Definition API (latest)

Specifications Editorial Committee openEHR: info@openehr.org URL: https://specifications.openehr.org/ License: Creative Commons Attribution-NoDerivs 3.0 Unported

© 2003 - 2022 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 Web: specifications.openEHR.org

Amendment Record

Issue	Details	Raiser, Implementer	Completed
Release-1.0.3
5.1	SPECITS-66: Migrate REST API specs to 'openAPI' format	S Iancu	19 Dec 2022
Release-1.0.2
4.2	SPECITS-59: Specify mimeType used by adl2 template	S Iancu	26 Mar 2021
4.1	SPECITS-42: Fix TEMPLATE_ID value format in examples	S Iancu	21 Mar 2021
4.1	SPECITS-41: Add double quotes to ETag and If-Match headers	S Iancu	21 Mar 2021
4.0	SPECITS-57: Updating request and response examples of GET adl1.4 template in relation with headers about simplified JSON formats	E Sundvall, S Iancu	13 Mar 2021
Release-1.0.1
3.0	SPECITS-32: Fix typos and minor documentary errors (fixes SPECPR-253, SPECPR-289)	J Smolka, P Pazos, E Sundvall, T Beale, S Iancu	1 Sep 2019
2.2	SPECITS-24: Added changelog	J Smolka, S Iancu	12 May 2019
	SPECITS-25, SPECITS-29: Change layout and structure	J Smolka, S Iancu	12 May 2019
2.1	Update links to new openEHR specifications website	S Iancu	16 Dec 2018
Release-1.0.0

Intro

Acknowledgements

Editor

Sebastian Iancu, Architect, Code24, Netherlands

Contributors

This specification benefited from wide formal and informal input from the openEHR and wider health informatics community. The openEHR Foundation would like to recognise the following people for their contributions.

Birger Haarbrandt, MSc, Peter L. Reichertz Institut for Medical Informatics (PLRI), Germany
Bjørn Næss, DIPS, Norway
Bostjan Lah, Senior Architect, Better, Slovenia
Erik Sundvall, Information Architect at Karolinska University Hospital, Sweden
Heath Frankel, Ocean Informatics, Australia
Ian McNicoll MD, FreshEHR, UK
Jake Smolka, Software Engineer, Better, Slovenia
Matija Polajnar, PhD, Software Engineer, Better, Slovenia
Pablo Pazos Gutierrez, Senior engineer, CaboLabs, Uruguay
Rong Chen MD, PhD, Cambio Healthcare Systems, Sweden
Sebastian Iancu, Architect, Code24, Netherlands
Seref Arikan, MEcon, Ocean Informatics UK, Centre for Health Informatics and Multi-professional Education (CHIME) UK
Thomas Beale, Ars Semantica UK, openEHR Foundation Management Board

Trademarks

'openEHR' is a trademark of the openEHR Foundation
'OpenAPI' is a trademark of the The Linux Foundation

Preface

Purpose

This specification describes service endpoints, resources and operations as well as details of requests and responses that interacts with Definition openEHR API in a RESTful manner.

Prerequisite documents for reading this document include:

The Operational Template 2
The Archetype Query Language(AQL)

Status

This specification is in the STABLE state, and can be downloaded as OpenAPI specification file (in YAML format) for validation, or for code generators. Users are encouraged to comment on and/or advise on these paragraphs as well as the main content.

The development version of this document can be found at https://specifications.openehr.org/releases/ITS-REST/latest/definition.html.

Feedback

Feedback may be provided on the Implementation Technology Specifications forum.

Issues may be raised on the specifications Problem Report tracker.

To see changes made due to previously reported issues, see the ITS component Change Request tracker.

Conformance

tbd.

ADL1.4 TEMPLATE

Management of AOM and ADL 1.4 Operational Templates (OPTs). These templates can be created using modelling tools such as the Template Designer and the Archetype Designer.

Operational templates simplify the creation of openEHR-based input or storage implementations by, for a specific COMPOSITION template (use case), collecting all labels, requirements and constraints from all contained archetypes and sub-templates into a single easily parsed file. This file can be a basis for UI-generation/creation and for data validation.

Upload a template

Upload a new ADL 1.4 operational template (OPT).

header Parameters

Prefer

string

Default: return=minimal

Enum: "return=representation" "return=minimal"

Request header to indicate the preference over response details. The response will contain the entire resource when the Prefer header has a value of return=representation.

Request Body schema: application/xml

One of

object (OPERATIONAL_TEMPLATE)

Responses

Request samples

Payload

Content type

