Overview (latest)

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

Purpose

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

Related Documents

Prerequisite documents for reading this document include:

• The openEHR Architecture Overview

Related documents include:

• The openEHR Global Class Index
• The XML-Schemas (XSD)
• The JSON-Schemas and Simplified Data Template (SDT)
• The openEHR Platform Abstract Service Model

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/overview.html.

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.

tbd.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC 2119], [RFC 8174] when, and only when, they appear in all capitals, as shown here.

Throughout this specification, a set of short terms is being used as described below:

Term	Description
API	Application Programmer Interface
REST	Representational state transfer, a type of Web service that allows clients to access and manipulate textual representations of Web resources.
OAS	An acronym for OpenAPI Specification
AQL	openEHR's Archetype Query Language
RM	openEHR's Reference Model
SEMVER	Semantic Versioning 2.0.0
UUID	A universally unique identifier as described by RFC 4122 (e.g. 8849182c-82ad-4088-a07f-48ead4180515)
ehr_id	The value for an EHR identifier, stored under EHR.ehr_id.value, in a form of a HIER_OBJECT_ID, usually an UUID or a GUID (e.g. 7d44b88c-4199-4bad-97dc-d78268e01398)
versioned_object_uid	The value of a VERSIONED_OBJECT unique identifier, stored under VERSIONED_OBJECT.uid.value, in a form of a HIER_OBJECT_ID (e.g. 8849182c-82ad-4088-a07f-48ead4180515)
version_uid	The value of a VERSION unique identifier, stored under VERSION.uid.value, in a form of an OBJECT_VERSION_ID (e.g. 8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::2)
uid_based_id	An abstract identifier: it can take a form of an OBJECT_VERSION_ID identifier taken from VERSION.uid.value (i.e. a version_uid), or a form of a HIER_OBJECT_ID identifier taken from VERSIONED_OBJECT.uid.value (i.e. a versioned_object_uid).
preceding_version_uid	The value of a previous VERSION unique identifier, used usually for PUT or DELETE methods (e.g. 8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1)
version_at_time	Time specifier used to retrieve the VERSION at a given time; the value is in the extended ISO 8601 format (e.g. 2015-01-20T19:30:22.765+01:00)

The openEHR REST specifications following service endpoints:

• System API
• EHR API
• Demographic API
• Query API
• Definition API
• Admin API

Specifications can be downloaded as YAML files in OpenAPI Specification 3.0 format. For each API there are two flavours provided:

• a file optimized for code generators, with the file name having the -codegen.openapi.yaml suffix; this file can be used with tools like OpenAPI Generator, or Swagger codegen,
• a file optimized for data validation, with the file name having the -validation.openapi.yaml suffix; this file can be used by (mock-)servers or applications to validate openEHR request and response payloads.

The main difference between these files (aside of schema model names) is that the codegen flavour is defining and using inheritance in model schemas, with the use of allOf property and discriminators, whereas the validation variant is flattening all these requirements (each model contains all RM-inherited properties), and is using oneOf property to define union-types. See Polymorphism specification.

The latest OpenAPI Specification files are available in GitHub at openEHR/specifications-ITS-REST/computable/OAS.

The following describes in details how HTTP headers and status codes MUST be used by an openEHR REST API implementation to ensure effective interaction between services and clients in accordance with this specification.

Additionally, general details about resources, data representation and content negotiation are described in this specification.

NOTE: Examples primarily use the JSON format. However, this does not imply that XML is unsupported by the same service endpoint.

HTTP Methods are described by RFC 9110. The following subset is used in this specification:

Method	Description
GET	Transfer a current representation of the target resource.
HEAD	Check existence of target resource and return the status, but does not transfer content.
POST	Perform resource-specific processing on the request payload.
PUT	Replace all current representations of the target resource with the request payload.
DELETE	Remove all current representations of the target resource.
OPTIONS	Describe the communication options for the target resource.

A server receiving an unrecognized or unimplemented method SHOULD respond with the 501 Not Implemented status code. If a method is recognized but not allowed for the target resource, the response SHOULD be 405 Method Not Allowed status code.

Services SHOULD implement and support an HTTP Authentication and Authorization framework, though this specification does not mandate a specific authentication scheme. See RFC 9110 or Mozilla's HTTP Authentication for details on implementing an authentication and authorization.

