Definition API (latest)

Description

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:

Related documents include:

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.

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" "return=identifier"

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, or only the resource identifier (e.g., the uid) when the value is return=identifier.

Accept
string
Enum: "application/json" "application/xml" "application/openehr.wt+json"
Content-Type
string
Value: "application/xml"
Request Body schema: application/xml
required
One of
object (OPERATIONAL_TEMPLATE)

Responses

Request samples

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>
        ...

Response samples

Content type
No sample

List templates

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

header Parameters
Accept
string
Value: "application/json"

Responses

Response samples

Content type
application/json
[
  • {
    }
]

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

Content type
<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 adjustment
  • medium: 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

Content type
application/json
Example
{
  • "archetype_node_id": "openEHR-EHR-COMPOSITION.encounter.v1",
  • "name": {
    },
  • "uid": {
    },
  • "archetype_details": {
    },
  • "language": {
    },
  • "territory": {
    },
  • "category": {
    },
  • "composer": {
    },
  • "context": {
    },
  • "content": [ ]
}

ADL2 TEMPLATE

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 Prefer header has a value of return=representation, or only the resource identifier (e.g., the uid) when the value is return=identifier.

Accept
string
Enum: "application/json" "application/xml" "text/plain"
Content-Type
string
Value: "text/plain"
Request Body schema: text/plain
required
One of
object (OPERATIONAL_TEMPLATE_V2)

Responses

Request samples

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">
...

Response samples

Content type
application/json
{
  • "message": "Error message",
  • "validationErrors": [
    ]
}

List templates

List the available ADL2 operational templates on the system.

header Parameters
Accept
string
Value: "application/json"

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

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

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 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

Content type
application/json
Example
{
  • "archetype_node_id": "openEHR-EHR-COMPOSITION.encounter.v1",
  • "name": {
    },
  • "uid": {
    },
  • "archetype_details": {
    },
  • "language": {
    },
  • "territory": {
    },
  • "category": {
    },
  • "composer": {
    },
  • "context": {
    },
  • "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. 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.

header Parameters
Accept
string
Enum: "application/json" "application/xml" "text/plain"

Responses

Response samples

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, 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.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}. See Query Name for details on syntax.

header Parameters
Accept
string
Value: "application/json"

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

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}. See Query Name for details on syntax.

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/plain
required
string (AQL)

The given AQL query.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "message": "Error message",
  • "validationErrors": [
    ]
}

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}. See Query Name for details on syntax.

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.

header Parameters
Accept
string
Value: "application/json"
Request Body schema: text/plain
required
string (AQL)

The given AQL query.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "message": "Error message",
  • "validationErrors": [
    ]
}

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}. See Query Name for details on syntax.

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.

header Parameters
Accept
string
Value: "application/json"

Responses

Response samples

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, including identifiers, names, versions and related attributes that help clients discover available templates.

Array
template_id
required
string
version
string
Deprecated
concept
required
string
archetype_id
required
string
created_timestamp
required
string
[
  • {
    }
]

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": [
    ],
  • "tree": {
    }
}

Stored Query

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 [{namespace}::]{query-name}. See Query Name for details on syntax.

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'"
}