application/xml

<template xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.openehr.org/v1">
    <language>
        <terminology_id>
            <value>ISO_639-1</value>
        </terminology_id>
        <code_string>en</code_string>
    </language>
    <description>
        <original_author id="Original Author">Not Specified</original_author>
        <lifecycle_state>Initial</lifecycle_state>
        <other_details id="MetaDataSet:Sample Set ">Template metadata sample set</other_details>
        <other_details id="Acknowledgements"></other_details>
        <other_details id="Business Process Level"></other_details>
        <other_details id="Care setting"></other_details>
        <other_details id="Client group"></other_details>
        <other_details id="Clinical Record Element"></other_details>
        <other_details id="Copyright"></other_details>
        <other_details id="Issues"></other_details>
        <other_details id="Owner"></other_details>
        <other_details id="Sign off"></other_details>
        <other_details id="Speciality"></other_details>
        <other_details id="User roles"></other_details>
        <details>
            <language>
                <terminology_id>
                    <value>ISO_639-1</value>
                </terminology_id>
                <code_string>en</code_string>
            </language>
            <purpose>Not Specified</purpose>
        </details>
    </description>
    <uid>
        <value>b4d7f203-b329-4e89-a58a-c605b19e94de</value>
    </uid>
    <template_id>
        <value>Vital Signs</value>
    </template_id>
    <concept>Vital Signs</concept>
    <definition>
        <rm_type_name>COMPOSITION</rm_type_name>
        <occurrences>
            <lower_included>true</lower_included>
            <upper_included>true</upper_included>
            <lower_unbounded>false</lower_unbounded>
            <upper_unbounded>false</upper_unbounded>
            <lower>1</lower>
            <upper>1</upper>
        </occurrences>
        <node_id>at0000</node_id>
        ...

List templates

List the available ADL 1.4 operational templates (OPT) on the system.

Responses

Response samples

200

Content type

application/json

[{"template_id": "Vital Signs",
"concept": "Vital Signs",
"archetype_id": "openEHR-EHR-COMPOSITION.encounter.v1",
"created_timestamp": "2017-08-14T19:24:56.639Z"
}
]

Get a template

Retrieves the ADL 1.4 operational template (OPT) identified by template_id identifier.

Note that this can return either the original (canonical) XML based OPT format (if called with the Accept: application/xml request header), as well as the simplified JSON-based “web template” format (if called with the Accept: application/openehr.wt+json request header). For more details see the data representation specification.

path Parameters

template_id

required

string

Example: Vital Signs

Template identifier.

header Parameters

Accept

required

string

Enum: "application/json" "application/xml" "text/plain" "application/openehr.wt+json"

Example: application/xml

Header to indicate the expected response format.

Responses

Response samples

200

Content type

application/xml

<template xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.openehr.org/v1">
    <language>
        <terminology_id>
            <value>ISO_639-1</value>
        </terminology_id>
        <code_string>en</code_string>
    </language>
    <description>
        <original_author id="Original Author">Not Specified</original_author>
        <lifecycle_state>Initial</lifecycle_state>
        <other_details id="MetaDataSet:Sample Set ">Template metadata sample set</other_details>
        <other_details id="Acknowledgements"></other_details>
        <other_details id="Business Process Level"></other_details>
        <other_details id="Care setting"></other_details>
        <other_details id="Client group"></other_details>
        <other_details id="Clinical Record Element"></other_details>
        <other_details id="Copyright"></other_details>
        <other_details id="Issues"></other_details>
        <other_details id="Owner"></other_details>
        <other_details id="Sign off"></other_details>
        <other_details id="Speciality"></other_details>
        <other_details id="User roles"></other_details>
        <details>
            <language>
                <terminology_id>
                    <value>ISO_639-1</value>
                </terminology_id>
                <code_string>en</code_string>
            </language>
            <purpose>Not Specified</purpose>
        </details>
    </description>
    <uid>
        <value>b4d7f203-b329-4e89-a58a-c605b19e94de</value>
    </uid>
    <template_id>
        <value>Vital Signs</value>
    </template_id>
    <concept>Vital Signs</concept>
    <definition>
        <rm_type_name>COMPOSITION</rm_type_name>
        <occurrences>
            <lower_included>true</lower_included>
            <upper_included>true</upper_included>
            <lower_unbounded>false</lower_unbounded>
            <upper_unbounded>false</upper_unbounded>
            <lower>1</lower>
            <upper>1</upper>
        </occurrences>
        <node_id>at0000</node_id>
        ...

ADL2 TEMPLATE