If authentication and authorization are required, services MUST properly use the WWW-Authenticate and/or Proxy-Authenticate response headers, returning 403 Forbidden, 401 Unauthorized or 407 Proxy Authentication as applicable. Clients MUST send valid Authorization and Proxy-Authorization headers in their requests when required.

Standard HTTP request and response headers are defined by RFC 9110 and the IANA Message Headers Registry.

This section outlines the subset of these headers used in the openEHR API, along with custom headers specific to openEHR.

Prior to Release 1.1.0, some openEHR custom headers included special characters that caused compatibility issues with HTTP standards. To ensure compliance and improve interoperability, these headers have been deprecated.

While the deprecated headers remain available for backward compatibility, their use is strongly discouraged. The table below lists the updated header names alongside their deprecated counterparts:

Deprecated header	New header
openEHR-VERSION	openehr-version
openEHR-AUDIT_DETAILS	openehr-audit-details
openEHR-TEMPLATE_ID	openehr-template-id
openEHR-uri	openehr-uri
openEHR-EHR-id	openehr-ehr-id

Some of the GET methods had a Location response header to indicate the canonical location of a representation. However, this was an incorrect use of the header, and it is now deprecated. Similarly, the Location response header was deprecated from responses of DELETE methods. For more information see Location header section.

The ETag response header was used without a weakness indicator W/. This is now deprecated, all ETag headers that holds a resource identifier MUST include a weakness indicator W/. For more information see ETag and Last-Modified section.

To ensure forward compatibility, clients are strongly encouraged to always include the Prefer request header explicitly. Although the current default behavior is equivalent to Prefer=minimal, this might change in the near future to Prefer=identifier. Explicitly stating the preference prevents unexpected behavior changes as the default evolves. For more information see Prefer only identifier section.

For long-term stability, all new implementations should adopt the updated header names and follow their prescribed usage.

When it comes to committing content to an openEHR system, for all change-controlled resources (e.g. COMPOSITION, EHR_STATUS, FOLDER, etc.) the services are performing versioning under the hood. The 'native' way of committing is to use a CONTRIBUTION and wrap the content as a VERSION. To keep things simpler and consistent, services MUST also allow PUT, POST and DELETE methods directly on these change-controlled resources. However, these operations MUST internally be executed using the 'native' way.

In order to allow clients to provide committal metadata, services MUST accept openehr-version and openehr-audit_details custom request headers. For clients, it is RECOMMENDED to provision these headers based on authentication and authorization runtime data. Below is a complex example of these request headers used in a PUT action to update a COMPOSITION:

openehr-version: lifecycle_state.code_string="532"
openehr-audit-details: change_type.code_string="251"
openehr-audit-details: description.value="An updated composition contribution description"
openehr-audit-details: committer.name="John Doe",committer.external_ref.id="BC8132EA-8F4A-11E7-BB31-BE2E44B06B34",committer.external_ref.namespace="demographic",committer.external_ref.type="PERSON"

None of these headers are mandatory, but whatever is provided it MUST be merged with the default VERSION and VERSION.audit_details attributes on commit runtime.

The list of code_string values and their meaning is specified by the Audit Change Type and Version Lifecycle State openEHR terminology vocabularies.

The openehr-item-tag and openehr-version-item-tag headers provide a lightweight mechanism for associating tags with change-controlled resources (e.g. COMPOSITION, EHR_STATUS, FOLDER, etc.).

• openehr-item-tag applies to VERSIONED_OBJECT targets.
• openehr-version-item-tag applies to a specific target VERSION within a VERSIONED_OBJECT.

Below is an example of these headers:

openehr-item-tag: key="category",value="final"
openehr-version-item-tag: key="reviewed",value="true"; key="flag",value="follow-up",target_path="/composition/start_time/value"

Both headers act as convenient wrappers around the dedicated ITEM_TAG operations (e.g. retrieving COMPOSITION tags), simplifying client interaction and reducing the number of API calls.

Tag values are provided as a list of key-value pairs, separated by semicolons. They both support the same syntax and schema, having the following attributes: key, value and target_path. More than one ITEM_TAG may be associated with a single target, in which case they are uniquely identified by their key and target_path pair attributes.

If the server does not support ITEM_TAGs, these headers will also be unsupported.

Usage in Requests

