openEHR logo

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
openEHR components
© 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

image Creative Commons Attribution-NoDerivs 3.0 Unported. https://creativecommons.org/licenses/by-nd/3.0/

Support

Issues: Problem Reports
Web: specifications.openEHR.org

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

Original IP

A significant part of the content of this specification was adapted from the Better (Marand) 'Web Templates' specification, kindly provided by Marand d.o.o. (Slovenia) and the EtherCIS JSON flat format description.

Trademarks

  • 'openEHR' is a registered trademark of the openEHR Foundation

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.

1.4. Conformance

TBD: xxxx

1.5. Tooling

TBD: xxxx

2. Overview

2.1. Design Concept

The Serial Data Formats (SDF) define compact serialisations for:

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.

2.2. Variant forms and Rules for Mixing

TBD: xxxx

2.2.1. EhrScape Format

TBD: xxxx

2.3. Parsing Model

TBD: xxxx

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

Boolean

"true" | "false"

Integer

JSON integer

5
124000

Real

JSON number

5.0
6.023e23

String

JSON string

"mild anaemia"
"a line of text\n"

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

Character

JSON character

 
"k"
"\t"

Iso8601_date

ISO 8601 date string, including partial forms; see TIME_DEFINITIONS.valid_iso8601_date().

 
"2020-04-01"
"2020-04"
"2020"

Iso8601_time

ISO 8601 time string, including partial forms; see TIME_DEFINITIONS.valid_iso8601_time().

 
"13:45:00"
"13:45"
"13"
"13:45:00.722+03:00"
"13:45+03:00"

Iso8601_date_time

ISO 8601 date/time string, including partial forms; see TIME_DEFINITIONS.valid_iso8601_date_time().

 
"P2Y4M10D"
"P1DT3H"
"PT2h5m0s"

Iso8601_duration

ISO 8601 duration string; see TIME_DEFINITIONS.valid_iso8601_duration().

 
"P2Y4M10D"
"P1DT3H"
"PT2h5m0s"

Uri

RFC 3986 string

 
"https://www.openEHR.org"
"http://snomed.info"

Terminology_code

openEHR ODIN TERM_CODE_REF, defined as "[<terminology_id>::<code>]" | "[<terminology_id>(<version_id>)::<code>]"

 
"[icd10AM::F60.1]"
"[snomed_ct(2020_06_01)::3415004]"

Terminology_term

openEHR ODIN XXXX, defined as "[<terminology_id>::<code>|<text>|]" | "[<terminology_id>(<version_id>)::<code>|<text>|]"

 
"[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.2.1. EhrScape Variants

EhrScape variants exist for the following types.

Formal type EhrScape Format

Terminology_code

 
{
    "|code": "238",
    "|terminology": "openehr"
}

Terminology_term

 
{
    "|code": "238",
    "|value": "other care",
    "|terminology": "openehr"
}

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

DV_BOOLEAN

See Boolean

CODE_PHRASE

See Terminology_code

DV_TEXT

See String

DV_CODED_TEXT

See Terminology_term

DV_COUNT

See Integer

DV_DATE

See Iso8601_date

DV_DATE_TIME

See Iso8601_date_time

DV_TIME

See Iso8601_time

DV_DURATION

See Iso8601_duration

DV_EHR_URI

See Uri

The DATA_VALUE types that have specific SDF syntax forms are shown in the following table.

Formal type Definition Example

DV_ORDINAL

"<ordinal_value>|<terminology_code>" |
"<ordinal_value>|<terminology_term>"

"1|[snomed_ct::313267000|Stroke|]"

DV_SCALE

"<scale_value>|<terminology_code>" |
"<scale_value>|<terminology_term>"

"1.5|[snomed_ct::127840596|minor difficulty|]"

DV_QUANTITY

"<value>,<unit>"

"78.500,kg"

DV_PROPORTION

"<numerator>/<denominator>;<proportion_kind>" where is <proportion_kind> is RATIO | UNITARY | PERCENT | FRACTION | INTEGER_FRACTION

"25.3/100;PERCENT"

DV_MULTIMEDIA

Standard JSON structure with compressed items internally

 
{
    "integrityCheckAlgorithm": "[openehr_integrity_check_algorithms::SHA-1]",
    "mediaType": "IANA_media-types::text/plain",
    "compressionAlgorithm": "[openehr_compression_algorithms::other]",
    "uri": "file://test.ethercis.com/dir/file.jpg"
}

DV_PARSABLE

CHECK

CHECK

DV_IDENTIFIER

Standard JSON

 
{
    "id": "id1",
    "issuer": "issuer1",
    "assigner": "assigner1",
    "type": "PERSON"
}

DV_INTERVAL<T:DV_ORDERED>

CHECK

CHECK

3.5.1. EhrScape Variants

EhrScape variants exist for the following DV_ types.

Formal type EhrScape Format

DV_PARSABLE

 
{
    "|value": "Hello world!",
    "|formalism": "text/plain"
}

DV_MULTIMEDIA

 
{
    "|integrityCheckAlgorithm": "[openehr_integrity_check_algorithms::SHA-1]",
    "|mediaType": "IANA_media-types::text/plain",
    "|compressionAlgorithm": "[openehr_compression_algorithms::other]",
    "|uri": "file://test.ethercis.com/dir/file.jpg"
}

DV_IDENTIFIER

 
{
    "|id": "id1",
    "|issuer": "issuer1",
    "|assigner": "assigner1",
    "|type": "PERSON"
}

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
    ;

4.2. String Parser

TBD: define

5. Amendment Record

Issue Details Raiser Completed

SM Release 1.0.0 (unreleased)

0.5.0

SPECSM-5. Add Simplified Data Formats (SDF)
Initial writing, adapted from the Better Platform 'Web Templates' specification and EtherCIS documentation.

openEHR SEC

27 Aug 2020