openapi: 3.0.3
info:
  title: Overview
  version: latest
  x-status: STABLE
  x-spec: overview
  contact:
    name: Specifications Editorial Committee openEHR
    url: https://specifications.openehr.org/
    email: info@openehr.org
  license:
    name: Creative Commons Attribution-NoDerivs 3.0 Unported
    url: https://creativecommons.org/licenses/by-nd/3.0/
  description: |
    <table>
        <colgroup>
            <col style="width: 20%;">
            <col style="width: 80%;">
        </colgroup>
        <thead>
        <tr>
            <th colspan="2">© 2018 - 2024 The openEHR Foundation</th>
        </tr>
        </thead>
        <tbody>
        <tr>
            <td colspan="2">
                The <a href="https://www.openEHR.org" target="_blank" rel="noopener">openEHR Foundation</a> 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.
            </td>
        </tr>
        <tr>
            <td><strong>Licence</strong></td>
            <td><span class="image"><img src="https://specifications.openehr.org/images/cc-by-nd-88x31.png" alt="image"></span> Creative Commons Attribution-NoDerivs 3.0 Unported.
                <a href="https://creativecommons.org/licenses/by-nd/3.0/" class="bare">https://creativecommons.org/licenses/by-nd/3.0/</a>
            </td>
        </tr>
        <tr>
            <td><strong>Support</strong></td>
            <td>Issues: <a href="https://specifications.openehr.org/components/ITS/open_issues" target="_blank" rel="noopener">Problem Reports</a><br>
                Web: <a href="https://specifications.openehr.org" target="_blank" rel="noopener">specifications.openEHR.org</a>
            </td>
        </tr>
        </tbody>
    </table>