When used as request headers for creation or update operations (PUT, POST), the header instructs the system which ITEM_TAG list should be associated with the target VERSION or VERSIONED_OBJECT resource (depending on the header name).

Providing an empty value for this header will effectively remove all ITEM_TAGs associated with the given target.

Usage in Responses

Servers MAY include the openehr-item-tag or openehr-version-item-tag header in responses to confirm the actual list of ITEM_TAGs stored on the server side.

When retrieving resources via GET, the server MAY also add these headers to the response, containing the list of ITEM_TAGs associated with the target VERSION or VERSIONED_OBJECT (depending on the header name).

The openehr-template-id request header MUST be used whenever committing COMPOSITION (via PUT or POST methods) using a simplified data format which does not support TEMPLATE_ID value under an equivalent LOCATABLE.archetype_details.template_id attribute of contained data.

The Location header, as defined in RFC 9110, Section 10.2.2, is used by a server to indicate the URL of a newly created resource. In the openEHR REST API, it is used in 201 Created responses when a new resource is successfully created (e.g., via POST method). It MUST NOT be used to indicate an alternate representation of an existing resource (e.g. via GET method).

DEPRECATION: Prior to Release 1.1.0, the Location header was used to indicate the canonical location of a representation in a response. This usage is now deprecated. The Location header MUST ONLY be used for resource creation (e.g., 201 Created) or redirect responses.

Example of a Location response header:

HTTP/1.1 201 Created
Location: https://openEHRSys.example.com/v1/ehr/347a5490-55ee-4da9-b91a-9bba710f730e/composition/8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::2
Preference-Applied: return=minimal

If the service supports generating resource URIs in the format defined by the DV_EHR_URI class, it MAY include the openehr-uri response header for applicable openEHR resources.

Example:

HTTP/1.1 200 Ok
openehr-uri: ehr:/347a5490-55ee-4da9-b91a-9bba710f730e/compositions/87284370-2D4B-4e3d-A3F3-F303D2F4F34B

The Prefer request header MAY be used by clients to negotiate the format or content of the resource representation in the response. For more information, see the representation details negotiation section.

The ETag and Last-Modified headers provide essential information about the state of a resource, enabling clients to manage caching, detect changes, and prevent unintentional overwrites.

The ETag (Entity Tag) header acts as a unique identifier for a specific version of a resource. It helps clients determine whether a resource has changed between requests, supporting efficient caching and optimistic concurrency control.

In this specification, the ETag value is independent of its resource serialization format (JSON/XML). This differs from standard HTTP behavior, where an ETag typically identifies a specific representation of a resource - see RFC 9110. Therefore, the ETag are considered to be of weak-type and should have a weakness indicator W/ prefix.

DEPRECATION: Prior to Release 1.1.0, the ETag header was used without a weakness indicator W/. This usage is now deprecated, but implementations MAY still support it alongside the updated header format that includes the weakness indicator W/ prefix.

The ETag value is usually taken from e.g. VERSIONED_OBJECT.uid.value, VERSION.uid.value, EHR.ehr_id.value, etc. It changes as soon as the resource changes (i.e. when a new version is created).

An example of ETag header value format is:

HTTP/1.1 200 OK
ETag: W/"8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::2"

Servers MAY add additional ETag response headers, consisting of an opaque quoted string, possibly prefixed by a weakness indicator.

The Last-Modified response HTTP header, indicates the date and time when the resource was last modified. This helps clients determine freshness and manage conditional requests. For openEHR resources, this value should be derived from VERSION.commit_audit.time_committed.value.

An example of Last-Modified header value format is:

HTTP/1.1 200 OK
Last-Modified: Wed, 22 Jul 2009 19:15:56 GMT

Both ETag and Last-Modified SHOULD be included in responses for VERSION, VERSIONED_OBJECT, or other resources that have versioning or unique state identifiers.

The If-Match request header SHOULD be used by the clients with state-changing methods (e.g., PUT) to prevent accidental overwrites when multiple user agents might be acting in parallel on the same resource (i.e., to prevent the "lost update" problem). This is only required by a small set of versioned resources in this specification, when the preceding_version_uid is not part of the endpoint path segment. If a service receives this header, and the condition evaluates to false, it MUST NOT perform the requested method. Instead, it MUST respond with HTTP status code 412 Precondition Failed, and SHOULD return also latest version_uid in the ETag response headers. When the service expects If-Match for an operation, but the client does not provide it, the service SHOULD respond with 400 Bad Reequest.