Management of AOM2 templates.

Upload a template

Upload a new ADL2 operational template.

query Parameters

version

string

Example: version=1.0.1

A SEMVER version number. Query parameter to indicate the desired version associated with the request.

header Parameters

Prefer

string

Default: return=minimal

Enum: "return=representation" "return=minimal"

Request header to indicate the preference over response details. The response will contain the entire resource when the Prefer header has a value of return=representation.

Request Body schema: text/plain

One of

object (OPERATIONAL_TEMPLATE_V2)

Responses

Request samples

Payload

Content type

text/plain

operational_template (adl_version=2.0.6; rm_release=1.0.2; generated)
    openEHR-EHR-COMPOSITION.t_clinical_info_ds_sf.v1.0.0

specialize
    openEHR-EHR-COMPOSITION.discharge.v1

language
    original_language = <[ISO_639-1::en]>

description
    lifecycle_state = <"unmanaged">
    original_author = <
        ["name"] = <"Ian McNicoll">
        ["organisation"] = <"openEHR Foundation">
        ["email"] = <"ian.mcnicoll@openehr.org">
...

List templates

List the available ADL2 operational templates on the system.

Responses

Response samples

200

Content type

application/json

[{"template_id": "openEHR-EHR-COMPOSITION.t_clinical_info_ds_sf.v1.0.0",
"version": "1.0.1",
"concept": "Clinical detail",
"archetype_id": "openEHR-EHR-COMPOSITION.discharge.v1",
"created_timestamp": "2017-08-14T19:24:56.639Z"
},
{"template_id": "openEHR-EHR-COMPOSITION.t_vital_signs.v1.0.0",
"version": "1.0.1",
"concept": "Vital Signs",
"archetype_id": "openEHR-EHR-COMPOSITION.encounter.v1",
"created_timestamp": "2017-08-14T19:24:56.639Z"
}
]

Get a template

Retrieves the latest version of the ADL2 operational template identified by template_id identifier.

path Parameters

template_id

required

string

Example: Vital Signs

Template identifier.

Responses

Response samples

200

Content type

text/plain

operational_template (adl_version=2.0.6; rm_release=1.0.2; generated)
    openEHR-EHR-COMPOSITION.t_clinical_info_ds_sf.v1.0.0

specialize
    openEHR-EHR-COMPOSITION.discharge.v1

language
    original_language = <[ISO_639-1::en]>

description
    lifecycle_state = <"unmanaged">
    original_author = <
        ["name"] = <"Ian McNicoll">
        ["organisation"] = <"openEHR Foundation">
        ["email"] = <"ian.mcnicoll@openehr.org">
...

Get a template at version

Retrieves the ADL2 operational template identified by template_id identifier, at specified version.

path Parameters

template_id required	string Example: Vital Signs Template identifier.
version required	string Example: 1.0 A SEMVER version number. This can be a an exact version (e.g. `1.7.1`), or a pattern as partial prefix, in a form of `{major}` or `{major}.{minor}` (e.g. `1` or `1.0`), in which case the highest (latest) version matching the prefix will be considered.

Responses

Response samples

200

Content type

text/plain

operational_template (adl_version=2.0.6; rm_release=1.0.2; generated)
    openEHR-EHR-COMPOSITION.t_clinical_info_ds_sf.v1.0.0

specialize
    openEHR-EHR-COMPOSITION.discharge.v1

language
    original_language = <[ISO_639-1::en]>

description
    lifecycle_state = <"unmanaged">
    original_author = <
        ["name"] = <"Ian McNicoll">
        ["organisation"] = <"openEHR Foundation">
        ["email"] = <"ian.mcnicoll@openehr.org">
...

Stored Query

Management of stored (registered) queries in the system. Actions upon resources of this group are also formally described in the I_DEFINITION_QUERY Abstract Service Model interface.

Stored queries are identified by their qualified name and version. They can be executed using the query endpoint.

List stored queries

Retrieves list of all stored queries on the system matched by qualified_query_name as pattern.

If pattern should given be in the format of [{namespace}::]{query-name}, and when is empty, it will be treated as "wildcard" in the search.

Examples:

GET https://openEHRSys.example.com/v1/definition/query/org.openehr will list all versions of all queries with names starting with org.openehr
GET https://openEHRSys.example.com/v1/definition/query/org.openehr::compositions will list all versions of the query named org.openehr::compositions

path Parameters

qualified_query_name

required

string (QueryName)

Example: org.openehr::compositions

The (fully qualified) name of the query to be executed, in a format of [{namespace}::]{query-name}.

