Overview (latest)
© 2018 - 2025 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 | ![]() |
Support | Issues: Problem Reports Web: specifications.openEHR.org |
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:
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.
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:
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.
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
header is available all change-controlled resources (e.g. COMPOSITION, EHR_STATUS, FOLDER, etc.).
Below is an example of this header:
openehr-item-tag: key="category",value="final"; key="flag",value="follow-up",target_path="/composition/start_time/value"
Note that, this header acts as a convenient wrapper around dedicated ITEM_TAG actions (e.g. retrieving COMPOSITION tags), simplifying client interaction and reducing necessary API calls. If the server does not support ITEM_TAGs, this header will also be unsupported.
Usage in Requests
When used as a request headers for creation or update operations (PUT
, POST
), the header will instruct the system on which ITEM_TAG list should be associated with the target VERSION or VERSION_OBJECT resource.
Providing an empty value for this header will effectively remove all ITEM_TAG associated with the given target.
Usage in Responses
Servers MAY add openehr-item-tag
header to the response, to confirm the actual list as stored on server side.
When retrieving resources viw GET
methods, the server MAY also add openehr-item-tag
response header that will contain the list of all ITEM_TAG associated with the target VERSION or VERSIONED_OBJECT.
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. TheLocation
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 indicatorW/
. This usage is now deprecated, but implementations MAY still support it alongside the updated header format that includes the weakness indicatorW/
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 aLocation
header pointing to the newly created or updated resource. The HTTP status is typically201 Created
. If no response body is returned, the service SHOULD use204 No Content
.Prefer: return=identifier
Indicates the client prefers a minimal response that includes only the identifier (e.g., theuid
) of the affected resource. The response MAY include aLocation
header pointing to the newly created or updated resource. The HTTP status is typically201 Created
or200 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 aLocation
header, and the response body SHOULD contain the full representation of the resource. The HTTP status is typically201 Created
or200 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 toreturn=identifier
. To ensure forward compatibility, clients are encouraged to always include thePrefer
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 is8849182c-82ad-4088-a07f-48ead4180515
and the latest version is1
, - the request is made to an openEHR API (of version
v1
), located athttps://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 theuid
copied from the enclosing VERSION object. For example, if an ORIGINAL_VERSION.uid is87284370-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 |