openEHR Serial Data Formats (SDF)
Issuer: openEHR Specification Program | |
---|---|
Release: SM development |
Status: DEVELOPMENT |
Revision: [latest_issue] |
Date: [latest_issue_date] |
Keywords: SDF, serialization, openEHR |
© 2020 - 2024 The openEHR Foundation | |
---|---|
The openEHR Foundation is an independent, non-profit foundation, facilitating the sharing of health records by consumers and clinicians via open specifications, clinical models and open platform implementations. |
|
Licence |
Creative Commons Attribution-NoDerivs 3.0 Unported. https://creativecommons.org/licenses/by-nd/3.0/ |
Support |
Issues: Problem Reports |
Acknowledgements
Authors
-
Pieter Bos, Software Engineer, Nedap, Netherlands
-
Diego Boscá, IBIME, Technical University Valencia, VeraTech for Health, Spain
-
Borut Fabjan, Program Manager, Better, Slovenia
-
Sebastian Iancu, Architect, Code24, Netherlands
-
Bostjan Lah, CTO, Better, Slovenia
-
Ian McNicoll MD, MSc, FreshEhr, UK
-
Matija Polajnar, Architect, Better, Slovenia
1. Preface
1.1. Purpose
This document describes the Serial data formats, a set of serialisations for openEHR RM data, intended to be used to generate simplified Data Templates.
1.2. Status
This specification is in the DEVELOPMENT state. The development version of this document can be found at https://specifications.openehr.org/releases/SM/development/serial_data_formats.html.
Known omissions or questions are indicated in the text with a 'to be determined' paragraph, as follows:
TBD: (example To Be Determined paragraph)
1.3. Feedback
Feedback may be provided on the technical mailing list.
Issues may be raised on the specifications Problem Report tracker.
To see changes made due to previously reported issues, see the SM component Change Request tracker.
2. Overview
2.1. Design Concept
The Serial Data Formats (SDF) define compact serialisations for:
-
the openEHR Foundation Types and
The intention is twofold:
-
to reduce the size and increase the human-readability of JSON-serialised openEHR data;
-
to make generation of openEHR data easier.
The formats defined in this specification are mostly re-used from elsewhere in openEHR, and may be expected to be implemented in a standard library for each major implementation technology.
3. Data Values
3.1. JSON Primitives
The following JSON primitive types are a subset of the openEHR Foundation Types, and are represented in SDF in their native JSON form.
Formal type | Definition | Example |
---|---|---|
|
|
|
|
5 |
|
|
5.0 |
|
|
"mild anaemia" |
3.2. openEHR Primitives Represented as JSON String
The following are openEHR primitive types represented as JSON Strings which may be parsed to instantiate the appropriate data type.
Formal type | Definition | Example |
---|---|---|
|
"k" "\t" |
|
|
ISO 8601 date string, including partial forms; see |
"2020-04-01" "2020-04" "2020" |
|
ISO 8601 time string, including partial forms; see |
"13:45:00" "13:45" "13" "13:45:00.722+03:00" "13:45+03:00" |
|
ISO 8601 date/time string, including partial forms; see |
"P2Y4M10D" "P1DT3H" "PT2h5m0s" |
|
ISO 8601 duration string; see |
"P2Y4M10D" "P1DT3H" "PT2h5m0s" |
|
"https://www.openEHR.org" "http://snomed.info" |
|
|
openEHR ODIN TERM_CODE_REF, defined as |
"[icd10AM::F60.1]" "[snomed_ct(2020_06_01)::3415004]" |
|
openEHR ODIN XXXX, defined as |
"[icd10AM::F60.1|Schizoid personality disorder|]" "[snomed_ct(2020_06_01)::3415004|cyanosis|]" |
TBD: S.I.: there is no support for version_id in Terminology_code / Terminology_term, or value in Terminology_term.
3.3. openEHR Intervals Represented as JSON String
Data instances of type Interval<T: Ordered>
, where the concrete descendants of Ordered
are shown in the openEHR Foundation Types are represented in SDF templates as JSON Strings containing openEHR ODIN intervals, for example "|08:02 .. 09:10|"
.
The interval syntax is summarised as follows:
|N .. M| -- the two-sided range N >= x <= M; |> N .. M| -- the two-sided range N > x <= M; |N .. <M| -- the two-sided range N <= x <M; |> N .. <M| -- the two-sided range N > x <M; |< N| -- the one-sided range x < N; |> N| -- the one-sided range x > N; |>= N| -- the one-sided range x >= N; |<= N| -- the one-sided range x <= N; |N +/-M| -- interval of N ±M; |N±M| -- interval of N ±M.
Examples of this syntax include:
|0 .. 5| -- integer interval |0.0 .. 1000.0| -- real interval |0.0 .. <1000.0| -- real interval 0.0 <= x < 1000.0 |08:02 .. 09:10| -- interval of time |>= 1939-02-01| -- open-ended interval of dates |5.0 ±0.5| -- 4.5 ±5.5 |5.0 +/-0.5| -- 4.5 ±5.5 |>= 0| -- >= 0
3.4. Lists of Primitive Type and Intervals
Lists are represented in the standard JSON manner, with the elements represented as described above. The following shows various examples.
["cyan", "magenta", "yellow", "black"] [1, 1, 2, 3, 5] ["[icd10AM::F60.1]", "[icd10AM::F64.2]"]
3.5. openeHR Reference Model DATA_VALUE Types
All openEHR RM DATA_VALUE
types can be represented in SDF form. Many have the same representation as the Foundation types on which they are based and are assumed to be instantiated to the correct RM type by virtue of parsing within a model-available context. These are shown in the following table.
Formal type | Definition |
---|---|
|
See |
|
See |
|
See |
|
See |
|
See |
|
See |
|
See |
|
See |
|
See |
|
See |
The DATA_VALUE
types that have specific SDF syntax forms are shown in the following table.
Formal type | Definition | Example |
---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
Standard JSON structure with compressed items internally |
|
|
CHECK |
CHECK |
|
Standard JSON |
|
|
CHECK |
CHECK |
3.5.1. EhrScape Variants
EhrScape variants exist for the following DV_
types.
Formal type | EhrScape Format |
---|---|
|
|
|
|
|
|
4. Syntax Specification
The JSON syntax is formally specified in terms of a standard JSON parser, which will return native JSON objects, and a second-level JSON string parser, that will return structured SDF instances as described the specification in the previous section. The final instantiated type(s) will further depend on the formal type(s) in the model context.
TBD: provide Antlr4 files
4.1. JSON Syntax Elements
The following EBNF is the standard JSON parser production rules from JSON.org.
json =
element ;
value =
object
| array
| string
| number
| "true"
| "false"
| "null"
;
object =
'{' ws '}'
| '{' members '}'
;
members =
member
| member ',' members
;
member =
ws string ws ':' element ;
array =
'[' ws ']'
| '[' elements ']'
;
elements =
element
| element ',' elements
;
element =
ws value ws ;
string =
'"' characters '"' ;
characters =
""
| character characters
;
character =
'0020' - '10FFFF'
| '"' - '\'
| '\' escape
;
escape =
'"'
| '\'
| '/'
| 'b'
| 'f'
| 'n'
| 'r'
| 't'
| 'u' hex hex hex hex
;
hex =
digit
| 'A' - 'F'
| 'a' - 'f'
;
number =
integer fraction exponent ;
integer =
digit
| onenine digits
| '-' digit
| '-' onenine digits
;
digits =
digit
| digit digits
;
digit =
'0'
| onenine
;
onenine =
'1' - '9' ;
fraction =
""
| '.' digits
;
exponent =
""
| 'E' sign digits
| 'e' sign digits
;
sign =
""
| '+'
| '-'
;
ws =
""
| '0020' ws
| '000A' ws
| '000D' ws
| '0009' ws
;
5. Amendment Record
Issue | Details | Raiser | Completed |
---|---|---|---|
SM Release 1.0.0 (unreleased) |
|||
SPECSM-5. Add Simplified Data Formats (SDF) |
openEHR SEC |