Responses

Response samples

200

Content type

application/json

[{"name": "org.openehr::compositions",
"type": "aql",
"version": "1.0.1",
"saved": "2017-07-16T19:20:30.450+01:00",
"q": "SELECT c  FROM EHR e[ehr_id/value=$ehr_id] \n  CONTAINS COMPOSITION c[$compositionid] \nWHERE c/name/value = 'Vitals'"
},
{"name": "org.openehr::compositions",
"type": "aql",
"version": "1.1.7",
"saved": "2018-06-13T09:37:20.530+01:00",
"q": "SELECT c  FROM EHR e[ehr_id/value=$ehr_id] \n  CONTAINS COMPOSITION c[$uid] \nWHERE c/name/value = 'Vitals'"
}
]

Store a query

Stores a new query, or updates an existing query on the system.

path Parameters

qualified_query_name

required

string (QueryName)

Example: org.openehr::compositions

The (fully qualified) name of the query to be executed, in a format of [{namespace}::]{query-name}.

query Parameters

query_type

string

Default: "AQL"

Example: query_type=AQL

Parameter indicating the query language/type.

Request Body schema: text/plain

string (AQL)

The given AQL query.

Responses

Request samples

Payload

Content type

text/plain

SELECT c FROM
  EHR e
    CONTAINS COMPOSITION c[openEHR-EHR-COMPOSITION.encounter.v1]
      CONTAINS OBSERVATION obs[openEHR-EHR-OBSERVATION.blood_pressure.v1]
WHERE
  obs/data[at0001]/events[at0006]/data[at0003]/items[at0004]/value/magnitude >= $systolic_bp

Store a query version

Stores a query, at a specified version, on the system.

path Parameters

qualified_query_name required	string (QueryName) Example: org.openehr::compositions The (fully qualified) name of the query to be executed, in a format of `[{namespace}::]{query-name}`.
version required	string Example: 1.0 A SEMVER version number. This can be a an exact version (e.g. `1.7.1`), or a pattern as partial prefix, in a form of `{major}` or `{major}.{minor}` (e.g. `1` or `1.0`), in which case the highest (latest) version matching the prefix will be considered.

query Parameters

query_type

string

Default: "AQL"

Example: query_type=AQL

Parameter indicating the query language/type.

Request Body schema: text/plain

string (AQL)

The given AQL query.

Responses

Request samples

Payload

Content type

text/plain

SELECT c FROM
  EHR e
    CONTAINS COMPOSITION c[openEHR-EHR-COMPOSITION.encounter.v1]
      CONTAINS OBSERVATION obs[openEHR-EHR-OBSERVATION.blood_pressure.v1]
WHERE
  obs/data[at0001]/events[at0006]/data[at0003]/items[at0004]/value/magnitude >= $systolic_bp

Get stored query at version

Retrieves the definition of a particular stored query (at specified version) and its associated metadata.

path Parameters

qualified_query_name required	string (QueryName) Example: org.openehr::compositions The (fully qualified) name of the query to be executed, in a format of `[{namespace}::]{query-name}`.
version required	string Example: 1.0 A SEMVER version number. This can be a an exact version (e.g. `1.7.1`), or a pattern as partial prefix, in a form of `{major}` or `{major}.{minor}` (e.g. `1` or `1.0`), in which case the highest (latest) version matching the prefix will be considered.

Responses

Response samples

200

Content type

application/json

{"name": "org.openehr::compositions",
"type": "aql",
"version": "1.0.1",
"saved": "2017-07-16T19:20:30.450+01:00",
"q": "SELECT c FROM EHR e[ehr_id/value=$ehr_id] CONTAINS COMPOSITION c[$compositionid] WHERE c/name/value = 'Vitals'"
}

Template list

This resource represents the list of Template meta-information associated with uploaded templates - see also Service Model - Definition Package.

Array

template_id required	string
version	string
concept required	string
archetype_id required	string
created_timestamp required	string

[{"template_id": "openEHR-EHR-COMPOSITION.t_vital_signs.v1.0.0",
"version": "1.0.1",
"concept": "Vital Signs",
"archetype_id": "openEHR-EHR-COMPOSITION.encounter.v1",
"created_timestamp": "2017-08-14T19:24:56.639Z"
}
]

Template

The following resources are formally specified in the Archetype Model as AOM/ADL 1.4 Operational Templates (OPTs) and as AOM2 templates.

The AOM/ADL 1.4 OPERATIONAL_TEMPLATE resource:

object (OPERATIONAL_TEMPLATE)