Example:

If-Match: "8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::2"

See also details for If-Match described by RFC 9110.

HTTP Status codes are described by RFC 9110 and by the IANA Status Code Registry. The following subset of the is used in this specification:

Code	Reason-Phrase	Meaning, usecase and details
200	OK	The request succeeded, payload sent in a 200 response depends on the request method
201	Created	The request has been fulfilled and has resulted in one or more new resources being created
204	No content	The request has been fulfilled and there is no additional content to send in the response payload body
400	Bad request	The service cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, syntactically invalid content)
401	Unauthorized	If the service requires authorization, this indicates that the request has not been applied because it lacks valid authentication credentials for the target resource
403	Forbidden	The service understood the request but refuses to authorize it
404	Not found	The origin service did not find the target resource or is not willing to disclose that one exists
405	Method Not Allowed	The method received in the request-line is known by the origin service but not supported by the target resource
406	Not Acceptable	The target resource does not have a current representation that would be acceptable to the user
408	Request Timeout	Request maximum execution time is reached, therefore the server aborted the request
409	Conflict	Indicates that the request could not be processed because it might generate a duplicate or a conflict
412	Precondition Failed	One or more conditions given in the request header fields evaluated to false when tested on the server
415	Unsupported Media Type	The service is refusing the request because the payload is in a format not supported by this method on the target resource
422	Unprocessable Entity	The request was well-formed but was unable to be followed due to semantic errors
500	Internal Server Error	The service encountered an unexpected condition that prevented it from fulfilling the request
501	Not Implemented	The service does not support the functionality required to fulfill the request

To indicate the status of a request or operation, an appropriate HTTP status code MUST be used as described above. Additional status codes MAY be used as long as they do not conflict with the predefined codes.

Status code 400 indicates normally a bad request, as well as a generic client-side error, used when no other 4xx error code is appropriate. The client SHOULD NOT repeat the request without modifications.

For 4xx and 5xx status codes, services MAY return additional error details if the Prefer: return=representation header is present in the request. Example error response:

{
    "message": "Error message",
    "code": 90000,
    "errors": [
        {
            "_type": "DV_CODED_TEXT",
            "value": "Error message",
            "defining_code": {
                "terminology_id": {
                    "value": "local"
                },
                "code_string": "9000"
            }
        },
        {
            "_type": "DV_CODED_TEXT",
            "value": "Secondary error message",
            "defining_code": {
                "terminology_id": {
                    "value": "local"
                },
                "code_string": "8000"
            }
        }
    ]
}

When using POST, PUT, or DELETE to create, update, or delete a resource, the client can specify its preferred response format using the Prefer header, as defined in RFC 7240, Section 4.2.

The service MAY include a Preference-Applied header in the response, such as Preference-Applied: return=minimal or Preference-Applied: return=representation, to indicate that the client's preference has been honored.

If no Prefer header is provided, the default behavior is assumed to be return=minimal.

Clients MAY use the following preferences to control the verbosity of successful responses:

• Prefer: return=minimal
  Indicates the client prefers a minimal response. The response SHOULD include a Location header pointing to the newly created or updated resource. The HTTP status is typically 201 Created. If no response body is returned, the service SHOULD use 204 No Content.

• Prefer: return=identifier
  Indicates the client prefers a minimal response that includes only the identifier (e.g., the uid) of the affected resource. The response MAY include a Location header pointing to the newly created or updated resource. The HTTP status is typically 201 Created or 200 OK and the response body SHOULD contain only the identifier of the affected resource.

• Prefer: return=representation
  Indicates the client prefers a full resource representation in the response.
  The response MAY include a Location header, and the response body SHOULD contain the full representation of the resource. The HTTP status is typically 201 Created or 200 OK.

Clients MAY request a minimal response that includes only the identifier (e.g., the uid) of the affected resource by specifying:

PUT https://openEHRSys.example.com/v1/ehr/7d44b88c-4199-4bad-97dc-d78268e01398/composition/8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::2
Prefer: return=identifier
Accept: application/json

This is a variant of preference that implies minimal response semantics, but with a non-empty response body (i.e., the status will be 201 Created or 200 OK, never 204 No Content). The response body SHOULD contain only the identifier of the affected resource formatted according to the Accept request header. For example, when application/json is requested as above, the response body will be a single JSON object with a single uid attribute.