servers: []
security: []
tags:
  - name: Acknowledgements
    description: |+
      [comment]: # (title: Acknowledgements)

      ### Editor
      - Sebastian Iancu, Architect, Code24, Netherlands

      ### Contributors
      This specification benefited from wide formal and informal input from the openEHR and wider health informatics community. The openEHR Foundation would like to recognise the following people for their contributions.
      - Birger Haarbrandt, MSc, Peter L. Reichertz Institut for Medical Informatics (PLRI), Germany
      - Bjørn Næss, DIPS, Norway
      - Bostjan Lah, Senior Architect, Better, Slovenia
      - Erik Sundvall, Information Architect at Karolinska University Hospital, Sweden
      - Heath Frankel, Ocean Informatics, Australia
      - Ian McNicoll MD, FreshEHR, UK
      - Jake Smolka, Software Engineer, Better, Slovenia
      - Matija Polajnar, PhD, Software Engineer, Better, Slovenia
      - Pablo Pazos Gutierrez, Senior engineer, CaboLabs, Uruguay
      - Rong Chen MD, PhD, Cambio Healthcare Systems, Sweden
      - Sebastian Iancu, Architect, Code24, Netherlands
      - Seref Arikan, MEcon, Ocean Informatics UK, Centre for Health Informatics and Multi-professional Education (CHIME) UK
      - Thomas Beale, Ars Semantica UK, openEHR Foundation Management Board

      ### Trademarks
      - 'openEHR' is a trademark of the [openEHR Foundation](https://www.openEHR.org)
      - 'OpenAPI' is a trademark of the [The Linux Foundation](https://www.linuxfoundation.org)

  - name: Preface
    description: |+
      [comment]: # (title: Preface)

      ### 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](https://specifications.openehr.org/releases/BASE/latest/architecture_overview.html)

      Related documents include:

      - The [openEHR Global Class Index](https://specifications.openehr.org/classes)
      - The [XML-Schemas (XSD)](https://specifications.openehr.org/releases/ITS-XML/latest)
      - The [JSON-Schemas](https://specifications.openehr.org/releases/ITS-JSON/latest) and [Simplified Data Template (SDT)](simplified_data_template.html)
      - The [openEHR Platform Abstract Service Model](https://specifications.openehr.org/releases/SM/development/openehr_platform.html)

      ### Status

      This specification is in the `STABLE` state, and can be downloaded as [OpenAPI specification](https://spec.openapis.org/oas/v3.0.3) file (in YAML format) [for validation](computable/OAS/overview-validation.openapi.yaml), or [for code generators](computable/OAS/overview-codegen.openapi.yaml).
      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

      Feedback may be provided on the [Implementation Technology Specifications forum](https://discourse.openehr.org/c/specifications/its/41).

      Issues may be raised on the [specifications Problem Report tracker](https://openehr.atlassian.net/browse/SPECPR).

      To see changes made due to previously reported issues, see the [ITS component Change Request tracker](https://specifications.openehr.org/components/ITS/history).

      ## Conformance

      tbd.

      ## Requirements

      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](https://tools.ietf.org/html/bcp14) [[RFC 2119](https://tools.ietf.org/html/rfc2119)],
      [[RFC 8174](https://tools.ietf.org/html/rfc8174)] when, and only when, they appear in all capitals, as shown here.

  - name: Glossary_and_conventions
    x-displayName: Glossary and conventions
    description: |
      [comment]: # (title: Glossary and conventions)

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

      | <div style="width:180px">Term</div> | Description                                                                                                                                                                                                                                        |
      |-------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
      | API                                 | Application Programmer Interface                                                                                                                                                                                                                   |
      | REST                                | [Representational state transfer](https://en.wikipedia.org/wiki/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](https://spec.openapis.org/oas/v3.0.3)                                                                                                                                                                       |
      | AQL                                 | openEHR's [Archetype Query Language](https://specifications.openehr.org/releases/QUERY/latest/AQL.html)                                                                                                                                            |
      | RM                                  | openEHR's [Reference Model](https://specifications.openehr.org/releases/RM/latest)                                                                                                                                                                 |
      | SEMVER                              | [Semantic Versioning 2.0.0](https://semver.org/)                                                                                                                                                                                                   |
      | `UUID`                              | A universally unique identifier as described by [RFC 4122](https://tools.ietf.org/html/rfc4122) (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)                                                                                                     |
  - name: Specifications
    description: |
      [comment]: # (title: Specifications)

      The openEHR REST specifications following service endpoints: 
       - [System API](system.html)
       - [EHR API](ehr.html)
       - [Demographic API](demographic.html)
       - [Query API](query.html)
       - [Definition API](definition.html)

      Specifications can be downloaded as YAML files in [OpenAPI Specification 3.0](https://spec.openapis.org/oas/v3.0.3) 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](https://github.com/openapitools/openapi-generator), or [Swagger codegen](https://github.com/swagger-api/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](https://spec.openapis.org/oas/v3.0.3#composition-and-inheritance-polymorphism) specification. 

      The latest OpenAPI Specification files are available in GitHub at [openEHR/specifications-ITS-REST/computable/OAS](https://github.com/openEHR/specifications-ITS-REST/tree/master/computable/OAS).
  - name: Requests_and_responses
    x-displayName: Requests and responses
    description: |
      [comment]: # (title: Requests and Responses)

      The following describes in details how HTTP [headers](#tag/Requests_and_responses/HTTP-headers) and [status codes](#tag/Requests_and_responses/HTTP-status-codes)
      MUST be used by an openEHR REST API implementation in order to achieve good interaction between services and clients in the spirit of this specification.

      Furthermore, general details about resources, [data representation](#tag/Resources/Data-representation) and content negotiation are described in this specification.

      > NOTE: **JSON** format is used in many of the example below, but this does not imply that **XML** might not be supported by the same service endpoint.


      # HTTP Methods

      HTTP Methods are described by [RFC 7231](https://tools.ietf.org/html/rfc7231#section-4)
      and by [IANA HTTP Method Registry](https://www.iana.org/assignments/http-methods/http-methods.xhtml).
      The following subset is being 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.                              |


      # Authentication and authorization

      Services SHOULD implement and support an HTTP Authentication and Authorization framework
      (which can support various schemes) but there is no assumption or recommendation being made
      in this specification about which authentication scheme should be used by services and clients.
      See [RFC 7235](https://tools.ietf.org/html/rfc7235) or [Mozilla's HTTP Authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication)
      for details on this subject.

      If an Authentication and Authorisation framework is present, services MUST properly use `WWW-Authenticate` and/or
      `Proxy-Authenticate` response headers and return HTTP status code `403 Forbidden` or `401 Unauthorized` or
      `407 Proxy Authentication` whenever applicable, and clients MUST properly use `Authorization` and `Proxy-Authorization`
      in their request headers.


      # HTTP headers

      Standard HTTP Request and Response headers are described by [RFC 7231](https://tools.ietf.org/html/rfc7231)
      and by the [IANA Message Headers](http://www.iana.org/assignments/message-headers/message-headers.xhtml).
      The following describes the use of a subset of these headers, as well as the custom headers used by an openEHR API.

      ## openEHR-VERSION and openEHR-AUDIT_DETAILS

      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](https://specifications.openehr.org/releases/RM/latest/common.html#\_change_control_package) under the hood.
      The 'native' way of committing is to use a [CONTRIBUTION](https://specifications.openehr.org/releases/RM/latest/common.html#\_contributions)
      and wrap the content as a [VERSION](https://specifications.openehr.org/releases/RM/latest/common.html#\_version_class).
      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](#tag/Requests_and_responses/Authentication-and-authorization) runtime data.
      Below is a complex example of these request headers used in a `PUT` action to update a COMPOSITION:

      ```http
      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", external_ref.id="BC8132EA-8F4A-11E7-BB31-BE2E44B06B34", external_ref.namespace="demographic", 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.

      Below a list of `code_string` values and their meaning (taken from [openEHR terminology](https://raw.githubusercontent.com/openEHR/terminology/Release-2.0.0/openEHR_RM/en/openehr_terminology.xml)):

      | header                            | code | value / meaning |
      | --------------------------------- | ---- | --------------- |
      | openEHR-VERSION.lifecycle_state   | 532  | complete        |
      | openEHR-VERSION.lifecycle_state   | 553  | incomplete      |
      | openEHR-VERSION.lifecycle_state   | 523  | deleted         |
      | openEHR-AUDIT_DETAILS.change_type | 249  | creation        |
      | openEHR-AUDIT_DETAILS.change_type | 250  | amendment       |
      | openEHR-AUDIT_DETAILS.change_type | 251  | modification    |
      | openEHR-AUDIT_DETAILS.change_type | 252  | synthesis       |
      | openEHR-AUDIT_DETAILS.change_type | 523  | deleted         |
      | openEHR-AUDIT_DETAILS.change_type | 666  | attestation     |
      | openEHR-AUDIT_DETAILS.change_type | 253  | unknown         |

      ## If-Match and accidental overwrites

      The `If-Match` request header SHOULD be used by the clients to prevent accidental overwrites when multiple user
      agents might be acting in parallel on the same resource. This is only required by a small set of versioned resources of this specification.
      In case a service receives this header, and the condition evaluates to `false`, it MUST NOT perform the requested method and instead MUST respond with
      HTTP status code `412 Precondition Failed`, and SHOULD return also latest `version_uid` in the `Location` and `ETag` response headers.

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

      See also details for `If-Match` described by [RFC 7232](https://tools.ietf.org/html/rfc7232#section-3.1).

      ## openEHR-TEMPLATE_ID

      The `openEHR-TEMPLATE_ID` request header MUST be used whenever committing COMPOSITION (via `PUT` or `POST` methods)
      using a [simplified data format](#header-alternative-data-formats) which does not support TEMPLATE_ID value
      under an equivalent `LOCATABLE.archetype_details.template_id` attribute of contained data.

      ## Location and openEHR-uri

      The `Location` response header indicates the resource location (URL).
      According to [RFC 7231](https://tools.ietf.org/html/rfc7231#section-7.1.2), it is used to refer to a specific resource in relation to the response.
      The type of relationship is defined by the combination of request method and status code semantics.
      The identifiers part of this URI-reference SHOULD comply with [resource identification](#tag/Resources/Resource-identification) semantics of this specification.

      Services MUST return this header whenever a create or update operation was performed, but it MAY
      return this header on other operation or action. Example:

      ```http
      Location: https://openEHRSys.example.com/v1/ehr/347a5490-55ee-4da9-b91a-9bba710f730e/composition/8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::2
      ```

      See [representation details negotiation](#tag/Requests_and_responses/Representation-details-negotiation) section
      for more details on how use this header.

      If services have support to generate resource URL as specified by the DV_URI/DV_EHR_URI format, then they MAY send also `openEHR-uri` response header. Example:

      ```http
      openEHR-uri: ehr:/347a5490-55ee-4da9-b91a-9bba710f730e/compositions/87284370-2D4B-4e3d-A3F3-F303D2F4F34B
      ```

      ## Prefer

      The `Prefer` request header MAY be used by clients for resource representation negotiation.
      See more details on [representation details negotiation](#tag/Requests_and_responses/Representation-details-negotiation) section.

      ## ETag and Last-Modified

      These headers are mainly related to whether or not a returned resource may be cacheable.
      Their purpose is to give clients information about the state of the requested resources.

      According to [RFC 7232](https://tools.ietf.org/html/rfc7232#section-2.3),

      > The "ETag" header field in a response provides the current entity-tag
      for the selected representation, as determined at the conclusion of
      handling the request.  An entity-tag is an opaque validator for
      differentiating between multiple representations of the same
      resource, regardless of whether those multiple representations are
      due to resource state changes over time, content negotiation
      resulting in multiple representations being valid at the same time,
      or both.

      The `ETag` response HTTP header contains a string token that the server associates with a resource in order to
      uniquely identify the state of that resource over its lifetime. The value of the token changes as soon as the resource changes.
      An example of such header value format is:

      ```http
      ETag: "8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::2"
      ```

      Servers MAY choose their own format for this header, but the recommended value is the unique identifier of the requested resource
      (e.g. VERSIONED_OBJECT.uid.value, VERSION.uid.value, EHR.ehr_id.value, etc).

      The `Last-Modified` response HTTP header contains the datetime of the last modification of targeted resource
      which should be taken from VERSION.commit_audit.time_committed.value.
      An example of such header value format is:

      ```http
      Last-Modified: Wed, 22 Jul 2009 19:15:56 GMT
      ```

      These two headers SHOULD be present in all responses targeting VERSION, VERSIONED_OBJECT or other resources
      that have similar unique identifier.


      # HTTP status codes 

      HTTP Status codes are described by [RFC 7231](https://tools.ietf.org/html/rfc7231#section-6)
      and by the [IANA Status Code Registry](https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml).
      The following subset of the is being 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 the request, or the executed operation, one of the HTTP status codes MUST be used, as described [above](#header-glossary-and-conventions).
      Meaning of these codes may be further detailed (nuanced) in this specification by particular responses.
      If required, other status codes MAY be used by implementations as long as their usecase is not conflicting or overlapping with above codes.

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

      In case of errors (HTTP status codes `400`-`500`), the services MAY return more details (if `Prefer: return=representation` request header is present).
      Example:

      > some codes/messages <https://github.com/ppazos/cabolabs-ehrserver/wiki/API-error-codes-and-messages> and
      > <http://veratechnas1.synology.me:13606/InstanceValidator/rules.html>

      ```json
      {
          "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"
                  }
              }
          ]
      }
      ```

      # Representation details negotiation

      When using the `POST` and `PUT` HTTP methods to create or update a resource, the service SHOULD give clients the option of returning either a complete
      representation of the (modified) resource, or a minimal or no content in the payload response (assuming the operation was successfully completed).
      See [RFC 7240](https://tools.ietf.org/html/rfc7240#section-4.2) for more details on how achieve this using `Prefer` header.
      The client MAY choose any of the following:

      - send `Prefer: return=minimal` to inform the service that prefers only a minimal response to a successful request.

      A `Location` header indicating the direct URL to access the resource MUST be part of the service response.
      If there is no payload content to be returned, the service SHOULD use HTTP status code `204 No Content`.

      - send `Prefer: return=representation` to inform the service that prefers a full representation response to a successful request.

      A `Location` header indicating the direct URL to access the resource MAY be part of the service response,
      and the payload content SHOULD include a full representation.

      In case no `Prefer` header is present in request, the default response policy is `return=minimal`.

      Another preference is related to following and resolving OBJECT_REF identifiers. Under some circumstances a client
      MAY indicate that prefers response containing full or partial resource representation instead of references to resources using OBJECT_REF.
      A typical case is a list of COMPOSITIONs part of an EHR, which, strictly following RM specification, should always return
      list of OBJECT_REF, but sometimes clients prefers to get COMPOSITIONs.
      Services that have this capability implemented SHOULD accept and honor `Prefer: resolve_refs` request header.

      ```http
      Prefer: return=representation, resolve_refs
      ```
  - name: Resources
    description: |
      [comment]: # (title: Resources)

      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.
      The following are examples of openEHR resources and their types:

      - top-level content structure types, such as COMPOSITION, EHR_STATUS, FOLDER, PARTY, etc.
      - version containers, such as VERSIONED_COMPOSITION, VERSIONED_EHR_STATUS, etc. or their containing VERSION
      - other non-versioned resources, such as EHR, CONTRIBUTION, RESULT_SET, etc.
      - definitions, such as TEMPLATE, ARCHETYPE, QUERY

      Types defined by openEHR specification are always capitalized when used in this specification.
      For a list of all available types or a particular type definition please refer to the [class index](https://specifications.openehr.org/classes).

      # Resource identification

      An important aspect of a RESTful service is to be able to address resources via URIs/URLs using HTTP verbs (methods).
      Each resource has an identifier which is unique within the system for that resource type, usually consisting of at least a globally unique identifier and sometimes associated also with a version identifier.
      Once the resource is persisted by the service, the identifier is assigned and will never change for that resource instance.

      Depending on the resource type and on the use-cases, there are several identifier types (and formats):

      - 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` is the unique identifier of a VERSION, in the lexical form of `object_id :: creating_system_id :: version_tree_id`,
      where the `object_id` has the same value as the containing VERSIONED_OBJECT identifier taken from VERSIONED_OBJECT.uid.value (i.e. the `versioned_object_uid`).

      As examples of identifiers, the following request:

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

      is using an URI that contains an EHR identifier `7d44b88c-4199-4bad-97dc-d78268e01398`, taken from EHR.ehr_id.value,
      and a COMPOSITION identifier `8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1`, taken from COMPOSITION.uid.value,
      serviced by an openEHR API (of version `v1`), located at `https://openEHRSys.example.com`.

      There are circumstances when resources can be uniquely identified by two different identifiers. For example, assuming that 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 that COMPOSITION can be identified either by following explicit URI:

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

      using the _version_uid_ identifier, as well as by the following implicit URI:

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

      However, the latter will only reference the same resource as the former as long as there are no more changes or modifications on that specific version container (i.e. the latest version remains `5`).

      - **NOTE:** Since [RM Release 1.0.4](https://specifications.openehr.org/releases/RM/Release-1.0.4) it is strongly recommended that the inherited attribute `uid` be populated in COMPOSITIONs, using the UID copied from the object_id() of the `uid` field of the enclosing VERSION object.
        For example, the ORIGINAL_VERSION.uid `87284370-2D4B-4e3d-A3F3-F303D2F4F34B::uk.nhs.ehr1::2` would be copied to the `uid` field of the COMPOSITION.
        See [Levels of identification](https://specifications.openehr.org/releases/BASE/latest/architecture_overview.html#\_levels_of_identification) chapter of Architecture Overview for more details.

      # Data representation

      Services MUST support at least one of the openEHR **XML** or **JSON** formats for resource representation.
      Alternative formats MAY be also supported, such as a **Simplified Data Template (SDT)** format.
      These formats and their associated negotiation protocol is described below.

      ## XML Format

      When resources representation is serialized as XML, the request payload as well as the result MUST be valid against [published XSDs](https://specifications.openehr.org/releases/ITS-XML/latest).

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

      ## JSON Format

      When resources representation is serialized as JSON, the request payload as well as the result SHOULD be valid against [published JSON-Schemas](https://specifications.openehr.org/releases/ITS-JSON/latest).

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

      ```json
      {
          "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:

      ```json
      {
          "_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`).

      ## Alternative data formats

      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.

      There is an initiative exploring and documenting these alternative formats, which specifications can be consulted at
      [Simplified Data Template (SDT)](simplified_data_template.html) 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](https://www.ehrscape.com/reference.html), originally created by Marand for the Better platform.
      More information can be found also in their ['examples'](https://www.ehrscape.com/examples.html) page, as well as in their [open-source implementation](https://github.com/better-care/web-template)
      and [conformance tests](https://github.com/better-care/web-template-tests).

      ```
      EHRbase also has support for this format, and provides information in their [documentation](https://docs.ehrbase.org/docs/EHRbase/openEHR-Introduction/Load-Data#flat-format). 
      ```

      - `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](https://www.ehrscape.com/reference.html) originally created by Marand for the Better platform
      (see also their ['examples'](https://www.ehrscape.com/examples.html)).

      - `text/plain` for all textual ADL2 templates or AQL queries,
      - `application/openehr.nc.flat+json` for near-canonical RM Simplified Data Template (ncSDT) as JSON, based on the

      [ECISFLAT format](https://github.com/ethercis/ethercis/blob/master/doc/flat%20json.md), 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](http://oceanhealthsystems.com/)
      (see [this wiki page](https://openehr.atlassian.net/wiki/spaces/spec/pages/30408770/Template+Data+Schema+TDS+Specification+and+associated+Template+Data+Document+TDD)
      and the [TDD2canonical](https://github.com/openEHR/openEHR-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`).

      ## Datetime format

      The format of the date, time and datetime types should comply with the [ISO 8601 Date and Time](https://en.wikipedia.org/wiki/ISO\_8601) format specification.
      The ISO 8601 semantics assumed by openEHR is defined in the classes of the [base.foundation_types.time package](https://specifications.openehr.org/releases/BASE/latest/foundation_types.html#\_time_types).
      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.
  - name: Amendment_record
    x-displayName: Amendment Record
    description: |
      [comment]: # (title: Amendment Record)

      <table>
          <colgroup>
              <col style="width: 9%;">
              <col style="width: 55%;">
              <col style="width: 18%;">
              <col style="width: 18%;">
          </colgroup>
          <thead>
          <tr>
              <th>Issue</th>
              <th>Details</th>
              <th>Raiser, Implementer</th>
              <th>Completed</th>
          </tr>
          </thead>
          <tbody>
          <tr>
              <td>5.1</td>
              <td><a href="https://specifications.openehr.org/tickets/SPECITS-73" target="_blank" rel="noopener">SPECITS-73</a>:
                  Add Demographic API endpoint</td>
              <td>P Pazos, S Iancu</td>
              <td>11 Sep 2024</td>
          </tr>
          <tr>
              <td>5.0</td>
              <td><a href="https://specifications.openehr.org/tickets/SPECITS-73" target="_blank" rel="noopener">SPECITS-73</a>:
                  Change structure and improve yaml specs</td>
              <td>S Iancu</td>
              <td>11 Sep 2024</td>
          </tr>
          <tr>
              <th colspan="4"><a href="https://specifications.openehr.org/releases/ITS-REST/latest" target="_blank" rel="noopener">Release-1.0.3</a></th>
          </tr>
          <tr>
              <td>4.1</td>
              <td><a href="https://specifications.openehr.org/tickets/SPECITS-66" target="_blank" rel="noopener">SPECITS-66</a>:
                  Migrate REST API specs to OpenAPI Specification</td>
              <td>S Iancu</td>
              <td>19 Dec 2022</td>
          </tr>
          <tr>
              <th colspan="4"><a href="https://specifications.openehr.org/releases/ITS-REST/Release-1.0.2" target="_blank" rel="noopener">Release-1.0.2</a></th>
          </tr>
          <tr>
              <td>3.4</td>
              <td><a href="https://specifications.openehr.org/tickets/SPECITS-59" target="_blank" rel="noopener">SPECITS-59</a>:
                  Specify mimeType used by adl2 template</td>
              <td>S Iancu</td>
              <td>26 Mar 2021</td>
          </tr>
          <tr>
              <td>3.3</td>
              <td><a href="https://specifications.openehr.org/tickets/SPECITS-41" target="_blank" rel="noopener">SPECITS-41</a>:
                  Add double quotes to ETag and If-Match headers</td>
              <td>S Iancu</td>
              <td>21 Mar 2021</td>
          </tr>
          <tr>
              <td></td>
              <td><a href="https://specifications.openehr.org/tickets/SPECITS-42" target="_blank" rel="noopener">SPECITS-42</a>:
                  Fix TEMPLATE_ID value format in examples</td>
              <td>S Iancu</td>
              <td>21 Mar 2021</td>
          </tr>
          <tr>
              <td>3.2</td>
              <td><a href="https://specifications.openehr.org/tickets/SPECITS-56" target="_blank" rel="noopener">SPECITS-56</a>:
                  Fixing typos, formatting and minor documentary errors</td>
              <td>S Iancu</td>
              <td>15 Mar 2021</td>
          </tr>
          <tr>
              <td></td>
              <td><a href="https://specifications.openehr.org/tickets/SPECITS-45" target="_blank" rel="noopener">SPECITS-45</a>:
                  Describe more clearly the datetime format for REST API</td>
              <td>P Pazos, S Iancu</td>
              <td>15 Mar 2021</td>
          </tr>
          <tr>
              <td>3.1</td>
              <td><a href="https://specifications.openehr.org/tickets/SPECITS-57" target="_blank" rel="noopener">SPECITS-57</a>:
                  Updating info about simplified JSON formats</td>
              <td>E Sundvall, S Iancu</td>
              <td>13 Mar 2021</td>
          </tr>
          <tr>
              <td>3.0</td>
              <td><a href="https://specifications.openehr.org/tickets/SPECITS-49" target="_blank" rel="noopener">SPECITS-49</a>:
                  Describing Resource Identification; add clarification over getting COMPOSITIONs by with `version_uid` vs `versioned_object_uid`</td>
              <td>J Smolka, M Polajnar, S Iancu</td>
              <td>08 Mar 2021</td>
          </tr>
          <tr>
              <td></td>
              <td><a href="https://specifications.openehr.org/tickets/SPECITS-47" target="_blank" rel="noopener">SPECITS-47</a>: 
                  Fix inconsistency over query_parameter(s)</td>
              <td>P Pazos, S Iancu</td>
              <td>06 Mar 2021</td>
          </tr>
          <tr>
              <td></td>
              <td><a href="https://specifications.openehr.org/tickets/SPECITS-52" target="_blank" rel="noopener">SPECITS-52</a>:
                  Fix wrong example on revision history of the VERSIONED_COMPOSITION and VERSIONED_EHR_STATUS</td>
              <td>J Smolka, S Iancu</td>
              <td>06 Mar 2021</td>
          </tr>
          <tr>
              <th colspan="43"><a href="https://specifications.openehr.org/releases/ITS-REST/Release-1.0.1" target="_blank" rel="noopener">Release-1.0.1</a></th>
          </tr>
          <tr>
              <td>2.5</td>
              <td><a href="https://specifications.openehr.org/tickets/SPECITS-37" target="_blank" rel="noopener">SPECITS-37</a>: Fix query definition endpoint and content-type errors</td>
              <td>P Pazos, J Smolka, S Iancu</td>
              <td>01 Oct 2019</td>
          </tr>
          <tr>
              <td></td>
              <td><a href="https://specifications.openehr.org/tickets/SPECITS-38" target="_blank" rel="noopener">SPECITS-38</a>:
                  Fix response status code for semantic validation errors (fixes also
                  <a href="https://specifications.openehr.org/tickets/SPECPR-298" target="_blank" rel="noopener">SPECPR-298</a>)</td>
              <td>P Pazos, S Iancu</td>
              <td>01 Oct 2019</td>
          </tr>
          <tr>
              <td>2.4</td>
              <td><a href="https://specifications.openehr.org/tickets/SPECITS-33" target="_blank" rel="noopener">SPECITS-33</a>: Add reference to Simplified Data Template (SDT) format specification</td>
              <td>I McNicoll, T Beale, S Iancu</td>
              <td>17 Oct 2019</td>
          </tr>
          <tr>
              <td></td>
              <td><a href="https://specifications.openehr.org/tickets/SPECITS-40" target="_blank" rel="noopener">SPECITS-40</a>:
                  Fix and improve documentation on EHR (fixes also
                  <a href="https://specifications.openehr.org/tickets/SPECPR-312" target="_blank" rel="noopener">SPECPR-312</a>)</td>
              <td>P Pazos, S Iancu</td>
              <td>28 Sep 2019</td>
          </tr>
          <tr>
              <td>2.3</td>
              <td><a href="https://specifications.openehr.org/tickets/SPECITS-32" target="_blank" rel="noopener">SPECITS-32</a>: Fix typos and minor documentary errors (fixes
                  <a href="https://specifications.openehr.org/tickets/SPECPR-252" target="_blank" rel="noopener">SPECPR-252</a>,
                  <a href="https://specifications.openehr.org/tickets/SPECPR-252" target="_blank" rel="noopener">SPECPR-253</a>,
                  <a href="https://specifications.openehr.org/tickets/SPECPR-255" target="_blank" rel="noopener">SPECPR-255</a>,
                  <a href="https://specifications.openehr.org/tickets/SPECPR-298" target="_blank" rel="noopener">SPECPR-298</a>,
                  <a href="https://specifications.openehr.org/tickets/SPECPR-333" target="_blank" rel="noopener">SPECPR-333</a>,
                  <a href="https://specifications.openehr.org/tickets/SPECPR-337" target="_blank" rel="noopener">SPECPR-337</a>)</td>
              <td>J Smolka, P Pazos, E Sundvall, T Beale, S Iancu</td>
              <td>1 Sep 2019</td>
          </tr>
          <tr>
              <td>2.2</td>
              <td><a href="https://specifications.openehr.org/tickets/SPECITS-24" target="_blank" rel="noopener">SPECITS-24</a>: Added changelog</td>
              <td>J Smolka, S Iancu</td>
              <td>12 May 2019</td>
          </tr>
          <tr>
              <td></td>
              <td><a href="https://specifications.openehr.org/tickets/SPECITS-25" target="_blank" rel="noopener">SPECITS-25</a>,
                  <a href="https://specifications.openehr.org/tickets/SPECITS-29" target="_blank" rel="noopener">SPECITS-29</a>: Change layout and structure</td>
              <td>J Smolka, S Iancu</td>
              <td>12 May 2019</td>
          </tr>
          <tr>
              <td>2.1</td>
              <td>Update links to new openEHR specifications website</td>
              <td>S Iancu</td>
              <td>16 Dec 2018</td>
          </tr>
          <tr>
              <th colspan="4"><a href="https://specifications.openehr.org/releases/ITS-REST/Release-1.0.0" target="_blank" rel="noopener">Release-1.0.0</a></th>
          </tr>
          </tbody>
      </table>
paths: {}
components:
  schemas: {}