{ }

The AOM/ADL 2 OPERATIONAL_TEMPLATE resource:

object (OPERATIONAL_TEMPLATE_V2)

{ }

The WebTemplate alternative resource:

templateId required	string
version required	string
defaultLanguage required	string
languages required	Array of strings
required	object (Tree)

{"templateId": "string",
"version": "string",
"defaultLanguage": "string",
"languages": ["string"
],
"tree": {"id": "string",
"name": "string",
"localizedName": "string",
"rmType": "string",
"nodeId": "string",
"min": 0,
"max": 0,
"localizedNames": {"en": "Vital Signs"
},
"localizedDescriptions": {"sl": "Generic encounter or progress note composition"
},
"aqlPath": "string",
"children": [{"id": "context",
"rmType": "EVENT_CONTEXT",
"nodeId": "",
"min": 1,
"max": 1,
"aqlPath": "/context",
"children": [{"id": "context_detail",
"name": "Context detail",
"localizedName": "Context detail",
"rmType": "CLUSTER",
"nodeId": "openEHR-EHR-CLUSTER.context_detail.v1",
"min": 0,
"max": -1,
"localizedNames": {"sl": "Podrobnosti"
},
"localizedDescriptions": {"sl": "Dodatni podatki o kontekstu"
},
"aqlPath": "/context/other_context[at0001]/items[openEHR-EHR-CLUSTER.context_detail.v1]",
"children": [{"id": "tags",
"name": "Tags",
"localizedName": "Tags",
"rmType": "DV_TEXT",
"nodeId": "at0008",
"min": 1,
"max": -1,
"localizedNames": {"sl": "Tagi"
},
"localizedDescriptions": {"sl": "*"
},
"annotations": {"comment": "Tags applied to the composition. They can contain various ids, such as episode id, central case id or other types of information forming composition meta-data."
},
"aqlPath": "/context/other_context[at0001]/items[openEHR-EHR-CLUSTER.context_detail.v1]/items[at0008]/value",
"inputs": [{"type": "TEXT"
}
]
}
]
},
{"id": "start_time",
"name": "Start_time",
"rmType": "DV_DATE_TIME",
"min": 0,
"max": 1,
"aqlPath": "/context/start_time",
"inputs": [{"type": "DATETIME"
}
],
"inContext": true
},
{"id": "setting",
"name": "Setting",
"rmType": "DV_CODED_TEXT",
"min": 0,
"max": 1,
"aqlPath": "/context/setting",
"inputs": [{"suffix": "code",
"type": "TEXT"
},
{"suffix": "value",
"type": "TEXT"
}
],
"inContext": true
}
]
}
]
}
}

Stored Query

This resource represents the definition of a stored Query and is formally specified in the Service Model as Registered Queries.

name required	string (QueryName) The (fully qualified) name of the query (when is registered as a stored query), in a format of `[{namespace}::]{query-name}`. The `namespace` prefix is optional, and when used it should be in a form of a reverse domain name.
type required	string (QueryType) Default: "AQL" Query formalism type.
version required	string (QueryVersion) The SEMVER version number of the Stored Query.
saved required	string <date-time>
q required	string (AQL) The given AQL query.

{"name": "org.openehr::compositions",
"type": "aql",
"version": "1.0.1",
"saved": "2017-07-16T19:20:30.450+01:00",
"q": "SELECT c FROM EHR e[ehr_id/value=$ehr_id] CONTAINS COMPOSITION c[$compositionid] WHERE c/name/value = 'Vitals'"
}

Definition API (latest)

Amendment Record

Intro

Acknowledgements

Editor

Contributors

Trademarks

Preface

Purpose

Related Documents

Status

Feedback

Conformance

ADL1.4 TEMPLATE

Upload a template

header Parameters

Request Body schema: application/xml

Responses

Request samples

List templates

Responses

Response samples

Get a template

path Parameters

header Parameters

Responses

Response samples

ADL2 TEMPLATE

Upload a template

query Parameters

header Parameters

Request Body schema: text/plain

Responses

Request samples

List templates

Responses

Response samples

Get a template

path Parameters

Responses

Response samples

Get a template at version

path Parameters

Responses

Response samples

Stored Query

List stored queries

path Parameters

Responses

Response samples

Store a query

path Parameters

query Parameters

Request Body schema: text/plain

Responses

Request samples

Store a query version

path Parameters

query Parameters

Request Body schema: text/plain

Responses

Request samples

Get stored query at version

path Parameters

Responses

Response samples

Template list

Template

Stored Query