HTTP/1.1 200 OK
Preference-Applied: return=identifier
Content-Type: application/json
{ 
  "uid": "8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::3"
}

Notice: Although the current default behavior is return=minimal, some server implementations MAY provide a configurable flag to switch the default response preference to return=identifier. To ensure forward compatibility, clients are encouraged to always include the Prefer request header explicitly. Stating the preference explicitly prevents unexpected behavior changes as the default behavior evolves.

Clients MAY request that object references (e.g., OBJECT_REF) be resolved into full or partial representations by specifying:

Prefer: return=representation, resolve_refs

This is particularly useful when retrieving lists of COMPOSITION resources within an EHR, where the default behavior is to return only reference links.

For the openEHR API, a resource is an instance object of a specific openEHR class (type) that can be identified, addressed, handled or managed by the service. Examples of openEHR resources include:

• top-level content structure: COMPOSITION, EHR_STATUS, FOLDER, PARTY, etc.
• versioned entities: VERSIONED_COMPOSITION, VERSIONED_EHR_STATUS, etc. or their contained VERSION instances.
• non-versioned resources: EHR, CONTRIBUTION, RESULT_SET, etc.
• definitions: TEMPLATE, ARCHETYPE, QUERY.

In this specification, types defined by openEHR are always capitalized. For a complete list of available types, refer to the class index.

A key aspect of a RESTful service is the ability to address resources via URIs/URLs using HTTP methods. Each resource has a unique identifier within the system for its type, typically including a globally unique identifier and, in some cases, a version identifier. Once assigned, a resource identifier remains unchanged throughout its lifetime.

Depending on the resource type and use case, different identifiers (and formats) are used:

• a versioned_object_uid for identifying a VERSIONED_OBJECT (i.e. a version container), stored under VERSIONED_OBJECT.uid.value, in a form of a HIER_OBJECT_ID,
• a version_uid for identifying a VERSION from the version container, stored under VERSION.uid.value, in a form of an OBJECT_VERSION_ID,
• an ehr_id to identify an EHR,
• a template_id to identify a Template definition.
• a qualified_query_name to identify Query definition.

The version_uid uniquely identifies a VERSION, in the lexical form of object_id :: creating_system_id :: version_tree_id. Here, the object_id matches the VERSIONED_OBJECT identifier, taken from VERSIONED_OBJECT.uid.value (i.e. the versioned_object_uid).

Consider the following request:

GET https://openEHRSys.example.com/v1/ehr/7d44b88c-4199-4bad-97dc-d78268e01398/composition/8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1

• the EHR identifier is 7d44b88c-4199-4bad-97dc-d78268e01398, taken from EHR.ehr_id.value,
• the COMPOSITION identifier 8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1, taken from COMPOSITION.uid.value, which also implies that the VERSIONED_OBJECT identifier is 8849182c-82ad-4088-a07f-48ead4180515 and the latest version is 1,
• the request is made to an openEHR API (of version v1), located at https://openEHRSys.example.com.

NOTE: Since RM Release 1.0.4 it is strongly recommended that the inherited attribute uid attribute in COMPOSITION objects be populated using the uid copied from the enclosing VERSION object. For example, if an ORIGINAL_VERSION.uid is 87284370-2D4B-4e3d-A3F3-F303D2F4F34B::uk.nhs.ehr1::2, then this value should be copied to the COMPOSITION.uid attribute. See Levels of identification section of Architecture Overview for more details.

There are circumstances when openEHR resources can be uniquely identified by two different identifiers. For example, if a VERSIONED_COMPOSITION container has the versioned_object_uid identifier 8849182c-82ad-4088-a07f-48ead4180515, and the latest version is 5 (taken from version_tree_id), then the COMPOSITION can be accessed using either:

GET https://openEHRSys.example.com/v1/ehr/7d44b88c-4199-4bad-97dc-d78268e01398/composition/8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com:5

as explicit version reference, using the version_uid identifier,

GET https://openEHRSys.example.com/v1/ehr/7d44b88c-4199-4bad-97dc-d78268e01398/composition/8849182c-82ad-4088-a07f-48ead4180515

as implicit latest version reference.

However, the implicit URI will only resolve to the same resource as the explicit versioned URI as long as no new versions are created (i.e. the latest version remains 5).

