Definition API (latest)
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.
Related Documents
Prerequisite documents for reading this document include:
Related documents include:
- The openEHR Architecture Overview
- The Archetype Technology Overview
- The openEHR Global Class Index
- The XML-Schemas (XSD)
- The JSON-Schemas and Simplified Formats
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/development/definition.html.
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" "return=identifier" Request header to indicate the preference over response details.
The response will contain the entire resource when the |
| Accept | string Enum: "application/json" "application/xml" "application/openehr.wt+json" |
| Content-Type | string Value: "application/xml" |
Request Body schema: application/xmlrequired
Responses
Request samples
- Payload
<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> ...
Response samples
- 201
- 400
List templates
List the available ADL 1.4 operational templates (OPT) on the system.
header Parameters
| Accept | string Value: "application/json" |
Responses
Response samples
- 200
[- {
- "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 | string Enum: "application/json" "application/xml" "application/openehr.wt+json" |
Responses
Response samples
- 200
- 400
<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> ...
Get example data by template
Generates and retrieves an example data instance based on an ADL 1.4 operational template (OPT) identified by the template_id parameter.
The generated example can be either of type input (i.e., ready to be submitted to the repository) or output (as it would appear when retrieved from the repository).
This behavior is controlled by the type query parameter.
The level of detail in the generated example can be customized using the detail_level query parameter.
It affects the number and complexity of nested elements, the inclusion or exclusion of optional elements, and the depth of data point details.
The supported values are:
required: a minimal composition including only mandatory data points; intended for training purposes and expected to be committable without adjustmentmedium: a fairly realistic set of data points, including some optional RM attributes and elements; intended to be committable (e.g., it should not contain more than one choice element, even if the template allows it)complete: a full representation of all possible data points; not expected to be committable or realistic, and intended as reference guidance for how parts of the RM should be represented
NOTE: The implementation and completeness of these examples are not specified, and vendors may produce different results. These examples are intended as pedagogical tools; their output should not be used in production.
When the server does not support the requested type or detail_level, it will fall back to the closest supported level, or it may return an error (typically 400 Bad Request).
The format of the returned data instance can be controlled via the Accept header. See the data representation specification for supported formats.tags:
path Parameters
| template_id required | string Example: Vital Signs Template identifier. |
query Parameters
| type | string Default: "input" Enum: "input" "output" Type of use for the data example. |
| detail_level | string Default: "required" Enum: "required" "medium" "complete" The level of data points details of the example. |
header Parameters
| Accept | string Enum: "application/json" "application/xml" "application/openehr.wt.flat+json" "application/openehr.wt.structured+json" |
Responses
Response samples
- 200
- 400
{- "archetype_node_id": "openEHR-EHR-COMPOSITION.encounter.v1",
- "name": {
- "value": "Vital Signs"
}, - "uid": {
- "_type": "OBJECT_VERSION_ID",
- "value": "8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1"
}, - "archetype_details": {
- "archetype_id": {
- "value": "openEHR-EHR-COMPOSITION.encounter.v1"
}, - "template_id": {
- "value": "Example.v1::c7ec861c-c413-39ff-9965-a198ebf44747"
}, - "rm_version": "1.0.2"
}, - "language": {
- "terminology_id": {
- "value": "ISO_639-1"
}, - "code_string": "en"
}, - "territory": {
- "terminology_id": {
- "value": "ISO_3166-1"
}, - "code_string": "NL"
}, - "category": {
- "value": "event",
- "defining_code": {
- "terminology_id": {
- "value": "openehr"
}, - "code_string": "433"
}
}, - "composer": {
- "_type": "PARTY_IDENTIFIED",
- "external_ref": {
- "id": {
- "_type": "GENERIC_ID",
- "value": "16b74749-e6aa-4945-b760-b42bdc07098a",
- "scheme": "pid"
}, - "namespace": "openEHRSys.example.com",
- "type": "PERSON"
}, - "name": "A name"
}, - "context": {
- "start_time": {
- "value": "2014-11-18T09:50:35.000+01:00"
}, - "setting": {
- "value": "other care",
- "defining_code": {
- "terminology_id": {
- "value": "openehr"
}, - "code_string": "238"
}
}
}, - "content": [ ]
}Management of AOM2 templates.
See also ADL2 Template specifications.
Upload a template
Upload a new ADL2 operational template.
query Parameters
| version | string Deprecated Example: version=1.0.1 |
header Parameters
| Prefer | string Default: return=minimal Enum: "return=representation" "return=minimal" "return=identifier" Request header to indicate the preference over response details.
The response will contain the entire resource when the |
| Accept | string Enum: "application/json" "application/xml" "text/plain" |
| Content-Type | string Value: "text/plain" |
Request Body schema: text/plainrequired
Responses
Request samples
- Payload
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"> ...
Response samples
- 400
{- "message": "Error message",
- "validationErrors": [
- "error1",
- "error2"
]
}List templates
List the available ADL2 operational templates on the system.
header Parameters
| Accept | string Value: "application/json" |
Responses
Response samples
- 200
[- {
- "template_id": "openEHR-EHR-COMPOSITION.t_clinical_info_ds_sf.v1.0.0",
- "version": "1.0.0",
- "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.1",
- "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. |
header Parameters
| Accept | string Enum: "application/json" "application/xml" "text/plain" |
Responses
Response samples
- 200
- 400
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 example data by template
Generates and retrieves an example data instance based on an ADL2 operational template (OPT) identified by the template_id parameter.
The generated example can be either an input type (ready for submission to the repository) or an output type (as it would appear when retrieved from the repository), controlled by the type parameter.
The level of detail in the generated example can be customized using the detail_level parameter, which affects:
- Number and complexity of nested elements
- Inclusion/exclusion of optional elements
- Depth of data point details
The format of the returned data instance can be controlled via the Accept header. See the data representation specification for supported formats.
path Parameters
| template_id required | string Example: Vital Signs Template identifier. |
query Parameters
| type | string Default: "input" Enum: "input" "output" Type of use for the data example. |
| detail_level | string Default: "required" Enum: "required" "medium" "complete" The level of data points details of the example. |
header Parameters
| Accept | string Enum: "application/json" "application/xml" "application/openehr.wt.flat+json" "application/openehr.wt.structured+json" |
Responses
Response samples
- 200
- 400
{- "archetype_node_id": "openEHR-EHR-COMPOSITION.encounter.v1",
- "name": {
- "value": "Vital Signs"
}, - "uid": {
- "_type": "OBJECT_VERSION_ID",
- "value": "8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1"
}, - "archetype_details": {
- "archetype_id": {
- "value": "openEHR-EHR-COMPOSITION.encounter.v1"
}, - "template_id": {
- "value": "Example.v1::c7ec861c-c413-39ff-9965-a198ebf44747"
}, - "rm_version": "1.0.2"
}, - "language": {
- "terminology_id": {
- "value": "ISO_639-1"
}, - "code_string": "en"
}, - "territory": {
- "terminology_id": {
- "value": "ISO_3166-1"
}, - "code_string": "NL"
}, - "category": {
- "value": "event",
- "defining_code": {
- "terminology_id": {
- "value": "openehr"
}, - "code_string": "433"
}
}, - "composer": {
- "_type": "PARTY_IDENTIFIED",
- "external_ref": {
- "id": {
- "_type": "GENERIC_ID",
- "value": "16b74749-e6aa-4945-b760-b42bdc07098a",
- "scheme": "pid"
}, - "namespace": "openEHRSys.example.com",
- "type": "PERSON"
}, - "name": "A name"
}, - "context": {
- "start_time": {
- "value": "2014-11-18T09:50:35.000+01:00"
}, - "setting": {
- "value": "other care",
- "defining_code": {
- "terminology_id": {
- "value": "openehr"
}, - "code_string": "238"
}
}
}, - "content": [ ]
}Get a template at version Deprecated
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. |
header Parameters
| Accept | string Enum: "application/json" "application/xml" "text/plain" |
Responses
Response samples
- 200
- 400
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"> ...
Management of stored (registered) queries in the system, including creation of new versions and retrieval by qualified name and version.
These endpoints enable registration and lifecycle management of reusable queries available for later execution.
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.openehrwill list all versions of all queries with names starting withorg.openehrGET https://openEHRSys.example.com/v1/definition/query/org.openehr::compositionswill list all versions of the query namedorg.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 |
header Parameters
| Accept | string Value: "application/json" |
Responses
Response samples
- 200
[- {
- "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 |
query Parameters
| query_type | string Default: "AQL" Example: query_type=AQL Parameter indicating the query language/type. |
header Parameters
| Accept | string Value: "application/json" |
| Content-Type | string Value: "text/plain" |
Request Body schema: text/plainrequired
The given AQL query.
Responses
Request samples
- Payload
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_bpResponse samples
- 400
{- "message": "Error message",
- "validationErrors": [
- "error1",
- "error2"
]
}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 |
| version required | string Example: 1.0 A SEMVER version number.
This can be a an exact version (e.g. |
query Parameters
| query_type | string Default: "AQL" Example: query_type=AQL Parameter indicating the query language/type. |
header Parameters
| Accept | string Value: "application/json" |
Request Body schema: text/plainrequired
The given AQL query.
Responses
Request samples
- Payload
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_bpResponse samples
- 400
{- "message": "Error message",
- "validationErrors": [
- "error1",
- "error2"
]
}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 |
| version required | string Example: 1.0 A SEMVER version number.
This can be a an exact version (e.g. |
header Parameters
| Accept | string Value: "application/json" |
Responses
Response samples
- 200
{- "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'"
}This resource represents the list of Template meta-information associated with uploaded templates, including identifiers, names, versions and related attributes that help clients discover available templates.
| template_id required | string |
| version | string Deprecated |
| concept required | string |
| archetype_id required | string |
| created_timestamp required | string |
[- {
- "template_id": "openEHR-EHR-COMPOSITION.t_vital_signs.v1.0.0",
- "concept": "Vital Signs",
- "archetype_id": "openEHR-EHR-COMPOSITION.encounter.v1",
- "created_timestamp": "2017-08-14T19:24:56.639Z"
}
]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:
{ }The AOM/ADL 2 OPERATIONAL_TEMPLATE resource:
{ }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
}
]
}
]
}
}This resource represents the definition of a stored query, including its qualified name, versioning and parameter declarations. Stored queries provide a reusable, immutable way to identify a specific AQL statement that can be executed later.
| name required | string (QueryName) The (fully qualified) name of the query (when is registered as a stored query), in a format of |
| 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'"
}