Services MUST support at least one of the openEHR XML or JSON formats for resource representation. Additionally, alternative formats, such as the Simplified Data Template (SDT) format, MAY be supported. The supported formats and their negotiation protocols are described below.

When resources are serialized in XML format, both request payloads and responses MUST conform to the published XSDs.

A client MAY use the header Content-Type: application/xml in the requests to specify the XML payload format. If the service cannot process the request payload as XML format is not supported, it MUST respond with HTTP status code 415 Unsupported Media Type.

The client SHOULD use the Accept: application/xml request header in order to specify the expected XML response format. If the service cannot fulfill this aspect of the request, it MUST respond with HTTP status code 406 Not Acceptable. Proper header Content-Type: application/xml MUST be present in the response of the service unless the response has no content body (HTTP status code 204).

When resources representation is serialized as JSON, the request payload as well as the result SHOULD be valid against published JSON-Schemas.

NOTE: The JSON-Schema project is under development.

Attribute names must be lowercase snake_case names as specified in the equivalent RM type. For example:

{
    "category": {
        "value": "event",
        "defining_code": {
            "terminology_id": {
                "value": "openehr"
            },
            "code_string": "433"
        }
    }
}

Metadata attributes (those that are not also RM attributes) will always be prefixed by a '_'.

One example is the _type attribute, which should be used to specify the RM type whenever polymorphism is involved, or when the underlying definition in RM type is abstract (dynamic type is different from the static type). This follows same rule as for XML typing. The value of this attribute MUST be the uppercase class name from the RM specification. For example:

{
    "_type": "DV_TEXT",
    "value": "Hello world!"
}

The RM attributes (even required ones) that are Null, empty list or empty arrays SHOULD be absent when serialized as JSON.

The order of attributes in the resource MAY follow the order of attributes in the RM specification of the type of the resource, but this is not mandatory.

A client MAY use the header Content-Type: application/json in the requests to specify the JSON payload format. If the service cannot process the request payload as JSON format is not supported, it MUST respond with HTTP status code 415 Unsupported Media Type.

The client SHOULD use the Accept: application/json request header in order to specify the expected JSON response format. If the service cannot fulfill this aspect of the request, it MUST respond with HTTP status code 406 Not Acceptable. Proper header Content-Type: application/json MUST be present in the response of the service unless the response has no content body (HTTP status code 204).

Creating data instances according to canonical XML or JSON format is not always straightforward, particularly for developers with minimal exposure to openEHR, and various alternatives have been used in the past to simplify the job of content creation and committal for application developers.

Simplified Data Template formats

There is an initiative exploring and documenting these alternative formats, which specifications can be consulted at Simplified Data Template (SDT) page.

NOTE: The specification of Simplified Data Template is under development.

In order to use these formats, content negotiation SHOULD be done in the same manner as for the canonical XML or JSON format above, but instead of application/xml or application/json, clients and servers MUST use:

• application/openehr.wt.flat+json for the simplified IM Simplified Data Template (simSDT) as JSON,

based on the 'FLAT' version of the 'web template' format, originally created by Marand for the Better platform. More information can be found also in their 'examples' page, as well as in their open-source implementation and conformance tests.

EHRbase also has support for this format, and provides information in their documentation.

• application/openehr.wt.structured+json for the structured IM Simplified Data Template (structSDT) as JSON,

based on the 'STRUCTURED' version of the 'web template' format originally created by Marand for the Better platform (see also their 'examples').

Legacy or experimental formats

• application/openehr.nc.flat+json for near-canonical RM Simplified Data Template (ncSDT) as JSON, based on the

ECISFLAT format, originally devised for the EtherCIS project,

• application/openehr.tds2+xml for TDS simplification of RM as XML,

based on the 'TDS/TDD' format originally created by Ocean Health Systems (see this wiki page and the TDD2canonical project).

NOTE: Other alternative formats may be added in the future, depending on innovative impact, simplicity, popular demand or adoption rate.

Current alternative formats might not be supported once they become obsolete or superseded by newer formats.

A client MAY use the header Content-Type in the requests to specify the simplified payload format. If the service cannot process the request payload as the simplified format is not supported, it MUST respond with HTTP status code 415 Unsupported Media Type.

The client SHOULD use the Accept request header in order to specify the expected simplified response format. If the service cannot fulfill this aspect of the request, it MUST respond with HTTP status code 406 Not Acceptable. Proper header Content-Type MUST be present in the response of the service unless the response has no content body (HTTP status code 204).

The format of the date, time and datetime types should comply with the ISO 8601 Date and Time format specification. The ISO 8601 semantics assumed by openEHR is defined in the classes of the base.foundation_types.time package. It is strongly recommended using the extended format for dates, times and datetimes. This greatly aids human readability, and reduces the need for special date/time parsing and formatting.

HTTP query parameters and path segments that are dates, datetimes, or times, MUST always use the extended ISO 8601 format. The general form of a datetime is YYYY-MM-DDThh:mm:ss.sss[Z|±hh:mm], e.g. 2016-06-23T13:42:16.117+02:00.
Timezone SHOULD be only supplied when needed, otherwise the local timezone is assumed.

Any date, datetime or time value provided as part of the HTTP message body, when creating or updating a resource (e.g. a DV_DATE_TIME value inside the COMPOSITION content), will be preserved as it was sent by the client, and passed to the underlying backend engine as is. Retrieval or querying those resources SHOULD return date, datetime, or time values in the (original) format provided by underlying backend engine, avoiding any format change.

Issue	Details	Raiser, Implementer	Completed
5.3	SPECITS-74: Deprecate some of the use of Location response header	REST WG	25 Sep 2025
	SPECITS-82: Add ETag weakness indicator W/ prefix	REST WG	25 Sep 2025
	SPECITS-50: Return very minimal REST responses to avoid 204 No content codes.	REST WG	25 Sep 2025
5.2	SPECITS-77: Add support for ITEM_TAGs	REST WG	14 Mar 2025
	SPECITS-80: Add admin support to delete EHR	S Iancu	14 Mar 2025
	SPECITS-75: Fix inconsistent and invalid header names	E Astrom, J Grisham, S Iancu	14 Mar 2025
5.1	SPECITS-73: Add Demographic API endpoint	P Pazos, S Iancu	11 Sep 2024
5.0	SPECITS-75: Change structure and improve yaml specs	S Iancu	11 Sep 2024
Release-1.0.3
4.1	SPECITS-66: Migrate REST API specs to OpenAPI Specification	S Iancu	19 Dec 2022
Release-1.0.2
3.4	SPECITS-59: Specify mimeType used by adl2 template	S Iancu	26 Mar 2021
3.3	SPECITS-41: Add double quotes to ETag and If-Match headers	S Iancu	21 Mar 2021
	SPECITS-42: Fix TEMPLATE_ID value format in examples	S Iancu	21 Mar 2021
3.2	SPECITS-56: Fixing typos, formatting and minor documentary errors	S Iancu	15 Mar 2021
	SPECITS-45: Describe more clearly the datetime format for REST API	P Pazos, S Iancu	15 Mar 2021
3.1	SPECITS-57: Updating info about simplified JSON formats	E Sundvall, S Iancu	13 Mar 2021
3.0	SPECITS-49: Describing Resource Identification; add clarification over getting COMPOSITIONs by with `version_uid` vs `versioned_object_uid`	J Smolka, M Polajnar, S Iancu	08 Mar 2021
	SPECITS-47: Fix inconsistency over query_parameter(s)	P Pazos, S Iancu	06 Mar 2021
	SPECITS-52: Fix wrong example on revision history of the VERSIONED_COMPOSITION and VERSIONED_EHR_STATUS	J Smolka, S Iancu	06 Mar 2021
Release-1.0.1
2.5	SPECITS-37: Fix query definition endpoint and content-type errors	P Pazos, J Smolka, S Iancu	01 Oct 2019
	SPECITS-38: Fix response status code for semantic validation errors (fixes also SPECPR-298)	P Pazos, S Iancu	01 Oct 2019
2.4	SPECITS-33: Add reference to Simplified Data Template (SDT) format specification	I McNicoll, T Beale, S Iancu	17 Oct 2019
	SPECITS-40: Fix and improve documentation on EHR (fixes also SPECPR-312)	P Pazos, S Iancu	28 Sep 2019
2.3	SPECITS-32: Fix typos and minor documentary errors (fixes SPECPR-252, SPECPR-253, SPECPR-255, SPECPR-298, SPECPR-333, SPECPR-337)	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