openapi: 3.0.3
info:
  title: EHR API
  version: latest
  x-status: STABLE
  x-spec: ehr
  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: |
    ## Description

    ### Purpose

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

    ### Related Documents

    Prerequisite documents for reading this document include:

    - The [EHR Information Model](https://specifications.openehr.org/releases/RM/latest/ehr.html#_the_ehr_information_model)

    Related documents include:

    - The [openEHR Architecture Overview](https://specifications.openehr.org/releases/BASE/latest/architecture_overview.html)
    - 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 Formats](simplified_formats.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/ehr-validation.openapi.yaml), or [for code generators](computable/OAS/ehr-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/ehr.html>.
servers:
  - url: https://{baseUrl}/v1
    description: An example openEHR server URL.
    variables:
      baseUrl:
        default: openEHRSys.example.com
        description: The (example) server base URL prefix providing openEHR services. This may contain server name, port and base path prefix.
security: []
tags:
  - name: EHR
    description: |
      Management of [EHRs](https://specifications.openehr.org/releases/RM/latest/ehr.html#_ehr_class).

      Operations in this group cover creation of new EHRs, retrieval by identifier or subject, and access to associated versioned resources.

      The `EHR` resource is the top-level resource in the EHR REST API; it contains all other resources in this group. 
      Identification of the `EHR` resource is usually by the `ehr_id`, and is present in the path segment.
  - name: EHR_STATUS
    description: |
      Management of [EHR_STATUS](https://specifications.openehr.org/releases/RM/latest/ehr.html#_ehr_status_class) and [VERSIONED_EHR_STATUS](https://specifications.openehr.org/releases/RM/latest/ehr.html#_versioned_ehr_status_class) resources.

      Operations include retrieval by time or version, update, and inspection of revision history for the versioned status of an EHR.
  - name: COMPOSITION
    description: |
      Management of [COMPOSITION](https://specifications.openehr.org/releases/RM/latest/ehr.html#_composition_class) and [VERSIONED_COMPOSITION](https://specifications.openehr.org/releases/RM/latest/ehr.html#_versioned_composition_class) resources.

      Operations include create, retrieve, update, delete of compositions, and access to their version containers, specific versions and revision history.
  - name: DIRECTORY
    description: |
      Management of the [directory](https://specifications.openehr.org/releases/RM/latest/ehr.html#_directory) [FOLDER](https://specifications.openehr.org/releases/RM/latest/common.html#_folder_class) resource.

      Operations include create, update, delete and time/version-based retrieval of the EHR’s directory structure.
  - name: CONTRIBUTION
    description: |
      Management of [CONTRIBUTION](https://specifications.openehr.org/releases/RM/latest/common.html#_contribution_class) resource.

      Operations cover creation of contributions and retrieval by identifier, enabling audit of grouped version commits within an EHR.
  - name: ITEM_TAG
    description: |
      Management of [ITEM_TAG](https://specifications.openehr.org/releases/RM/development/common.html#_item_tag_class) resources.
  - name: CONTENT_ITEM_schema
    x-displayName: CONTENT_ITEM
    description: |
      The abstract `CONTENT_ITEM` class:
      <SchemaDefinition schemaRef="#/components/schemas/ContentItem" />
  - name: ITEM_schema
    x-displayName: ITEM
    description: |
      The abstract `ITEM` class:
      <SchemaDefinition schemaRef="#/components/schemas/Item" />
  - name: ITEM_STRUCTURE_schema
    x-displayName: ITEM_STRUCTURE
    description: |
      The abstract `ITEM_STRUCTURE` class:
      <SchemaDefinition schemaRef="#/components/schemas/ItemStructure" />
paths:
  /ehr:
    post:
      operationId: ehr_create
      summary: Create EHR
      description: |
        Create a new `EHR` with an auto-generated identifier.

        An EHR_STATUS resource needs to be always created and committed in the new EHR.
        This resource MAY be also supplied by the client as the request body. 
        If not supplied, a default EHR_STATUS will be used by the service with following attributes:
          - `is_queryable`: true
          - `is_modifiable`: true
          - `subject`: a PARTY_SELF object

        All other required EHR attributes and resources will be automatically created as needed by the [EHR creation semantics](https://specifications.openehr.org/releases/RM/latest/ehr.html#_ehr_creation_semantics).
      tags:
        - EHR
      parameters:
        - $ref: '#/components/parameters/Prefer'
        - $ref: '#/components/parameters/Accept_canonical'
        - $ref: '#/components/parameters/ContentType_LOCATABLE'
      requestBody:
        description: |
          An EHR_STATUS resource MAY be also supplied by the client as the request body.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EhrStatus'
        required: false
      responses:
        '201':
          $ref: '#/components/responses/201_EHR'
        '400':
          $ref: '#/components/responses/400'
        '409':
          $ref: '#/components/responses/409_EHR'
    get:
      operationId: ehr_get_by_subject
      summary: Get EHR by subject id
      description: |
        Retrieve the EHR with the specified `subject_id` and `subject_namespace`.

        These subject parameters will be matched against EHR's EHR_STATUS.subject.external_ref.id.value and 
        EHR_STATUS.subject.external_ref.namespace values.
      tags:
        - EHR
      parameters:
        - $ref: '#/components/parameters/subject_id'
        - $ref: '#/components/parameters/subject_namespace'
        - $ref: '#/components/parameters/Accept_canonical'
      responses:
        '200':
          $ref: '#/components/responses/200_EHR'
        '404':
          $ref: '#/components/responses/404_EHR_subject'
  /ehr/{ehr_id}:
    put:
      operationId: ehr_create_with_id
      summary: Create EHR with id
      description: |
        Create a new EHR with the specified `ehr_id` identifier.

        The value of the `ehr_id` unique identifier MUST be valid [HIER_OBJECT_ID](https://specifications.openehr.org/releases/BASE/latest/base_types.html#_hier_object_id_class) value. 
        It is strongly RECOMMENDED that an UUID always be used for this.

        An EHR_STATUS resource needs to be always created and committed in the new EHR.
        This resource MAY be also supplied by the client as the request body. 
        If not supplied, a default EHR_STATUS will be used by the service with following attributes:
          - `is_queryable`: true
          - `is_modifiable`: true
          - `subject`: a PARTY_SELF object

        All other required EHR attributes and resources will be automatically created as needed by the [EHR creation semantics](https://specifications.openehr.org/releases/RM/latest/ehr.html#_ehr_creation_semantics).
      tags:
        - EHR
      parameters:
        - $ref: '#/components/parameters/ehr_id'
        - $ref: '#/components/parameters/Prefer'
        - $ref: '#/components/parameters/Accept_canonical'
        - $ref: '#/components/parameters/ContentType_LOCATABLE'
      requestBody:
        description: |
          An EHR_STATUS resource MAY be also supplied by the client as the request body.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EhrStatus'
        required: false
      responses:
        '201':
          $ref: '#/components/responses/201_EHR'
        '400':
          $ref: '#/components/responses/400'
        '409':
          $ref: '#/components/responses/409_EHR_with_id'
    get:
      operationId: ehr_get_by_id
      summary: Get EHR by id
      description: |
        Retrieve the EHR with the specified `ehr_id`.
      tags:
        - EHR
      parameters:
        - $ref: '#/components/parameters/ehr_id'
        - $ref: '#/components/parameters/Accept_canonical'
      responses:
        '200':
          $ref: '#/components/responses/200_EHR'
        '404':
          $ref: '#/components/responses/404_unknown_ehr_id'
  /ehr/{ehr_id}/ehr_status/{version_uid}:
    get:
      operationId: ehr_status_get_by_version_id
      summary: Get EHR_STATUS by version id
      description: |
        Retrieves a particular version of the EHR_STATUS identified by `version_uid` and associated with the EHR identified by `ehr_id`.

        When there are ITEM_TAGs associated with the retrieved EHR_STATUS, they will be returned as `openehr-item-tag` and `openehr-version-item-tag` response headers, respectively - see [item tags headers](overview.html#tag/Requests_and_responses/HTTP-headers/openehr-item-tag-and-openehr-version-item-tag) for more details.
      tags:
        - EHR_STATUS
      parameters:
        - $ref: '#/components/parameters/ehr_id'
        - $ref: '#/components/parameters/version_uid'
        - $ref: '#/components/parameters/Accept_LOCATABLE'
      responses:
        '200':
          $ref: '#/components/responses/200_EHR_STATUS_retrieved'
        '404':
          $ref: '#/components/responses/404_unknown_ehr_id_or_version_uid'
  /ehr/{ehr_id}/ehr_status:
    get:
      operationId: ehr_status_get_at_time
      summary: Get EHR_STATUS at time
      description: |
        Retrieves a version of the EHR_STATUS associated with the EHR identified by `ehr_id`.

        If `version_at_time` is supplied, retrieves the version extant _at specified time_, otherwise retrieves the _latest_ EHR_STATUS version.

        When there are ITEM_TAGs associated with the retrieved EHR_STATUS, they will be returned as `openehr-item-tag` and `openehr-version-item-tag` response headers, respectively - see [item tags headers](overview.html#tag/Requests_and_responses/HTTP-headers/openehr-item-tag-and-openehr-version-item-tag) for more details.
      tags:
        - EHR_STATUS
      parameters:
        - $ref: '#/components/parameters/ehr_id'
        - $ref: '#/components/parameters/version_at_time'
        - $ref: '#/components/parameters/Accept_LOCATABLE'
      responses:
        '200':
          $ref: '#/components/responses/200_EHR_STATUS_retrieved'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404_unknown_ehr_id_or_no_version_at_time'
    put:
      operationId: ehr_status_update
      summary: Update EHR_STATUS
      description: |
        Updates EHR_STATUS associated with the EHR identified by `ehr_id`.

        The existing latest `version_uid` of EHR_STATUS resource (i.e. the `preceding_version_uid`) must be specified in the `If-Match` header.

        A list of ITEM_TAGs can be associated with the updated EHR_STATUS, in which case a `openehr-item-tag` or `openehr-version-item-tag` request header can be set as well. 
        The corresponding response header(s) will return ITEM_TAGs as they were set by the server - see [item tags headers](overview.html#tag/Requests_and_responses/HTTP-headers/openehr-item-tag-and-openehr-version-item-tag) for more details.

        The response will contain the updated EHR_STATUS resource when the `Prefer` header has a value of `return=representation`.
      tags:
        - EHR_STATUS
      parameters:
        - $ref: '#/components/parameters/ehr_id'
        - $ref: '#/components/parameters/If-Match'
        - $ref: '#/components/parameters/Prefer'
        - $ref: '#/components/parameters/Accept_LOCATABLE'
        - $ref: '#/components/parameters/ContentType_LOCATABLE'
        - $ref: '#/components/parameters/openehr-item-tag'
        - $ref: '#/components/parameters/openehr-version-item-tag'
      requestBody:
        description: |
          The new EHR_STATUS.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EhrStatus'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/200_EHR_STATUS_updated'
        '204':
          $ref: '#/components/responses/204_version_updated'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404_unknown_ehr_id'
        '412':
          $ref: '#/components/responses/412_EHR_STATUS'
  /ehr/{ehr_id}/versioned_ehr_status:
    get:
      operationId: versioned_ehr_status_get
      summary: Get versioned EHR_STATUS
      description: |
        Retrieves a VERSIONED_EHR_STATUS associated with an EHR identified by `ehr_id`.
      tags:
        - EHR_STATUS
      parameters:
        - $ref: '#/components/parameters/ehr_id'
        - $ref: '#/components/parameters/Accept_canonical'
        - $ref: '#/components/parameters/ContentType_canonical'
      responses:
        '200':
          $ref: '#/components/responses/200_VERSIONED_EHR_STATUS'
        '404':
          $ref: '#/components/responses/404_unknown_ehr_id'
  /ehr/{ehr_id}/versioned_ehr_status/revision_history:
    get:
      operationId: versioned_ehr_status_revision_history
      summary: Get versioned EHR_STATUS revision history
      description: |
        Retrieves revision history of the VERSIONED_EHR_STATUS associated with the EHR identified by `ehr_id`.
      tags:
        - EHR_STATUS
      parameters:
        - $ref: '#/components/parameters/ehr_id'
        - $ref: '#/components/parameters/Accept_canonical'
        - $ref: '#/components/parameters/ContentType_canonical'
      responses:
        '200':
          $ref: '#/components/responses/200_REVISION_HISTORY'
        '404':
          $ref: '#/components/responses/404_unknown_ehr_id'
  /ehr/{ehr_id}/versioned_ehr_status/version:
    get:
      operationId: versioned_ehr_status_version_get_at_time
      summary: Get versioned EHR_STATUS version at time
      description: |
        Retrieves a VERSION from the VERSIONED_EHR_STATUS associated with the EHR identified by `ehr_id`.

        If `version_at_time` is supplied, retrieves the VERSION extant _at specified time_, otherwise retrieves the _latest_ VERSION.
      tags:
        - EHR_STATUS
      parameters:
        - $ref: '#/components/parameters/ehr_id'
        - $ref: '#/components/parameters/version_at_time'
        - $ref: '#/components/parameters/Accept_canonical'
        - $ref: '#/components/parameters/ContentType_canonical'
      responses:
        '200':
          $ref: '#/components/responses/200_VERSION_of_EHR_STATUS_at_time'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404_unknown_ehr_id_or_no_version_at_time'
  /ehr/{ehr_id}/versioned_ehr_status/version/{version_uid}:
    get:
      operationId: versioned_ehr_status_version_get_by_id
      summary: Get versioned EHR_STATUS version by id
      description: |
        Retrieves a VERSION identified by `version_uid` of an EHR_STATUS associated with the EHR identified by `ehr_id`.
      tags:
        - EHR_STATUS
      parameters:
        - $ref: '#/components/parameters/ehr_id'
        - $ref: '#/components/parameters/version_uid'
        - $ref: '#/components/parameters/Accept_canonical'
        - $ref: '#/components/parameters/ContentType_canonical'
      responses:
        '200':
          $ref: '#/components/responses/200_VERSION_of_EHR_STATUS_by_id'
        '404':
          $ref: '#/components/responses/404_unknown_ehr_id_or_version_uid'
  /ehr/{ehr_id}/composition:
    post:
      operationId: composition_create
      summary: Create COMPOSITION
      description: |
        Creates the first version of a new COMPOSITION in the EHR identified by `ehr_id`.

        A list of ITEM_TAGs can be associated with the COMPOSITION, in which case a `openehr-item-tag` or `openehr-version-item-tag` request header can be set as well. 
        The corresponding response header(s) will return ITEM_TAGs as they were set by the server - see [item tags headers](overview.html#tag/Requests_and_responses/HTTP-headers/openehr-item-tag-and-openehr-version-item-tag) for more details.
      tags:
        - COMPOSITION
      parameters:
        - $ref: '#/components/parameters/ehr_id'
        - $ref: '#/components/parameters/Prefer'
        - $ref: '#/components/parameters/Accept_LOCATABLE'
        - $ref: '#/components/parameters/ContentType_LOCATABLE'
        - $ref: '#/components/parameters/openehr-item-tag'
        - $ref: '#/components/parameters/openehr-version-item-tag'
      requestBody:
        description: |
          The COMPOSITION.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Composition'
        required: true
      responses:
        '201':
          $ref: '#/components/responses/201_COMPOSITION'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404_unknown_ehr_id'
        '422':
          $ref: '#/components/responses/422'
  /ehr/{ehr_id}/composition/{uid_based_id}:
    get:
      operationId: composition_get
      summary: Get COMPOSITION
      description: |
        Retrieves a version of the COMPOSITION identified by `uid_based_id` and associated with the EHR identified by `ehr_id`.

        The `uid_based_id` 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`).
        The former is used to retrieve a specific known version of the COMPOSITION (e.g. one identified by `8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1`), whereas the latter (e.g. an identifier like `8849182c-82ad-4088-a07f-48ead4180515`) is be used to retrieve a version from the version container whenever the _version_tree_id_ is unknown or irrelevant (such as when most recent version is requested).

        When the `uid_based_id` has the form of a HIER_OBJECT_ID, if the `version_at_time` is supplied, retrieves the version extant _at specified time_, otherwise retrieves the _latest_ COMPOSITION version.

        See [Resource identification](overview.html#tag/Resources/Resource-identification) for more details about the identifiers usage and meaning.

        When there are ITEM_TAGs associated with the retrieved COMPOSITION, they will be returned as `openehr-item-tag` and `openehr-version-item-tag` response headers, respectively - see [item tags headers](overview.html#tag/Requests_and_responses/HTTP-headers/openehr-item-tag-and-openehr-version-item-tag) for more details.
      tags:
        - COMPOSITION
      parameters:
        - $ref: '#/components/parameters/ehr_id'
        - $ref: '#/components/parameters/uid_based_id'
        - $ref: '#/components/parameters/version_at_time'
        - $ref: '#/components/parameters/Accept_LOCATABLE'
      responses:
        '200':
          $ref: '#/components/responses/200_COMPOSITION_retrieved'
        '204':
          $ref: '#/components/responses/204_deleted_at_time'
        '404':
          $ref: '#/components/responses/404_unknown_ehr_id_or_no_version_at_time'
    put:
      operationId: composition_update
      summary: Update COMPOSITION
      description: |
        Updates COMPOSITION identified by `uid_based_id` and associated with the EHR identified by `ehr_id`.

        The `uid_based_id` can take only a form of an HIER_OBJECT_ID identifier taken from VERSIONED_OBJECT.uid.value (i.e. a `versioned_object_uid`).

        If the request body already contains a COMPOSITION.uid.value, it must match the `uid_based_id` in the URL. 

        The existing latest `version_uid` of COMPOSITION resource (i.e. the `preceding_version_uid`) must be specified in the `If-Match` header.

        A list of ITEM_TAGs can be associated with the updated COMPOSITION, in which case a `openehr-item-tag` or `openehr-version-item-tag` request header can be set as well. 
        The corresponding response header(s) will return ITEM_TAGs as they were set by the server - see [item tags headers](overview.html#tag/Requests_and_responses/HTTP-headers/openehr-item-tag-and-openehr-version-item-tag) for more details.
      tags:
        - COMPOSITION
      parameters:
        - $ref: '#/components/parameters/ehr_id'
        - $ref: '#/components/parameters/uid_based_id_as_versioned_object_uid'
        - $ref: '#/components/parameters/If-Match'
        - $ref: '#/components/parameters/Prefer'
        - $ref: '#/components/parameters/Accept_LOCATABLE'
        - $ref: '#/components/parameters/ContentType_LOCATABLE'
        - $ref: '#/components/parameters/openehr-item-tag'
        - $ref: '#/components/parameters/openehr-version-item-tag'
      requestBody:
        description: |
          The new COMPOSITION.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Composition'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/200_COMPOSITION_updated'
        '204':
          $ref: '#/components/responses/204_version_updated'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404_unknown_ehr_id_or_uid_based_id'
        '412':
          $ref: '#/components/responses/412_COMPOSITION'
        '422':
          $ref: '#/components/responses/422'
    delete:
      operationId: composition_delete
      summary: Delete COMPOSITION
      description: |
        Deletes the COMPOSITION identified by `uid_based_id` and associated with the EHR identified by `ehr_id`.

        The `uid_based_id` MUST be in a form of an OBJECT_VERSION_ID identifier taken from the last (most recent) VERSION.uid.value, representing the `preceding_version_uid` to be deleted.
      tags:
        - COMPOSITION
      parameters:
        - $ref: '#/components/parameters/ehr_id'
        - $ref: '#/components/parameters/uid_based_id_as_version_uid'
      responses:
        '204':
          $ref: '#/components/responses/204_version_deleted'
        '400':
          $ref: '#/components/responses/400_already_deleted'
        '404':
          $ref: '#/components/responses/404_unknown_ehr_id_or_uid_based_id'
        '409':
          $ref: '#/components/responses/409_COMPOSITION_with_uid_based_id'
  /ehr/{ehr_id}/versioned_composition/{versioned_object_uid}:
    get:
      operationId: versioned_composition_get
      summary: Get versioned COMPOSITION
      description: |
        Retrieves a VERSIONED_COMPOSITION identified by `versioned_object_uid` and associated with the EHR identified by `ehr_id`.
      tags:
        - COMPOSITION
      parameters:
        - $ref: '#/components/parameters/ehr_id'
        - $ref: '#/components/parameters/versioned_object_uid_COMPOSITION'
        - $ref: '#/components/parameters/Accept_canonical'
        - $ref: '#/components/parameters/ContentType_canonical'
      responses:
        '200':
          $ref: '#/components/responses/200_VERSIONED_COMPOSITION'
        '404':
          $ref: '#/components/responses/404_unknown_ehr_id_or_versioned_object_uid'
  /ehr/{ehr_id}/versioned_composition/{versioned_object_uid}/revision_history:
    get:
      operationId: versioned_composition_revision_history
      summary: Get versioned COMPOSITION revision history
      description: |
        Retrieves revision history of the VERSIONED_COMPOSITION identified by `versioned_object_uid` and associated with the EHR identified by `ehr_id`.
      tags:
        - COMPOSITION
      parameters:
        - $ref: '#/components/parameters/ehr_id'
        - $ref: '#/components/parameters/versioned_object_uid_COMPOSITION'
        - $ref: '#/components/parameters/Accept_canonical'
        - $ref: '#/components/parameters/ContentType_canonical'
      responses:
        '200':
          $ref: '#/components/responses/200_REVISION_HISTORY'
        '404':
          $ref: '#/components/responses/404_unknown_ehr_id_or_versioned_object_uid'
  /ehr/{ehr_id}/versioned_composition/{versioned_object_uid}/version:
    get:
      operationId: versioned_composition_version_get_at_time
      summary: Get versioned COMPOSITION version at time
      description: |
        Retrieves a VERSION from the VERSIONED_COMPOSITION identified by `versioned_object_uid` and associated with the EHR identified by `ehr_id`.

        If `version_at_time` is supplied, retrieves the VERSION extant _at specified time_, otherwise retrieves the _latest_ VERSION.
      tags:
        - COMPOSITION
      parameters:
        - $ref: '#/components/parameters/ehr_id'
        - $ref: '#/components/parameters/versioned_object_uid_COMPOSITION'
        - $ref: '#/components/parameters/version_at_time'
        - $ref: '#/components/parameters/Accept_canonical'
        - $ref: '#/components/parameters/ContentType_canonical'
      responses:
        '200':
          $ref: '#/components/responses/200_VERSION_of_COMPOSITION_at_time'
        '404':
          $ref: '#/components/responses/404_unknown_ehr_id_or_versioned_object_uid_or_no_version_at_time'
  /ehr/{ehr_id}/versioned_composition/{versioned_object_uid}/version/{version_uid}:
    get:
      operationId: versioned_composition_version_get_by_id
      summary: Get versioned COMPOSITION version by id
      description: |
        Retrieves a VERSION identified by `version_uid` of a VERSIONED_COMPOSITION identified by `versioned_object_uid` and associated with the EHR identified by `ehr_id`.
      tags:
        - COMPOSITION
      parameters:
        - $ref: '#/components/parameters/ehr_id'
        - $ref: '#/components/parameters/versioned_object_uid_COMPOSITION'
        - $ref: '#/components/parameters/version_uid_COMPOSITION'
        - $ref: '#/components/parameters/Accept_canonical'
        - $ref: '#/components/parameters/ContentType_canonical'
      responses:
        '200':
          $ref: '#/components/responses/200_VERSION_of_COMPOSITION_by_id'
        '404':
          $ref: '#/components/responses/404_unknown_ehr_id_or_versioned_object_uid_or_version_uid'
  /ehr/{ehr_id}/directory:
    post:
      operationId: directory_create
      summary: Create directory
      description: |
        Creates a new directory FOLDER associated with the EHR identified by `ehr_id`.
      tags:
        - DIRECTORY
      parameters:
        - $ref: '#/components/parameters/ehr_id'
        - $ref: '#/components/parameters/Prefer'
        - $ref: '#/components/parameters/Accept_LOCATABLE'
        - $ref: '#/components/parameters/ContentType_LOCATABLE'
      requestBody:
        description: |
          The directory.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Folder'
        required: true
      responses:
        '201':
          $ref: '#/components/responses/201_directory'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404_unknown_ehr_id'
    put:
      operationId: directory_update
      summary: Update directory
      description: |
        Updates directory FOLDER associated with the EHR identified by `ehr_id`.

        The existing latest `version_uid` of directory FOLDER resource (i.e. the `preceding_version_uid`) must be specified in the `If-Match` header.
      tags:
        - DIRECTORY
      parameters:
        - $ref: '#/components/parameters/ehr_id'
        - $ref: '#/components/parameters/If-Match'
        - $ref: '#/components/parameters/Prefer'
        - $ref: '#/components/parameters/Accept_LOCATABLE'
        - $ref: '#/components/parameters/ContentType_LOCATABLE'
      requestBody:
        description: |
          The new directory.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Folder'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/200_directory_updated'
        '204':
          $ref: '#/components/responses/204_version_updated'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404_unknown_ehr_id'
        '412':
          $ref: '#/components/responses/412_directory'
    delete:
      operationId: directory_delete
      summary: Delete directory
      description: |
        Deletes directory FOLDER associated with the EHR identified by `ehr_id`.

        The existing latest `version_uid` of directory FOLDER resource (i.e. the `preceding_version_uid`) must be specified in the `If-Match` header.
      tags:
        - DIRECTORY
      parameters:
        - $ref: '#/components/parameters/ehr_id'
        - $ref: '#/components/parameters/If-Match'
      responses:
        '204':
          $ref: '#/components/responses/204_deleted'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404_unknown_ehr_id'
        '412':
          $ref: '#/components/responses/412_directory'
    get:
      operationId: directory_get_at_time
      summary: Get folder in directory version at time
      description: |
        Retrieves the version of the directory FOLDER associated with the EHR identified by `ehr_id`. 
        If `version_at_time` is supplied, retrieves the version extant _at specified time_, otherwise retrieves the _latest_ directory FOLDER version. 

        If `path` is supplied, retrieves from the directory only the sub-FOLDER that is associated with that path.
      tags:
        - DIRECTORY
      parameters:
        - $ref: '#/components/parameters/ehr_id'
        - $ref: '#/components/parameters/version_at_time'
        - $ref: '#/components/parameters/path'
        - $ref: '#/components/parameters/Accept_LOCATABLE'
      responses:
        '200':
          $ref: '#/components/responses/200_FOLDER_retrieved'
        '204':
          $ref: '#/components/responses/204_deleted_at_time'
        '404':
          $ref: '#/components/responses/404_directory_unknown_ehr_id_or_no_version_at_time_or_no_path'
  /ehr/{ehr_id}/directory/{version_uid}:
    get:
      operationId: directory_get_by_version_id
      summary: Get folder in directory version
      description: |
        Retrieves a particular version of the directory FOLDER identified by `version_uid` and associated with the EHR identified by `ehr_id`.

        If `path` is supplied, retrieves from the directory only the sub-FOLDER that is associated with that path.
      tags:
        - DIRECTORY
      parameters:
        - $ref: '#/components/parameters/ehr_id'
        - $ref: '#/components/parameters/version_uid'
        - $ref: '#/components/parameters/path'
        - $ref: '#/components/parameters/Accept_LOCATABLE'
      responses:
        '200':
          $ref: '#/components/responses/200_FOLDER_retrieved'
        '404':
          $ref: '#/components/responses/404_directory_unknown_ehr_id_or_no_version_uid_or_no_path'
  /ehr/{ehr_id}/contribution:
    post:
      operationId: contribution_create
      summary: Create CONTRIBUTION
      description: |
        We will use the relaxed CONTRIBUTION with the following optional attributes:
          - `uid`: when provided, it will be accepted in case is not in-use, otherwise error will be returned
          - `audit.time_committed`: server will always set it
          - `audit.system_id`: when provided, it will be validated

        The `audit` and each `versions[i].commit_audit` are `UPDATE_AUDIT` objects: structurally an
        `AUDIT_DETAILS` minus the server-assigned attributes (`time_committed`, and the optional `system_id`).
        Clients SHOULD send `_type: "UPDATE_AUDIT"`; for interoperability servers SHOULD additionally accept
        `_type: "AUDIT_DETAILS"` or an omitted `_type` for this attribute. The `audit.change_type` and each
        `versions[i].lifecycle_state` are `DV_CODED_TEXT` values coded against the openEHR terminology.

        ### Simplified Formats (FLAT / STRUCTURED)

        The `Content-Type` and `Accept` headers MAY be set to one of the Simplified Formats MIME types - `application/openehr.wt.flat+json` or `application/openehr.wt.structured+json` - in addition to the canonical `application/json` / `application/xml`.

        When a Simplified Formats MIME type is used, the **CONTRIBUTION envelope itself remains canonical JSON** (i.e. `uid`, `versions[]` metadata, and `audit` follow the canonical RM serialization). Only the inner versioned payload - each `versions[i].data` (the embedded `COMPOSITION`, `EHR_STATUS`, or `FOLDER`) - is serialized in the chosen FLAT or STRUCTURED form. See [Simplified Formats](../simplified_formats.html) for the rules that apply to that inner payload.
      tags:
        - CONTRIBUTION
      parameters:
        - $ref: '#/components/parameters/ehr_id'
        - $ref: '#/components/parameters/Prefer'
        - $ref: '#/components/parameters/Accept_LOCATABLE'
        - $ref: '#/components/parameters/ContentType_LOCATABLE'
      requestBody:
        description: |
          The CONTRIBUTION.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewContribution'
        required: true
      responses:
        '201':
          $ref: '#/components/responses/201_CONTRIBUTION'
        '400':
          $ref: '#/components/responses/400_CONTRIBUTION'
        '404':
          $ref: '#/components/responses/404_unknown_ehr_id'
        '409':
          $ref: '#/components/responses/409'
  /ehr/{ehr_id}/contribution/{contribution_uid}:
    get:
      operationId: contribution_get
      summary: Get CONTRIBUTION by id
      description: |
        Retrieves a CONTRIBUTION identified by `contribution_uid` and associated with the EHR identified by `ehr_id`.

        ### Simplified Formats (FLAT / STRUCTURED)

        The `Accept` header MAY be set to one of the Simplified Formats MIME types - `application/openehr.wt.flat+json` or `application/openehr.wt.structured+json` - in addition to the canonical `application/json` / `application/xml`.

        When a Simplified Formats MIME type is requested, the **CONTRIBUTION envelope itself is still returned as canonical JSON** (`uid`, `versions[]` metadata, `audit`). Only the inner `versions[i].data` payload (`COMPOSITION`, `EHR_STATUS`, or `FOLDER`) is serialized in the chosen FLAT or STRUCTURED form. See [Simplified Formats](../simplified_formats.html) for the rules that apply to that inner payload.
      tags:
        - CONTRIBUTION
      parameters:
        - $ref: '#/components/parameters/ehr_id'
        - $ref: '#/components/parameters/contribution_uid'
        - $ref: '#/components/parameters/Accept_LOCATABLE'
      responses:
        '200':
          $ref: '#/components/responses/200_CONTRIBUTION'
        '404':
          $ref: '#/components/responses/404_CONTRIBUTION'
  /ehr/{ehr_id}/tags:
    get:
      operationId: ehr_tags_get
      summary: Get EHR tags
      description: |
        Retrieves the list of ITEM_TAG resources associated with any target VERSION or 
        VERSIONED_OBJECT within the EHR identified by `ehr_id`. 

        This list can be filtered by the given one or more `tag_key`, `tag_value`, `tag_target_path` query parameters. 
        In case no such parameter is provided then all ITEM_TAG resources will be retrieved.

        This will return an empty list when there is no matching ITEM_TAG associated with any target within given EHR.
          
        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.
      tags:
        - ITEM_TAG
      parameters:
        - $ref: '#/components/parameters/ehr_id'
        - $ref: '#/components/parameters/tag_key'
        - $ref: '#/components/parameters/tag_value'
        - $ref: '#/components/parameters/tag_target_path'
        - $ref: '#/components/parameters/Accept_canonical'
      responses:
        '200':
          $ref: '#/components/responses/200_COMPOSITION_ItemTagList_retrieved'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404_unknown_ehr_id'
  /ehr/{ehr_id}/composition/{uid_based_id}/tags:
    get:
      operationId: composition_tags_get
      summary: Get COMPOSITION tags
      description: |
        Retrieves the list of all ITEM_TAG resources associated with a given target COMPOSITION version or 
        VERSIONED_COMPOSITION identified by `uid_based_id` and owned by EHR identified by `ehr_id`.

        The `uid_based_id` 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`).
        The former is used to get the tags of a particular (target) version of the COMPOSITION version (e.g. one identified by `8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1`),
        whereas the latter (e.g. an identifier like `8849182c-82ad-4088-a07f-48ead4180515`) is be used to get the tags of the target VERSIONED_COMPOSITION container.

        This will return an empty list when there is no ITEM_TAG associated with the given target.
          
        More than one ITEM_TAG may be associated with a single target COMPOSITION or VERSIONED_COMPOSITION, in which case they are uniquely identified 
        by their `key` and `target_path` pair attributes.
      tags:
        - ITEM_TAG
      parameters:
        - $ref: '#/components/parameters/ehr_id'
        - $ref: '#/components/parameters/uid_based_id'
        - $ref: '#/components/parameters/Accept_canonical'
      responses:
        '200':
          $ref: '#/components/responses/200_COMPOSITION_ItemTagList_retrieved'
        '404':
          $ref: '#/components/responses/404_unknown_ehr_id_or_uid_based_id'
    put:
      operationId: composition_tags_update
      summary: Update COMPOSITION tags
      description: |
        Updates the list of all ITEM_TAG resources associated with a given target COMPOSITION version or 
        VERSIONED_COMPOSITION identified by `uid_based_id` and owned by EHR identified by `ehr_id`.

        The `uid_based_id` 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`).
        The former is used to update the tags of a particular COMPOSITION version (e.g. one identified by `8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1`),
        whereas the latter (e.g. an identifier like `8849182c-82ad-4088-a07f-48ead4180515`) is be used to update the tags of the target VERSIONED_COMPOSITION container.
          
        Providing an empty list will effectively remove all ITEM_TAG associated with the given target.

        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.
      tags:
        - ITEM_TAG
      parameters:
        - $ref: '#/components/parameters/ehr_id'
        - $ref: '#/components/parameters/uid_based_id'
        - $ref: '#/components/parameters/Prefer'
        - $ref: '#/components/parameters/Accept_canonical'
        - $ref: '#/components/parameters/ContentType_canonical'
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/UpdateItemTag'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/200_COMPOSITION_ItemTagList_updated'
        '204':
          $ref: '#/components/responses/204_updated'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404_unknown_ehr_id_or_uid_based_id'
  /ehr/{ehr_id}/composition/{uid_based_id}/tags/{key}:
    delete:
      operationId: composition_tags_delete
      summary: Delete COMPOSITION tags
      description: |
        Deletes the ITEM_TAG resource(s) identified by `tag_key`, associated with a given target COMPOSITION version or 
        VERSIONED_COMPOSITION identified by `uid_based_id` and owned by EHR identified by `ehr_id`.

        The `uid_based_id` 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`).
        The former is used to delete the tags a particular (target) version of the COMPOSITION version (e.g. one identified by `8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1`),
        whereas the latter (e.g. an identifier like `8849182c-82ad-4088-a07f-48ead4180515`) is be used to delete the tags of the target VERSIONED_COMPOSITION container.
      tags:
        - ITEM_TAG
      parameters:
        - $ref: '#/components/parameters/ehr_id'
        - $ref: '#/components/parameters/uid_based_id'
        - $ref: '#/components/parameters/key'
      responses:
        '204':
          $ref: '#/components/responses/204_deleted'
        '404':
          $ref: '#/components/responses/404_unknown_ehr_id_or_uid_based_id_or_key'
  /ehr/{ehr_id}/ehr_status/{uid_based_id}/tags:
    get:
      operationId: ehr_status_tags_get
      summary: Get EHR_STATUS tags
      description: |
        Retrieves the list of all ITEM_TAG resources associated with a given target EHR_STATUS version or 
        VERSIONED_EHR_STATUS identified by `uid_based_id` and owned by EHR identified by `ehr_id`.

        The `uid_based_id` 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`).
        The former is used to get the tags of a particular (target) version of the EHR_STATUS version (e.g. one identified by `8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1`),
        whereas the latter (e.g. an identifier like `8849182c-82ad-4088-a07f-48ead4180515`) is be used to get the tags of the target VERSIONED_EHR_STATUS container.

        This will return an empty list when there is no ITEM_TAG associated with the given target.
          
        More than one ITEM_TAG may be associated with a single target EHR_STATUS or VERSIONED_EHR_STATUS, in which case they are uniquely identified 
        by their `key` and `target_path` pair attributes.
      tags:
        - ITEM_TAG
      parameters:
        - $ref: '#/components/parameters/ehr_id'
        - $ref: '#/components/parameters/uid_based_id'
        - $ref: '#/components/parameters/Accept_canonical'
      responses:
        '200':
          $ref: '#/components/responses/200_EHR_STATUS_ItemTagList_retrieved'
        '404':
          $ref: '#/components/responses/404_unknown_ehr_id_or_uid_based_id'
    put:
      operationId: ehr_status_tags_update
      summary: Update EHR_STATUS tags
      description: |
        Updates the list of all ITEM_TAG resources associated with a given target EHR_STATUS version or 
        VERSIONED_EHR_STATUS identified by `uid_based_id` and owned by EHR identified by `ehr_id`.

        The `uid_based_id` 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`).
        The former is used to update the tags of a particular EHR_STATUS version (e.g. one identified by `8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1`),
        whereas the latter (e.g. an identifier like `8849182c-82ad-4088-a07f-48ead4180515`) is be used to update the tags of the target VERSIONED_EHR_STATUS container.
          
        Providing an empty list will effectively remove all ITEM_TAG associated with the given target.

        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.
      tags:
        - ITEM_TAG
      parameters:
        - $ref: '#/components/parameters/ehr_id'
        - $ref: '#/components/parameters/uid_based_id'
        - $ref: '#/components/parameters/Prefer'
        - $ref: '#/components/parameters/Accept_canonical'
        - $ref: '#/components/parameters/ContentType_canonical'
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/UpdateItemTag'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/200_EHR_STATUS_ItemTagList_updated'
        '204':
          $ref: '#/components/responses/204_updated'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404_unknown_ehr_id_or_uid_based_id'
  /ehr/{ehr_id}/ehr_status/{uid_based_id}/tags/{key}:
    delete:
      operationId: ehr_status_tags_delete
      summary: Delete EHR_STATUS tags
      description: |
        Deletes the ITEM_TAG resource(s) identified by `tag_key`, associated with a given target EHR_STATUS version or 
        VERSIONED_EHR_STATUS identified by `uid_based_id` and owned by EHR identified by `ehr_id`.

        The `uid_based_id` 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`).
        The former is used to delete the tags a particular (target) version of the EHR_STATUS version (e.g. one identified by `8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1`),
        whereas the latter (e.g. an identifier like `8849182c-82ad-4088-a07f-48ead4180515`) is be used to delete the tags of the target VERSIONED_EHR_STATUS container.
      tags:
        - ITEM_TAG
      parameters:
        - $ref: '#/components/parameters/ehr_id'
        - $ref: '#/components/parameters/uid_based_id'
        - $ref: '#/components/parameters/key'
      responses:
        '204':
          $ref: '#/components/responses/204_deleted'
        '404':
          $ref: '#/components/responses/404_unknown_ehr_id_or_uid_based_id_or_key'
components:
  schemas:
    VersionOfComposition:
      title: VERSION
      required:
        - contribution
        - commit_audit
        - data
      type: object
      properties:
        _type:
          type: string
        contribution:
          $ref: '#/components/schemas/ObjectRefOfHierObjectId'
        signature:
          type: string
        commit_audit:
          $ref: '#/components/schemas/AuditDetails'
        data:
          $ref: '#/components/schemas/Composition'
      description: A VERSION resource
    VersionOfEhrStatus:
      title: VERSION
      required:
        - contribution
        - commit_audit
        - data
      type: object
      properties:
        _type:
          type: string
        contribution:
          $ref: '#/components/schemas/ObjectRefOfHierObjectId'
        signature:
          type: string
        commit_audit:
          $ref: '#/components/schemas/AuditDetails'
        data:
          $ref: '#/components/schemas/EhrStatus'
      description: A VERSION resource
    ObjectId:
      title: OBJECT_ID
      required:
        - value
      type: object
      properties:
        _type:
          type: string
        value:
          type: string
      discriminator:
        propertyName: _type
        mapping:
          ARCHETYPE_ID: '#/components/schemas/ArchetypeId'
          GENERIC_ID: '#/components/schemas/GenericId'
          HIER_OBJECT_ID: '#/components/schemas/HierObjectId'
          OBJECT_VERSION_ID: '#/components/schemas/ObjectVersionId'
          TEMPLATE_ID: '#/components/schemas/TemplateId'
          TERMINOLOGY_ID: '#/components/schemas/TerminologyId'
          UID_BASED_ID: '#/components/schemas/UidBasedId'
    UidBasedId:
      title: UID_BASED_ID
      type: object
      allOf:
        - $ref: '#/components/schemas/ObjectId'
      x-discriminator-value: UID_BASED_ID
      discriminator:
        propertyName: _type
        mapping:
          HIER_OBJECT_ID: '#/components/schemas/HierObjectId'
          OBJECT_VERSION_ID: '#/components/schemas/ObjectVersionId'
    HierObjectId:
      title: HIER_OBJECT_ID
      required:
        - value
      type: object
      allOf:
        - $ref: '#/components/schemas/UidBasedId'
      properties:
        _type:
          enum:
            - HIER_OBJECT_ID
          type: string
        value:
          type: string
      example:
        value: 6cb19121-4307-4648-9da0-d62e4d51f19b
      x-discriminator-value: HIER_OBJECT_ID
    ArchetypeId:
      title: ARCHETYPE_ID
      type: object
      allOf:
        - $ref: '#/components/schemas/ObjectId'
      properties:
        _type:
          enum:
            - ARCHETYPE_ID
          type: string
      x-discriminator-value: ARCHETYPE_ID
    TemplateId:
      title: TEMPLATE_ID
      type: object
      allOf:
        - $ref: '#/components/schemas/ObjectId'
      properties:
        _type:
          enum:
            - TEMPLATE_ID
          type: string
      x-discriminator-value: TEMPLATE_ID
    TerminologyId:
      title: TERMINOLOGY_ID
      type: object
      allOf:
        - $ref: '#/components/schemas/ObjectId'
      properties:
        _type:
          enum:
            - TERMINOLOGY_ID
          type: string
      x-discriminator-value: TERMINOLOGY_ID
    GenericId:
      title: GENERIC_ID
      required:
        - scheme
      type: object
      allOf:
        - $ref: '#/components/schemas/ObjectId'
      properties:
        _type:
          enum:
            - GENERIC_ID
          type: string
        scheme:
          type: string
      x-discriminator-value: GENERIC_ID
    ObjectVersionId:
      title: OBJECT_VERSION_ID
      required:
        - value
      type: object
      allOf:
        - $ref: '#/components/schemas/UidBasedId'
      properties:
        _type:
          enum:
            - OBJECT_VERSION_ID
          type: string
      example:
        value: 6cb19121-4307-4648-9da0-d62e4d51f19b::openEHRSys.example.com::2
      x-discriminator-value: OBJECT_VERSION_ID
    ObjectRef:
      title: OBJECT_REF
      required:
        - namespace
        - type
        - id
      type: object
      properties:
        namespace:
          type: string
        type:
          type: string
        id:
          $ref: '#/components/schemas/ObjectId'
      example:
        id:
          _type: OBJECT_VERSION_ID
          value: fb458d9c-1323-42bc-b7f8-787f3660a0b5::openEHRSys.example.com::1
        namespace: local
        type: COMPOSITION
      discriminator:
        propertyName: _type
        mapping:
          OBJECT_REF: '#/components/schemas/ObjectRef'
          PARTY_REF: '#/components/schemas/PartyRef'
    ObjectRefOfObjectVersionId:
      title: OBJECT_REF
      type: object
      allOf:
        - $ref: '#/components/schemas/ObjectRef'
      properties:
        id:
          $ref: '#/components/schemas/ObjectVersionId'
      example:
        id:
          _type: OBJECT_VERSION_ID
          value: fb458d9c-1323-42bc-b7f8-787f3660a0b5::openEHRSys.example.com::1
        namespace: local
        type: COMPOSITION
    DataValue:
      title: DATA_VALUE
      type: object
      properties:
        _type:
          type: string
      discriminator:
        propertyName: _type
        mapping:
          DV_AMOUNT: '#/components/schemas/DvAmount'
          DV_BOOLEAN: '#/components/schemas/DvBoolean'
          DV_CODED_TEXT: '#/components/schemas/DvCodedText'
          DV_COUNT: '#/components/schemas/DvCount'
          DV_DATE: '#/components/schemas/DvDate'
          DV_DATE_TIME: '#/components/schemas/DvDateTime'
          DV_DURATION: '#/components/schemas/DvDuration'
          DV_EHR_URI: '#/components/schemas/DvEhrUri'
          DV_ENCAPSULATED: '#/components/schemas/DvEncapsulated'
          DV_IDENTIFIER: '#/components/schemas/DvIdentifier'
          DV_INTERVAL: '#/components/schemas/DvInterval'
          DV_INTERVAL_of_DATE_TIME: '#/components/schemas/DvIntervalOfDateTime'
          DV_MULTIMEDIA: '#/components/schemas/DvMultimedia'
          DV_ORDERED: '#/components/schemas/DvOrdered'
          DV_ORDINAL: '#/components/schemas/DvOrdinal'
          DV_PARSABLE: '#/components/schemas/DvParsable'
          DV_PROPORTION: '#/components/schemas/DvProportion'
          DV_QUANTIFIED: '#/components/schemas/DvQuantified'
          DV_QUANTITY: '#/components/schemas/DvQuantity'
          DV_SCALE: '#/components/schemas/DvScale'
          DV_STATE: '#/components/schemas/DvState'
          DV_TEMPORAL: '#/components/schemas/DvTemporal'
          DV_TEXT: '#/components/schemas/DvText'
          DV_TIME: '#/components/schemas/DvTime'
          DV_URI: '#/components/schemas/DvUri'
    CodePhrase:
      title: CODE_PHRASE
      required:
        - terminology_id
        - code_string
      type: object
      properties:
        terminology_id:
          $ref: '#/components/schemas/TerminologyId'
        code_string:
          type: string
        preferred_term:
          type: string
      example:
        terminology_id:
          value: local
        code_string: at0001
    DvInterval:
      title: DV_INTERVAL
      required:
        - lower_unbounded
        - upper_unbounded
        - lower_included
        - upper_included
      type: object
      allOf:
        - $ref: '#/components/schemas/DataValue'
      properties:
        _type:
          type: string
          default: DV_INTERVAL
        lower_unbounded:
          type: boolean
        upper_unbounded:
          type: boolean
        lower_included:
          type: boolean
        upper_included:
          type: boolean
      x-discriminator-value: DV_INTERVAL
      discriminator:
        propertyName: _type
        mapping:
          DV_INTERVAL_of_DATE_TIME: '#/components/schemas/DvIntervalOfDateTime'
    DvUri:
      title: DV_URI
      required:
        - value
      type: object
      allOf:
        - $ref: '#/components/schemas/DataValue'
      properties:
        _type:
          type: string
          default: DV_URI
        value:
          type: string
      example:
        _type: DV_URI
        value: https://www.example.com
      x-discriminator-value: DV_URI
      discriminator:
        propertyName: _type
        mapping:
          DV_EHR_URI: '#/components/schemas/DvEhrUri'
    DvEhrUri:
      title: DV_EHR_URI
      type: object
      allOf:
        - $ref: '#/components/schemas/DvUri'
      properties:
        _type:
          enum:
            - DV_EHR_URI
          type: string
      example:
        _type: DV_EHR_URI
        value: ehr://system_id/ehr_id/top_level_structure_locator/path_inside_top_level_structure
      x-discriminator-value: DV_EHR_URI
    DvText:
      title: DV_TEXT
      required:
        - value
      type: object
      allOf:
        - $ref: '#/components/schemas/DataValue'
      properties:
        _type:
          type: string
          default: DV_TEXT
        value:
          type: string
        hyperlink:
          $ref: '#/components/schemas/DvUri'
        formatting:
          type: string
        mappings:
          type: array
          items:
            $ref: '#/components/schemas/TermMapping'
        language:
          $ref: '#/components/schemas/CodePhrase'
        encoding:
          $ref: '#/components/schemas/CodePhrase'
      example:
        _type: DV_TEXT
        value: Text value
      x-discriminator-value: DV_TEXT
      discriminator:
        propertyName: _type
        mapping:
          DV_CODED_TEXT: '#/components/schemas/DvCodedText'
    DvCodedText:
      title: DV_CODED_TEXT
      required:
        - defining_code
      type: object
      allOf:
        - $ref: '#/components/schemas/DvText'
      properties:
        _type:
          enum:
            - DV_CODED_TEXT
          type: string
        defining_code:
          $ref: '#/components/schemas/CodePhrase'
      example:
        value: Coded text value
        defining_code:
          terminology_id:
            value: local
          code_string: at0001
      x-discriminator-value: DV_CODED_TEXT
    TermMapping:
      title: TERM_MAPPING
      required:
        - match
        - target
      type: object
      properties:
        match:
          pattern: ^[><=?]$
          type: string
        purpose:
          $ref: '#/components/schemas/DvCodedText'
        target:
          $ref: '#/components/schemas/CodePhrase'
    ReferenceRange:
      title: REFERENCE_RANGE
      required:
        - meaning
        - range
      type: object
      properties:
        meaning:
          $ref: '#/components/schemas/DvText'
        range:
          $ref: '#/components/schemas/DvInterval'
    DvOrdered:
      title: DV_ORDERED
      type: object
      allOf:
        - $ref: '#/components/schemas/DataValue'
      properties:
        _type:
          type: string
          default: DV_ORDERED
        normal_status:
          $ref: '#/components/schemas/CodePhrase'
        normal_range:
          $ref: '#/components/schemas/DvInterval'
        other_reference_ranges:
          type: array
          items:
            $ref: '#/components/schemas/ReferenceRange'
      x-discriminator-value: DV_ORDERED
      discriminator:
        propertyName: _type
        mapping:
          DV_AMOUNT: '#/components/schemas/DvAmount'
          DV_COUNT: '#/components/schemas/DvCount'
          DV_DATE: '#/components/schemas/DvDate'
          DV_DATE_TIME: '#/components/schemas/DvDateTime'
          DV_DURATION: '#/components/schemas/DvDuration'
          DV_ORDINAL: '#/components/schemas/DvOrdinal'
          DV_PROPORTION: '#/components/schemas/DvProportion'
          DV_QUANTIFIED: '#/components/schemas/DvQuantified'
          DV_QUANTITY: '#/components/schemas/DvQuantity'
          DV_SCALE: '#/components/schemas/DvScale'
          DV_TEMPORAL: '#/components/schemas/DvTemporal'
          DV_TIME: '#/components/schemas/DvTime'
    DvQuantified:
      title: DV_QUANTIFIED
      type: object
      allOf:
        - $ref: '#/components/schemas/DvOrdered'
      properties:
        _type:
          type: string
          default: DV_QUANTIFIED
        magnitude_status:
          type: string
          default: '='
      x-discriminator-value: DV_QUANTIFIED
      discriminator:
        propertyName: _type
        mapping:
          DV_AMOUNT: '#/components/schemas/DvAmount'
          DV_COUNT: '#/components/schemas/DvCount'
          DV_DATE: '#/components/schemas/DvDate'
          DV_DATE_TIME: '#/components/schemas/DvDateTime'
          DV_DURATION: '#/components/schemas/DvDuration'
          DV_PROPORTION: '#/components/schemas/DvProportion'
          DV_QUANTITY: '#/components/schemas/DvQuantity'
          DV_TEMPORAL: '#/components/schemas/DvTemporal'
          DV_TIME: '#/components/schemas/DvTime'
    DvAmount:
      title: DV_AMOUNT
      type: object
      allOf:
        - $ref: '#/components/schemas/DvQuantified'
      properties:
        _type:
          type: string
          default: DV_AMOUNT
        accuracy_is_percent:
          type: boolean
        accuracy:
          type: number
      x-discriminator-value: DV_AMOUNT
      discriminator:
        propertyName: _type
        mapping:
          DV_COUNT: '#/components/schemas/DvCount'
          DV_DURATION: '#/components/schemas/DvDuration'
          DV_PROPORTION: '#/components/schemas/DvProportion'
          DV_QUANTITY: '#/components/schemas/DvQuantity'
    DvDuration:
      title: DV_DURATION
      required:
        - value
      type: object
      allOf:
        - $ref: '#/components/schemas/DvAmount'
      properties:
        _type:
          enum:
            - DV_DURATION
          type: string
        value:
          type: string
      x-discriminator-value: DV_DURATION
    DvTemporal:
      title: DV_TEMPORAL
      type: object
      allOf:
        - $ref: '#/components/schemas/DvQuantified'
      properties:
        _type:
          type: string
          default: DV_TEMPORAL
        accuracy:
          $ref: '#/components/schemas/DvDuration'
      x-discriminator-value: DV_TEMPORAL
      discriminator:
        propertyName: _type
        mapping:
          DV_DATE: '#/components/schemas/DvDate'
          DV_DATE_TIME: '#/components/schemas/DvDateTime'
          DV_TIME: '#/components/schemas/DvTime'
    DvDateTime:
      title: DV_DATE_TIME
      required:
        - value
      type: object
      allOf:
        - $ref: '#/components/schemas/DvTemporal'
      properties:
        _type:
          enum:
            - DV_DATE_TIME
          type: string
        value:
          type: string
          format: date-time
      example:
        _type: DV_DATE_TIME
        value: '2017-08-15T10:37:15.422+02:00'
      x-discriminator-value: DV_DATE_TIME
    Ehr:
      title: EHR
      type: object
      properties:
        system_id:
          $ref: '#/components/schemas/HierObjectId'
        ehr_id:
          $ref: '#/components/schemas/HierObjectId'
        ehr_status:
          $ref: '#/components/schemas/ObjectRefOfObjectVersionId'
        ehr_access:
          $ref: '#/components/schemas/ObjectRefOfObjectVersionId'
        time_created:
          $ref: '#/components/schemas/DvDateTime'
      description: An EHR resource
      example:
        system_id:
          value: 9624982A-9F42-41A5-9318-AE13D5F5031F
        ehr_id:
          value: 7d44b88c-4199-4bad-97dc-d78268e01398
        ehr_status:
          id:
            _type: OBJECT_VERSION_ID
            value: 8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1
          namespace: local
          type: EHR_STATUS
        ehr_access:
          id:
            _type: OBJECT_VERSION_ID
            value: 59a8d0ac-140e-4feb-b2d6-af99f8e68af8::openEHRSys.example.com::1
          namespace: local
          type: EHR_ACCESS
        time_created:
          value: '2015-01-20T19:30:22.765+01:00'
    Pathable:
      title: PATHABLE
      type: object
      properties:
        _type:
          type: string
      discriminator:
        propertyName: _type
        mapping:
          ACTION: '#/components/schemas/Action'
          ACTIVITY: '#/components/schemas/Activity'
          ADMIN_ENTRY: '#/components/schemas/AdminEntry'
          CARE_ENTRY: '#/components/schemas/CareEntry'
          CLUSTER: '#/components/schemas/Clstr'
          COMPOSITION: '#/components/schemas/Composition'
          CONTENT_ITEM: '#/components/schemas/ContentItem'
          DATA_STRUCTURE: '#/components/schemas/DataStructure'
          EHR_STATUS: '#/components/schemas/EhrStatus'
          ELEMENT: '#/components/schemas/Element'
          ENTRY: '#/components/schemas/AbstractEntry'
          EVALUATION: '#/components/schemas/Evaluation'
          EVENT: '#/components/schemas/Event'
          EVENT_CONTEXT: '#/components/schemas/EventContext'
          FOLDER: '#/components/schemas/Folder'
          HISTORY: '#/components/schemas/History'
          INSTRUCTION: '#/components/schemas/Instruction'
          INSTRUCTION_DETAILS: '#/components/schemas/InstructionDetails'
          ISM_TRANSITION: '#/components/schemas/IsmTransition'
          ITEM: '#/components/schemas/Item'
          ITEM_LIST: '#/components/schemas/ItemList'
          ITEM_SINGLE: '#/components/schemas/ItemSingle'
          ITEM_STRUCTURE: '#/components/schemas/ItemStructure'
          ITEM_TABLE: '#/components/schemas/ItemTable'
          ITEM_TREE: '#/components/schemas/ItemTree'
          LOCATABLE: '#/components/schemas/Locatable'
          OBSERVATION: '#/components/schemas/Observation'
          SECTION: '#/components/schemas/Section'
          Versionable: '#/components/schemas/Versionable'
    Link:
      title: LINK
      required:
        - meaning
        - type
        - target
      type: object
      properties:
        meaning:
          $ref: '#/components/schemas/DvText'
        type:
          $ref: '#/components/schemas/DvText'
        target:
          $ref: '#/components/schemas/DvEhrUri'
    Archetyped:
      title: ARCHETYPED
      required:
        - archetype_id
        - rm_version
      type: object
      properties:
        archetype_id:
          $ref: '#/components/schemas/ArchetypeId'
        template_id:
          $ref: '#/components/schemas/TemplateId'
        rm_version:
          type: string
      example:
        archetype_id:
          value: openEHR-EHR-COMPOSITION.encounter.v1
        template_id:
          value: Example.v1::c7ec861c-c413-39ff-9965-a198ebf44747
        rm_version: 1.0.2
      additionalProperties: false
    DvIdentifier:
      title: DV_IDENTIFIER
      required:
        - id
      type: object
      allOf:
        - $ref: '#/components/schemas/DataValue'
      properties:
        _type:
          enum:
            - DV_IDENTIFIER
          type: string
        issuer:
          type: string
        assigner:
          type: string
        id:
          type: string
        type:
          type: string
      description: |
        Type for representing identifiers of real-world entities. Typical identifiers include drivers licence number, social security number, veterans affairs number, prescription id, order id, and so on.

        DV_IDENTIFIER is used to represent any identifier of a real thing, issued by some authority or agency.
      example:
        id: 16b74749-e6aa-4945-b760-b42bdc07098a
        type: Patient
      x-discriminator-value: DV_IDENTIFIER
    DvEncapsulated:
      title: DV_ENCAPSULATED
      required:
        - _type
      type: object
      allOf:
        - $ref: '#/components/schemas/DataValue'
      properties:
        _type:
          type: string
        charset:
          $ref: '#/components/schemas/CodePhrase'
        language:
          $ref: '#/components/schemas/CodePhrase'
      discriminator:
        propertyName: _type
        mapping:
          DV_MULTIMEDIA: '#/components/schemas/DvMultimedia'
          DV_PARSABLE: '#/components/schemas/DvParsable'
    DvMultimedia:
      title: DV_MULTIMEDIA
      required:
        - media_type
        - size
      type: object
      allOf:
        - $ref: '#/components/schemas/DvEncapsulated'
      properties:
        _type:
          enum:
            - DV_MULTIMEDIA
          type: string
        alternate_text:
          type: string
        uri:
          $ref: '#/components/schemas/DvUri'
        data:
          type: string
        media_type:
          $ref: '#/components/schemas/CodePhrase'
        compression_algorithm:
          $ref: '#/components/schemas/CodePhrase'
        integrity_check:
          type: string
        integrity_check_algorithm:
          $ref: '#/components/schemas/CodePhrase'
        thumbnail:
          $ref: '#/components/schemas/DvMultimedia'
        size:
          type: integer
      x-discriminator-value: DV_MULTIMEDIA
    DvParsable:
      title: DV_PARSABLE
      required:
        - value
        - formalism
      type: object
      allOf:
        - $ref: '#/components/schemas/DvEncapsulated'
      properties:
        _type:
          enum:
            - DV_PARSABLE
          type: string
        value:
          type: string
        formalism:
          type: string
      x-discriminator-value: DV_PARSABLE
    PartyRef:
      title: PARTY_REF
      type: object
      allOf:
        - $ref: '#/components/schemas/ObjectRef'
      properties:
        type:
          pattern: ^PERSON|ORGANISATION|GROUP|AGENT|ROLE|PARTY|ACTOR$
          type: string
        id:
          $ref: '#/components/schemas/HierObjectId'
      description: Identifier for parties in a demographic or identity service.
      example:
        id:
          _type: HIER_OBJECT_ID
          value: b52b9408-7048-4ec8-94bd-831fb0727e67
        namespace: local
        type: PERSON
    PartyProxy:
      title: PARTY_PROXY
      required:
        - _type
      type: object
      properties:
        _type:
          type: string
        external_ref:
          $ref: '#/components/schemas/PartyRef'
      discriminator:
        propertyName: _type
        mapping:
          PARTY_IDENTIFIED: '#/components/schemas/PartyIdentified'
          PARTY_RELATED: '#/components/schemas/PartyRelated'
          PARTY_SELF: '#/components/schemas/PartySelf'
    PartyIdentified:
      title: PARTY_IDENTIFIED
      type: object
      allOf:
        - $ref: '#/components/schemas/PartyProxy'
      properties:
        _type:
          type: string
          default: PARTY_IDENTIFIED
        name:
          type: string
        identifiers:
          type: array
          items:
            $ref: '#/components/schemas/DvIdentifier'
      example:
        _type: PARTY_IDENTIFIED
        external_ref:
          id:
            _type: GENERIC_ID
            value: 16b74749-e6aa-4945-b760-b42bdc07098a
            scheme: pid
          namespace: openEHRSys.example.com
          type: PERSON
        name: A name
      x-discriminator-value: PARTY_IDENTIFIED
      discriminator:
        propertyName: _type
        mapping:
          PARTY_RELATED: '#/components/schemas/PartyRelated'
    PartyRelated:
      title: PARTY_RELATED
      required:
        - relationship
      type: object
      allOf:
        - $ref: '#/components/schemas/PartyIdentified'
      properties:
        _type:
          enum:
            - PARTY_RELATED
          type: string
        relationship:
          $ref: '#/components/schemas/DvCodedText'
      x-discriminator-value: PARTY_RELATED
    PartySelf:
      title: PARTY_SELF
      type: object
      allOf:
        - $ref: '#/components/schemas/PartyProxy'
      properties:
        _type:
          enum:
            - PARTY_SELF
          type: string
      x-discriminator-value: PARTY_SELF
    Locatable:
      title: LOCATABLE
      required:
        - name
        - archetype_node_id
      type: object
      allOf:
        - $ref: '#/components/schemas/Pathable'
      properties:
        name:
          $ref: '#/components/schemas/DvText'
        archetype_node_id:
          type: string
          xml:
            attribute: true
        uid:
          $ref: '#/components/schemas/UidBasedId'
        links:
          type: array
          items:
            $ref: '#/components/schemas/Link'
        archetype_details:
          $ref: '#/components/schemas/Archetyped'
        feeder_audit:
          $ref: '#/components/schemas/FeederAudit'
      discriminator:
        propertyName: _type
        mapping:
          ACTION: '#/components/schemas/Action'
          ACTIVITY: '#/components/schemas/Activity'
          ADMIN_ENTRY: '#/components/schemas/AdminEntry'
          CARE_ENTRY: '#/components/schemas/CareEntry'
          CLUSTER: '#/components/schemas/Clstr'
          COMPOSITION: '#/components/schemas/Composition'
          CONTENT_ITEM: '#/components/schemas/ContentItem'
          DATA_STRUCTURE: '#/components/schemas/DataStructure'
          EHR_STATUS: '#/components/schemas/EhrStatus'
          ELEMENT: '#/components/schemas/Element'
          ENTRY: '#/components/schemas/AbstractEntry'
          EVALUATION: '#/components/schemas/Evaluation'
          EVENT: '#/components/schemas/Event'
          FOLDER: '#/components/schemas/Folder'
          HISTORY: '#/components/schemas/History'
          INSTRUCTION: '#/components/schemas/Instruction'
          ITEM: '#/components/schemas/Item'
          ITEM_LIST: '#/components/schemas/ItemList'
          ITEM_SINGLE: '#/components/schemas/ItemSingle'
          ITEM_STRUCTURE: '#/components/schemas/ItemStructure'
          ITEM_TABLE: '#/components/schemas/ItemTable'
          ITEM_TREE: '#/components/schemas/ItemTree'
          OBSERVATION: '#/components/schemas/Observation'
          SECTION: '#/components/schemas/Section'
          Versionable: '#/components/schemas/Versionable'
    DataStructure:
      title: DATA_STRUCTURE
      type: object
      allOf:
        - $ref: '#/components/schemas/Locatable'
      properties:
        _type:
          type: string
      x-discriminator-value: DATA_STRUCTURE
      discriminator:
        propertyName: _type
        mapping:
          ITEM_LIST: '#/components/schemas/ItemList'
          ITEM_SINGLE: '#/components/schemas/ItemSingle'
          ITEM_STRUCTURE: '#/components/schemas/ItemStructure'
          ITEM_TABLE: '#/components/schemas/ItemTable'
          ITEM_TREE: '#/components/schemas/ItemTree'
    ItemStructure:
      title: ITEM_STRUCTURE
      type: object
      allOf:
        - $ref: '#/components/schemas/DataStructure'
      properties:
        _type:
          type: string
      x-discriminator-value: ITEM_STRUCTURE
      discriminator:
        propertyName: _type
        mapping:
          ITEM_LIST: '#/components/schemas/ItemList'
          ITEM_SINGLE: '#/components/schemas/ItemSingle'
          ITEM_TABLE: '#/components/schemas/ItemTable'
          ITEM_TREE: '#/components/schemas/ItemTree'
    Item:
      title: ITEM
      type: object
      allOf:
        - $ref: '#/components/schemas/Locatable'
      properties:
        _type:
          type: string
      x-discriminator-value: ITEM
      discriminator:
        propertyName: _type
        mapping:
          CLUSTER: '#/components/schemas/Clstr'
          ELEMENT: '#/components/schemas/Element'
    DvBoolean:
      title: DV_BOOLEAN
      required:
        - value
      type: object
      allOf:
        - $ref: '#/components/schemas/DataValue'
      properties:
        _type:
          enum:
            - DV_BOOLEAN
          type: string
        value:
          type: boolean
      x-discriminator-value: DV_BOOLEAN
    DvCount:
      title: DV_COUNT
      required:
        - magnitude
      type: object
      allOf:
        - $ref: '#/components/schemas/DvAmount'
      properties:
        _type:
          enum:
            - DV_COUNT
          type: string
        magnitude:
          type: integer
          format: int64
      x-discriminator-value: DV_COUNT
    DvDate:
      title: DV_DATE
      required:
        - value
      type: object
      allOf:
        - $ref: '#/components/schemas/DvTemporal'
      properties:
        _type:
          enum:
            - DV_DATE
          type: string
        value:
          type: string
          format: date
      example:
        _type: DV_DATE
        value: '2017-08-15'
      x-discriminator-value: DV_DATE
    DvOrdinal:
      title: DV_ORDINAL
      required:
        - symbol
        - value
      type: object
      allOf:
        - $ref: '#/components/schemas/DvOrdered'
      properties:
        _type:
          enum:
            - DV_ORDINAL
          type: string
        symbol:
          $ref: '#/components/schemas/DvCodedText'
        value:
          type: integer
      x-discriminator-value: DV_ORDINAL
    DvProportion:
      title: DV_PROPORTION
      required:
        - numerator
        - denominator
        - type
      type: object
      allOf:
        - $ref: '#/components/schemas/DvAmount'
      properties:
        _type:
          enum:
            - DV_PROPORTION
          type: string
        numerator:
          type: number
        denominator:
          type: number
        type:
          type: integer
        precision:
          type: integer
      x-discriminator-value: DV_PROPORTION
    DvQuantity:
      title: DV_QUANTITY
      required:
        - magnitude
        - units
      type: object
      allOf:
        - $ref: '#/components/schemas/DvAmount'
      properties:
        _type:
          enum:
            - DV_QUANTITY
          type: string
        magnitude:
          type: number
        precision:
          type: integer
        units:
          type: string
        units_system:
          type: string
        units_display_name:
          type: string
      x-discriminator-value: DV_QUANTITY
    DvScale:
      title: DV_SCALE
      required:
        - symbol
        - value
      type: object
      allOf:
        - $ref: '#/components/schemas/DvOrdered'
      properties:
        _type:
          enum:
            - DV_SCALE
          type: string
        symbol:
          $ref: '#/components/schemas/DvCodedText'
        value:
          type: number
      x-discriminator-value: DV_SCALE
    DvState:
      title: DV_STATE
      required:
        - value
        - is_terminal
      type: object
      allOf:
        - $ref: '#/components/schemas/DataValue'
      properties:
        _type:
          enum:
            - DV_STATE
          type: string
        value:
          $ref: '#/components/schemas/DvCodedText'
        is_terminal:
          type: boolean
      x-discriminator-value: DV_STATE
    DvTime:
      title: DV_TIME
      required:
        - value
      type: object
      allOf:
        - $ref: '#/components/schemas/DvTemporal'
      properties:
        _type:
          enum:
            - DV_TIME
          type: string
        value:
          type: string
          format: time
      example:
        _type: DV_TIME
        value: '08:20:12'
      x-discriminator-value: DV_TIME
    Element:
      title: ELEMENT
      type: object
      allOf:
        - $ref: '#/components/schemas/Item'
      properties:
        _type:
          enum:
            - ELEMENT
          type: string
        null_flavour:
          $ref: '#/components/schemas/DvCodedText'
        value:
          $ref: '#/components/schemas/DataValue'
        null_reason:
          $ref: '#/components/schemas/DvText'
      x-discriminator-value: ELEMENT
    ItemSingle:
      title: ITEM_SINGLE
      required:
        - item
      type: object
      allOf:
        - $ref: '#/components/schemas/ItemStructure'
      properties:
        _type:
          enum:
            - ITEM_SINGLE
          type: string
        item:
          $ref: '#/components/schemas/Element'
      x-discriminator-value: ITEM_SINGLE
    ItemList:
      title: ITEM_LIST
      type: object
      allOf:
        - $ref: '#/components/schemas/ItemStructure'
      properties:
        _type:
          enum:
            - ITEM_LIST
          type: string
        items:
          type: array
          items:
            $ref: '#/components/schemas/Element'
      x-discriminator-value: ITEM_LIST
    Clstr:
      title: CLUSTER
      required:
        - items
      type: object
      allOf:
        - $ref: '#/components/schemas/Item'
      properties:
        _type:
          enum:
            - CLUSTER
          type: string
        items:
          type: array
          items:
            $ref: '#/components/schemas/Item'
      x-discriminator-value: CLUSTER
    ItemTable:
      title: ITEM_TABLE
      type: object
      allOf:
        - $ref: '#/components/schemas/ItemStructure'
      properties:
        _type:
          enum:
            - ITEM_TABLE
          type: string
        items:
          type: array
          items:
            $ref: '#/components/schemas/Clstr'
      x-discriminator-value: ITEM_TABLE
    ItemTree:
      title: ITEM_TREE
      type: object
      allOf:
        - $ref: '#/components/schemas/ItemStructure'
      properties:
        _type:
          enum:
            - ITEM_TREE
          type: string
        items:
          type: array
          items:
            $ref: '#/components/schemas/Item'
          description: See [ITEM](#tag/ITEM_schema) schema details.
      x-discriminator-value: ITEM_TREE
    FeederAuditDetails:
      title: FEEDER_AUDIT_DETAILS
      required:
        - system_id
      type: object
      properties:
        system_id:
          type: string
        location:
          $ref: '#/components/schemas/PartyIdentified'
        subject:
          $ref: '#/components/schemas/PartyProxy'
        provider:
          $ref: '#/components/schemas/PartyIdentified'
        time:
          $ref: '#/components/schemas/DvDateTime'
        version_id:
          type: string
        other_details:
          $ref: '#/components/schemas/ItemStructure'
    FeederAudit:
      title: FEEDER_AUDIT
      required:
        - originating_system_audit
      type: object
      properties:
        originating_system_item_ids:
          type: array
          items:
            $ref: '#/components/schemas/DvIdentifier'
        feeder_system_item_ids:
          type: array
          items:
            $ref: '#/components/schemas/DvIdentifier'
        original_content:
          $ref: '#/components/schemas/DvEncapsulated'
        originating_system_audit:
          $ref: '#/components/schemas/FeederAuditDetails'
        feeder_system_audit:
          $ref: '#/components/schemas/FeederAuditDetails'
    Versionable:
      title: Versionable
      type: object
      allOf:
        - $ref: '#/components/schemas/Locatable'
      description: A Versionable resource
      discriminator:
        propertyName: _type
        mapping:
          COMPOSITION: '#/components/schemas/Composition'
          EHR_STATUS: '#/components/schemas/EhrStatus'
          FOLDER: '#/components/schemas/Folder'
    EhrStatus:
      title: EHR_STATUS
      required:
        - subject
        - is_queryable
        - is_modifiable
      type: object
      allOf:
        - $ref: '#/components/schemas/Versionable'
      properties:
        _type:
          enum:
            - EHR_STATUS
          type: string
        subject:
          $ref: '#/components/schemas/PartyProxy'
        is_queryable:
          type: boolean
          default: true
        is_modifiable:
          type: boolean
          default: true
        other_details:
          $ref: '#/components/schemas/ItemStructure'
      description: An EHR_STATUS resource
      example:
        archetype_node_id: openEHR-EHR-EHR_STATUS.generic.v1
        name:
          value: EHR status
        uid:
          _type: OBJECT_VERSION_ID
          value: 8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1
        subject:
          _type: PARTY_SELF
        is_queryable: true
        is_modifiable: true
      x-discriminator-value: EHR_STATUS
    Identifier:
      title: Identifier
      required:
        - uid
      type: object
      properties:
        uid:
          type: string
          description: The (version) resource identifier.
      example:
        uid: 6cb19121-4307-4648-9da0-d62e4d51f19b::openEHRSys.example.com::2
    Error:
      title: Error
      required:
        - message
        - validationErrors
      type: object
      properties:
        message:
          type: string
        validationErrors:
          type: array
          items:
            type: string
          description: ''
      example:
        message: Error message
        validationErrors:
          - error1
          - error2
    UpdateItemTag:
      title: UPDATE_ITEM_TAG
      required:
        - key
      type: object
      properties:
        key:
          type: string
          description: Tag key (identifier)
        value:
          type: string
          description: Tag value
        target_path:
          type: string
          description: An AQL path withing the `target` used to tag a fine-grained element
      example:
        key: flag
        value: follow-up
        target_path: /context/start_time/value
      additionalProperties: false
    ObjectRefOfHierObjectId:
      title: OBJECT_REF
      type: object
      allOf:
        - $ref: '#/components/schemas/ObjectRef'
      properties:
        id:
          $ref: '#/components/schemas/HierObjectId'
      example:
        id:
          _type: HIER_OBJECT_ID
          value: 6cb19121-4307-4648-9da0-d62e4d51f19b
        namespace: local
        type: CONTRIBUTION
    VersionedObject:
      title: VERSIONED_OBJECT
      required:
        - uid
        - owner_id
        - time_created
      type: object
      properties:
        _type:
          type: string
        uid:
          $ref: '#/components/schemas/HierObjectId'
        owner_id:
          $ref: '#/components/schemas/ObjectRefOfHierObjectId'
        time_created:
          $ref: '#/components/schemas/DvDateTime'
      discriminator:
        propertyName: _type
        mapping:
          VERSIONED_COMPOSITION: '#/components/schemas/VersionedComposition'
          VERSIONED_EHR_STATUS: '#/components/schemas/VersionedEhrStatus'
    VersionedEhrStatus:
      title: VERSIONED_EHR_STATUS
      type: object
      allOf:
        - $ref: '#/components/schemas/VersionedObject'
      properties:
        _type:
          enum:
            - VERSIONED_EHR_STATUS
          type: string
      description: A VERSIONED_EHR_STATUS resource
      example:
        uid:
          value: 6cb19121-4307-4648-9da0-d62e4d51f19b
        owner_id:
          id:
            _type: HIER_OBJECT_ID
            value: 7d44b88c-4199-4bad-97dc-d78268e01398
          namespace: local
          type: EHR
        time_created:
          value: '2015-01-20T19:30:22.765+01:00'
      x-discriminator-value: VERSIONED_EHR_STATUS
    AuditDetails:
      title: AUDIT_DETAILS
      required:
        - system_id
        - time_committed
        - change_type
        - committer
      type: object
      properties:
        _type:
          type: string
          default: AUDIT_DETAILS
        system_id:
          type: string
        time_committed:
          $ref: '#/components/schemas/DvDateTime'
        change_type:
          $ref: '#/components/schemas/DvCodedText'
        description:
          $ref: '#/components/schemas/DvText'
        committer:
          $ref: '#/components/schemas/PartyProxy'
      description: The set of attributes required to document the committal of an information item to a repository.
      example:
        system_id: 9624982A-9F42-41A5-9318-AE13D5F5031F
        committer:
          _type: PARTY_IDENTIFIED
          name: A user name
        time_committed:
          value: '2017-08-15T10:37:15.422+02:00'
        change_type:
          value: creation
          defining_code:
            terminology_id:
              value: openehr
            code_string: '249'
        description:
          value: Description text
      x-discriminator-value: AUDIT_DETAILS
      discriminator:
        propertyName: _type
        mapping:
          ATTESTATION: '#/components/schemas/Attestation'
    RevisionHistoryItem:
      title: REVISION_HISTORY_ITEM
      required:
        - version_id
        - audits
      type: object
      properties:
        version_id:
          $ref: '#/components/schemas/ObjectVersionId'
        audits:
          type: array
          items:
            $ref: '#/components/schemas/AuditDetails'
      description: A REVISION_HISTORY_ITEM resource
      example:
        version_id:
          value: 8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1
        audits:
          - system_id: d60e2348-b083-48ce-93b9-916cef1d3a5a
            time_committed:
              value: '2015-01-20T19:30:22.765+01:00'
            change_type:
              value: creation
              defining_code:
                terminology_id:
                  value: openehr
                code_string: '249'
            description:
              value: An optional description string
            committer:
              _type: PARTY_IDENTIFIED
              name: A user name
    RevisionHistory:
      title: REVISION_HISTORY
      required:
        - items
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/RevisionHistoryItem'
      description: A REVISION_HISTORY resource
    DvIntervalOfDateTime:
      title: DV_INTERVAL_of_DATE_TIME
      type: object
      allOf:
        - $ref: '#/components/schemas/DvInterval'
      properties:
        _type:
          type: string
          default: DV_INTERVAL
        lower:
          $ref: '#/components/schemas/DvDateTime'
        upper:
          $ref: '#/components/schemas/DvDateTime'
      x-discriminator-value: DV_INTERVAL_of_DATE_TIME
    Participation:
      title: PARTICIPATION
      required:
        - function
        - performer
      type: object
      properties:
        function:
          $ref: '#/components/schemas/DvText'
        mode:
          $ref: '#/components/schemas/DvCodedText'
        performer:
          $ref: '#/components/schemas/PartyProxy'
        time:
          $ref: '#/components/schemas/DvIntervalOfDateTime'
    EventContext:
      title: EVENT_CONTEXT
      required:
        - start_time
        - setting
      type: object
      allOf:
        - $ref: '#/components/schemas/Pathable'
      properties:
        start_time:
          $ref: '#/components/schemas/DvDateTime'
        end_time:
          $ref: '#/components/schemas/DvDateTime'
        location:
          type: string
        setting:
          $ref: '#/components/schemas/DvCodedText'
        other_context:
          $ref: '#/components/schemas/ItemStructure'
        health_care_facility:
          $ref: '#/components/schemas/PartyIdentified'
        participations:
          type: array
          items:
            $ref: '#/components/schemas/Participation'
      x-discriminator-value: EVENT_CONTEXT
    ContentItem:
      title: CONTENT_ITEM
      type: object
      allOf:
        - $ref: '#/components/schemas/Locatable'
      discriminator:
        propertyName: _type
        mapping:
          ACTION: '#/components/schemas/Action'
          ADMIN_ENTRY: '#/components/schemas/AdminEntry'
          CARE_ENTRY: '#/components/schemas/CareEntry'
          ENTRY: '#/components/schemas/AbstractEntry'
          EVALUATION: '#/components/schemas/Evaluation'
          INSTRUCTION: '#/components/schemas/Instruction'
          OBSERVATION: '#/components/schemas/Observation'
          SECTION: '#/components/schemas/Section'
    Section:
      title: SECTION
      type: object
      allOf:
        - $ref: '#/components/schemas/ContentItem'
      properties:
        _type:
          enum:
            - SECTION
          type: string
        items:
          minItems: 1
          type: array
          items:
            $ref: '#/components/schemas/ContentItem'
          description: See [CONTENT_ITEM](#tag/CONTENT_ITEM_schema) schema details.
      x-discriminator-value: SECTION
    AbstractEntry:
      title: ENTRY
      required:
        - language
        - encoding
        - subject
      type: object
      allOf:
        - $ref: '#/components/schemas/ContentItem'
      properties:
        language:
          $ref: '#/components/schemas/CodePhrase'
        encoding:
          $ref: '#/components/schemas/CodePhrase'
        other_participations:
          type: array
          items:
            $ref: '#/components/schemas/Participation'
        workflow_id:
          $ref: '#/components/schemas/ObjectRef'
        subject:
          $ref: '#/components/schemas/PartyProxy'
        provider:
          $ref: '#/components/schemas/PartyProxy'
      discriminator:
        propertyName: _type
        mapping:
          ACTION: '#/components/schemas/Action'
          ADMIN_ENTRY: '#/components/schemas/AdminEntry'
          CARE_ENTRY: '#/components/schemas/CareEntry'
          EVALUATION: '#/components/schemas/Evaluation'
          INSTRUCTION: '#/components/schemas/Instruction'
          OBSERVATION: '#/components/schemas/Observation'
    AdminEntry:
      title: ADMIN_ENTRY
      required:
        - data
      type: object
      allOf:
        - $ref: '#/components/schemas/AbstractEntry'
      properties:
        _type:
          enum:
            - ADMIN_ENTRY
          type: string
        data:
          $ref: '#/components/schemas/ItemStructure'
      x-discriminator-value: ADMIN_ENTRY
    CareEntry:
      title: CARE_ENTRY
      type: object
      allOf:
        - $ref: '#/components/schemas/AbstractEntry'
      properties:
        protocol:
          $ref: '#/components/schemas/ItemStructure'
        guideline_id:
          $ref: '#/components/schemas/ObjectRef'
      discriminator:
        propertyName: _type
        mapping:
          ACTION: '#/components/schemas/Action'
          EVALUATION: '#/components/schemas/Evaluation'
          INSTRUCTION: '#/components/schemas/Instruction'
          OBSERVATION: '#/components/schemas/Observation'
    Event:
      title: EVENT
      required:
        - time
        - data
      type: object
      allOf:
        - $ref: '#/components/schemas/Locatable'
      properties:
        _type:
          type: string
          default: EVENT
        time:
          $ref: '#/components/schemas/DvDateTime'
        state:
          $ref: '#/components/schemas/ItemStructure'
        data:
          $ref: '#/components/schemas/ItemStructure'
      x-discriminator-value: EVENT
    History:
      title: HISTORY
      required:
        - origin
      type: object
      allOf:
        - $ref: '#/components/schemas/Locatable'
      properties:
        _type:
          type: string
          default: HISTORY
        origin:
          $ref: '#/components/schemas/DvDateTime'
        period:
          $ref: '#/components/schemas/DvDuration'
        duration:
          $ref: '#/components/schemas/DvDuration'
        summary:
          $ref: '#/components/schemas/ItemStructure'
        events:
          type: array
          items:
            $ref: '#/components/schemas/Event'
      x-discriminator-value: HISTORY
    Observation:
      title: OBSERVATION
      required:
        - data
      type: object
      allOf:
        - $ref: '#/components/schemas/CareEntry'
      properties:
        _type:
          enum:
            - OBSERVATION
          type: string
        data:
          $ref: '#/components/schemas/History'
        state:
          $ref: '#/components/schemas/History'
      x-discriminator-value: OBSERVATION
    Evaluation:
      title: EVALUATION
      required:
        - data
      type: object
      allOf:
        - $ref: '#/components/schemas/CareEntry'
      properties:
        _type:
          enum:
            - EVALUATION
          type: string
        data:
          $ref: '#/components/schemas/ItemStructure'
      x-discriminator-value: EVALUATION
    Activity:
      title: ACTIVITY
      required:
        - action_archetype_id
        - description
      type: object
      allOf:
        - $ref: '#/components/schemas/Locatable'
      properties:
        _type:
          enum:
            - ACTIVITY
          type: string
        timing:
          $ref: '#/components/schemas/DvParsable'
        action_archetype_id:
          type: string
        description:
          $ref: '#/components/schemas/ItemStructure'
      x-discriminator-value: ACTIVITY
    Instruction:
      title: INSTRUCTION
      required:
        - narrative
      type: object
      allOf:
        - $ref: '#/components/schemas/CareEntry'
      properties:
        _type:
          enum:
            - INSTRUCTION
          type: string
        narrative:
          $ref: '#/components/schemas/DvText'
        expiry_time:
          $ref: '#/components/schemas/DvDateTime'
        wf_definition:
          $ref: '#/components/schemas/DvParsable'
        activities:
          type: array
          items:
            $ref: '#/components/schemas/Activity'
      x-discriminator-value: INSTRUCTION
    IsmTransition:
      title: ISM_TRANSITION
      required:
        - current_state
      type: object
      allOf:
        - $ref: '#/components/schemas/Pathable'
      properties:
        _type:
          enum:
            - ISM_TRANSITION
          type: string
        current_state:
          $ref: '#/components/schemas/DvCodedText'
        transition:
          $ref: '#/components/schemas/DvCodedText'
        careflow_step:
          $ref: '#/components/schemas/DvCodedText'
        reason:
          type: array
          items:
            $ref: '#/components/schemas/DvText'
      x-discriminator-value: ISM_TRANSITION
    LocatableRef:
      title: LOCATABLE_REF
      required:
        - namespace
        - type
        - id
      type: object
      properties:
        namespace:
          type: string
        type:
          type: string
        id:
          $ref: '#/components/schemas/UidBasedId'
        path:
          type: string
    InstructionDetails:
      title: INSTRUCTION_DETAILS
      required:
        - instruction_id
        - activity_id
      type: object
      allOf:
        - $ref: '#/components/schemas/Pathable'
      properties:
        _type:
          enum:
            - INSTRUCTION_DETAILS
          type: string
        instruction_id:
          $ref: '#/components/schemas/LocatableRef'
        activity_id:
          type: string
        wf_details:
          $ref: '#/components/schemas/ItemStructure'
      x-discriminator-value: INSTRUCTION_DETAILS
    Action:
      title: ACTION
      required:
        - time
        - ism_transition
        - description
      type: object
      allOf:
        - $ref: '#/components/schemas/CareEntry'
      properties:
        _type:
          enum:
            - ACTION
          type: string
        time:
          $ref: '#/components/schemas/DvDateTime'
        ism_transition:
          $ref: '#/components/schemas/IsmTransition'
        instruction_details:
          $ref: '#/components/schemas/InstructionDetails'
        description:
          $ref: '#/components/schemas/ItemStructure'
      x-discriminator-value: ACTION
    Composition:
      title: COMPOSITION
      required:
        - language
        - territory
        - category
        - composer
      type: object
      allOf:
        - $ref: '#/components/schemas/Versionable'
      properties:
        _type:
          enum:
            - COMPOSITION
          type: string
        language:
          $ref: '#/components/schemas/CodePhrase'
        territory:
          $ref: '#/components/schemas/CodePhrase'
        category:
          $ref: '#/components/schemas/DvCodedText'
        context:
          $ref: '#/components/schemas/EventContext'
        composer:
          $ref: '#/components/schemas/PartyProxy'
        content:
          minItems: 1
          type: array
          items:
            $ref: '#/components/schemas/ContentItem'
          description: See [CONTENT_ITEM](#tag/CONTENT_ITEM_schema) schema details.
      description: A COMPOSITION resource
      example:
        archetype_node_id: openEHR-EHR-COMPOSITION.encounter.v1
        name:
          value: Vital Signs
        uid:
          _type: OBJECT_VERSION_ID
          value: 8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1
        archetype_details:
          archetype_id:
            value: openEHR-EHR-COMPOSITION.encounter.v1
          template_id:
            value: Example.v1::c7ec861c-c413-39ff-9965-a198ebf44747
          rm_version: 1.0.2
        language:
          terminology_id:
            value: ISO_639-1
          code_string: en
        territory:
          terminology_id:
            value: ISO_3166-1
          code_string: NL
        category:
          value: event
          defining_code:
            terminology_id:
              value: openehr
            code_string: '433'
        composer:
          _type: PARTY_IDENTIFIED
          external_ref:
            id:
              _type: GENERIC_ID
              value: 16b74749-e6aa-4945-b760-b42bdc07098a
              scheme: pid
            namespace: openEHRSys.example.com
            type: PERSON
          name: A name
        context:
          start_time:
            value: '2014-11-18T09:50:35.000+01:00'
          setting:
            value: other care
            defining_code:
              terminology_id:
                value: openehr
              code_string: '238'
        content: []
      x-discriminator-value: COMPOSITION
    Folder:
      title: FOLDER
      type: object
      allOf:
        - $ref: '#/components/schemas/Versionable'
      properties:
        _type:
          enum:
            - FOLDER
          type: string
        items:
          type: array
          items:
            $ref: '#/components/schemas/ObjectRef'
        folders:
          type: array
          items:
            $ref: '#/components/schemas/Folder'
        details:
          $ref: '#/components/schemas/ItemStructure'
      description: A FOLDER resource
      example:
        archetype_node_id: openEHR-EHR-FOLDER.directory.v1
        name:
          value: Directory
        uid:
          _type: OBJECT_VERSION_ID
          value: 8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1
        items: []
        folders: []
      x-discriminator-value: FOLDER
    Version:
      title: VERSION
      required:
        - contribution
        - commit_audit
        - data
      type: object
      properties:
        _type:
          type: string
        contribution:
          $ref: '#/components/schemas/ObjectRefOfHierObjectId'
        signature:
          type: string
        commit_audit:
          $ref: '#/components/schemas/AuditDetails'
        data:
          $ref: '#/components/schemas/Versionable'
      description: A VERSION resource
      discriminator:
        propertyName: _type
        mapping:
          IMPORTED_VERSION: '#/components/schemas/ImportedVersion'
          ORIGINAL_VERSION: '#/components/schemas/OriginalVersion'
    Attestation:
      title: ATTESTATION
      required:
        - reason
        - is_pending
      type: object
      allOf:
        - $ref: '#/components/schemas/AuditDetails'
      properties:
        _type:
          enum:
            - ATTESTATION
          type: string
        attested_view:
          $ref: '#/components/schemas/DvMultimedia'
        proof:
          type: string
        items:
          type: array
          items:
            $ref: '#/components/schemas/DvEhrUri'
        reason:
          $ref: '#/components/schemas/DvText'
        is_pending:
          type: boolean
      x-discriminator-value: ATTESTATION
    OriginalVersion:
      title: ORIGINAL_VERSION
      required:
        - uid
        - lifecycle_state
      type: object
      allOf:
        - $ref: '#/components/schemas/Version'
      properties:
        _type:
          enum:
            - ORIGINAL_VERSION
          type: string
        uid:
          $ref: '#/components/schemas/ObjectVersionId'
        preceding_version_uid:
          $ref: '#/components/schemas/ObjectVersionId'
        other_input_version_uids:
          type: array
          items:
            $ref: '#/components/schemas/ObjectVersionId'
        lifecycle_state:
          $ref: '#/components/schemas/DvCodedText'
        attestations:
          type: array
          items:
            $ref: '#/components/schemas/Attestation'
      x-discriminator-value: ORIGINAL_VERSION
    ImportedVersion:
      title: IMPORTED_VERSION
      required:
        - item
      type: object
      allOf:
        - $ref: '#/components/schemas/Version'
      properties:
        _type:
          enum:
            - IMPORTED_VERSION
          type: string
        item:
          $ref: '#/components/schemas/OriginalVersion'
      x-discriminator-value: IMPORTED_VERSION
    VersionedComposition:
      title: VERSIONED_COMPOSITION
      type: object
      allOf:
        - $ref: '#/components/schemas/VersionedObject'
      properties:
        _type:
          enum:
            - VERSIONED_COMPOSITION
          type: string
      description: A VERSIONED_COMPOSITION resource
      example:
        uid:
          value: 8849182c-82ad-4088-a07f-48ead4180515
        owner_id:
          id:
            _type: HIER_OBJECT_ID
            value: 7d44b88c-4199-4bad-97dc-d78268e01398
          namespace: local
          type: EHR
        time_created:
          value: '2015-01-20T19:30:22.765+01:00'
      x-discriminator-value: VERSIONED_COMPOSITION
    UpdateAudit:
      title: UPDATE_AUDIT
      required:
        - change_type
        - committer
      type: object
      properties:
        _type:
          type: string
          default: UPDATE_AUDIT
        system_id:
          type: string
          description: |
            Optional identifier of the system where the change was committed. When provided it will be
            validated; when omitted the server sets its own value.
        change_type:
          $ref: '#/components/schemas/DvCodedText'
        description:
          $ref: '#/components/schemas/DvText'
        committer:
          $ref: '#/components/schemas/PartyProxy'
      description: |
        The set of attributes required to document the committal of an information item to a repository.

        `UPDATE_AUDIT` is a REST commit DTO, not an RM class: structurally an `AUDIT_DETAILS` without the
        server-assigned attributes (`time_committed` is always set by the server; `system_id` is optional on
        commit). The server uses it to create the persisted `AUDIT_DETAILS` object.

        Clients SHOULD send `_type: "UPDATE_AUDIT"`. For interoperability with existing implementations,
        servers SHOULD additionally accept `_type: "AUDIT_DETAILS"` or an omitted `_type` for this attribute.
      example:
        _type: UPDATE_AUDIT
        change_type:
          value: creation
          defining_code:
            terminology_id:
              value: openehr
            code_string: '249'
        description: Description text
        committer:
          _type: PARTY_IDENTIFIED
          name: A user name
      x-discriminator-value: UPDATE_AUDIT
      discriminator:
        propertyName: _type
        mapping:
          UPDATE_ATTESTATION: '#/components/schemas/UpdateAttestation'
    UpdateAttestation:
      title: UPDATE_ATTESTATION
      required:
        - reason
        - is_pending
      type: object
      allOf:
        - $ref: '#/components/schemas/UpdateAudit'
      properties:
        _type:
          enum:
            - UPDATE_ATTESTATION
          type: string
        attested_view:
          $ref: '#/components/schemas/DvMultimedia'
        proof:
          type: string
        items:
          type: array
          items:
            $ref: '#/components/schemas/DvEhrUri'
        reason:
          $ref: '#/components/schemas/DvText'
        is_pending:
          type: boolean
      x-discriminator-value: UPDATE_ATTESTATION
    UpdateVersion:
      title: UPDATE_VERSION
      required:
        - lifecycle_state
        - data
        - commit_audit
      type: object
      properties:
        preceding_version_uid:
          $ref: '#/components/schemas/ObjectVersionId'
        signature:
          type: string
        lifecycle_state:
          $ref: '#/components/schemas/DvCodedText'
        attestations:
          type: array
          items:
            $ref: '#/components/schemas/UpdateAttestation'
        data:
          $ref: '#/components/schemas/Versionable'
        commit_audit:
          $ref: '#/components/schemas/UpdateAudit'
    NewContribution:
      title: NewContribution
      required:
        - versions
        - audit
      type: object
      properties:
        uid:
          $ref: '#/components/schemas/HierObjectId'
        versions:
          type: array
          items:
            $ref: '#/components/schemas/UpdateVersion'
        audit:
          $ref: '#/components/schemas/UpdateAudit'
      description: A new (un-committed) CONTRIBUTION resource
    Contribution:
      title: CONTRIBUTION
      required:
        - uid
        - versions
        - audit
      type: object
      properties:
        uid:
          $ref: '#/components/schemas/HierObjectId'
        versions:
          minItems: 1
          type: array
          items:
            $ref: '#/components/schemas/ObjectRefOfObjectVersionId'
        audit:
          $ref: '#/components/schemas/AuditDetails'
      description: A CONTRIBUTION resource
      example:
        uid:
          value: 0826851c-c4c2-4d61-92b9-410fb8275ff0
        versions:
          - id:
              _type: OBJECT_VERSION_ID
              value: fb458d9c-1323-42bc-b7f8-787f3660a0b5::openEHRSys.example.com::1
            namespace: local
            type: COMPOSITION
          - id:
              _type: OBJECT_VERSION_ID
              value: abcdefgh-1323-42bc-b7f8-787f3660a0ba::openEHRSys.example.com::1
            namespace: local
            type: FOLDER
        audit:
          system_id: 9624982A-9F42-41A5-9318-AE13D5F5031F
          committer:
            _type: PARTY_IDENTIFIED
            name: A user name
          time_committed:
            value: '2017-08-15T10:37:15.422+02:00'
          change_type:
            value: creation
            defining_code:
              terminology_id:
                value: openehr
              code_string: '249'
          description:
            value: Description text
    ItemTag:
      title: ITEM_TAG
      required:
        - key
        - target
        - owner_id
      type: object
      properties:
        key:
          type: string
        value:
          type: string
        target_path:
          type: string
        target:
          $ref: '#/components/schemas/ObjectRef'
        owner_id:
          $ref: '#/components/schemas/ObjectRefOfHierObjectId'
      additionalProperties: false
      discriminator:
        propertyName: _type
        mapping:
          ITEM_TAG: '#/components/schemas/ItemTag'
    ItemTagOfComposition:
      title: ITEM_TAG
      type: object
      allOf:
        - $ref: '#/components/schemas/ItemTag'
      example:
        key: flag
        value: follow-up
        target_path: /context/start_time/value
        target:
          id:
            _type: HIER_OBJECT_ID
            value: 8849182c-82ad-4088-a07f-48ead4180515
          namespace: local
          type: COMPOSITION
        owner_id:
          id:
            _type: HIER_OBJECT_ID
            value: 7d44b88c-4199-4bad-97dc-d78268e01398
          namespace: local
          type: EHR
    ItemTagOfEhrStatus:
      title: ITEM_TAG
      type: object
      allOf:
        - $ref: '#/components/schemas/ItemTag'
      example:
        key: flag
        value: follow-up
        target_path: ''
        target:
          id:
            _type: HIER_OBJECT_ID
            value: 8849182c-82ad-4088-a07f-48ead4180515
          namespace: local
          type: EHR_STATUS
        owner_id:
          id:
            _type: HIER_OBJECT_ID
            value: 7d44b88c-4199-4bad-97dc-d78268e01398
          namespace: local
          type: EHR
  parameters:
    subject_id:
      name: subject_id
      in: query
      description: |
        The EHR subject id.
      required: true
      style: form
      explode: true
      schema:
        type: string
        example: ins01
    subject_namespace:
      name: subject_namespace
      in: query
      description: |
        The EHR subject id namespace.
      required: true
      style: form
      explode: true
      schema:
        type: string
        example: examples
    Accept_canonical:
      name: Accept
      in: header
      style: simple
      schema:
        type: string
        enum:
          - application/json
          - application/xml
    Prefer:
      name: Prefer
      in: header
      description: |
        Request header to indicate the preference over response details.
        The response will contain the entire resource when the `Prefer` header has a value of `return=representation`, or only the resource identifier (e.g., the `uid`) when the value is `return=identifier`.
      required: false
      style: simple
      schema:
        type: string
        enum:
          - return=representation
          - return=minimal
          - return=identifier
        default: return=minimal
    ContentType_LOCATABLE:
      name: Content-Type
      in: header
      style: simple
      schema:
        type: string
        enum:
          - application/json
          - application/xml
          - application/openehr.wt.flat+json
          - application/openehr.wt.structured+json
    ehr_id:
      name: ehr_id
      in: path
      description: |
        EHR identifier taken from EHR.ehr_id.value.
      required: true
      style: simple
      schema:
        type: string
        format: uuid
        example: 7d44b88c-4199-4bad-97dc-d78268e01398
    version_uid:
      name: version_uid
      in: path
      description: |
        VERSION identifier taken from VERSION.uid.value.
      required: true
      style: simple
      schema:
        type: string
        example: 6cb19121-4307-4648-9da0-d62e4d51f19b::openEHRSys.example.com::2
    Accept_LOCATABLE:
      name: Accept
      in: header
      style: simple
      schema:
        type: string
        enum:
          - application/json
          - application/xml
          - application/openehr.wt.flat+json
          - application/openehr.wt.structured+json
    version_at_time:
      name: version_at_time
      in: query
      description: |
        A given time in the extended ISO 8601 format.
      style: form
      explode: true
      schema:
        type: string
        format: datetime
        example: '2015-01-20T19:30:22.765+01:00'
    If-Match:
      name: If-Match
      in: header
      description: |
        Header to make the request conditional. 
        Together with `ETag` request tag, it helps to prevent simultaneous updates of a resource from overwriting each other ("mid-air collisions").
        The format is always an `version_uid` identifier enclosed by double quotes.
        The operation will be performed only if the existing latest `version_uid` of the resource (i.e. the `preceding_version_uid`) matches this header's value.
      required: true
      style: simple
      schema:
        type: string
        example: '"6cb19121-4307-4648-9da0-d62e4d51f19b::openEHRSys.example.com::1"'
    openehr-item-tag:
      name: openehr-item-tag
      in: header
      description: |
        The list of all ITEM_TAG to be set and associated with the current VERSIONED_OBJECT - see [details](overview.html#tag/Requests_and_responses/HTTP-headers/openehr-item-tag-and-openehr-version-item-tag).
      required: false
      style: simple
      explode: true
      schema:
        type: array
        items:
          $ref: '#/components/schemas/UpdateItemTag'
      example: key="category",value="final"; key="flag",value="follow-up",target_path="/composition/start_time/value"
    openehr-version-item-tag:
      name: openehr-version-item-tag
      in: header
      description: |
        The list of all ITEM_TAG to be set and associated with the current VERSION - see [details](overview.html#tag/Requests_and_responses/HTTP-headers/openehr-item-tag-and-openehr-version-item-tag).
      required: false
      style: simple
      explode: true
      schema:
        type: array
        items:
          $ref: '#/components/schemas/UpdateItemTag'
      example: key="category",value="final"; key="flag",value="follow-up",target_path="/composition/start_time/value"
    ContentType_canonical:
      name: Content-Type
      in: header
      style: simple
      schema:
        type: string
        enum:
          - application/json
          - application/xml
    uid_based_id:
      name: uid_based_id
      in: path
      description: |
        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`).
      required: true
      style: simple
      schema:
        type: string
        example: 8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1
    uid_based_id_as_versioned_object_uid:
      name: uid_based_id
      in: path
      description: |
        An identifier in a form of a HIER_OBJECT_ID identifier taken from VERSIONED_OBJECT.uid.value (i.e. a `versioned_object_uid`).
      required: true
      style: simple
      schema:
        type: string
        format: uuid
        example: 8849182c-82ad-4088-a07f-48ead4180515
    uid_based_id_as_version_uid:
      name: uid_based_id
      in: path
      description: |
        An identifier in a form of an OBJECT_VERSION_ID identifier taken from VERSION.uid.value (i.e. a `version_uid`).
      required: true
      style: simple
      schema:
        type: string
        example: 8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1
    versioned_object_uid_COMPOSITION:
      name: versioned_object_uid
      in: path
      description: |
        VERSIONED_COMPOSITION identifier taken from VERSIONED_COMPOSITION.uid.value.
      required: true
      style: simple
      schema:
        type: string
        format: uuid
        example: 8849182c-82ad-4088-a07f-48ead4180515
    version_uid_COMPOSITION:
      name: version_uid
      in: path
      description: |
        VERSION identifier taken from VERSION.uid.value.
      required: true
      style: simple
      schema:
        type: string
        example: 8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1
    path:
      name: path
      in: query
      description: |
        A path to a sub-folder; consists of slash-separated values of the name attribute of FOLDERs in the directory.
      style: form
      explode: true
      schema:
        type: string
        example: episodes/a/b/c
    contribution_uid:
      name: contribution_uid
      in: path
      description: |
        The CONTRIBUTION uid.
      required: true
      style: simple
      schema:
        type: string
        format: uuid
        example: 0826851c-c4c2-4d61-92b9-410fb8275ff0
    tag_key:
      name: tag_key
      in: query
      style: form
      explode: true
      schema:
        type: string
        example: flag
    tag_value:
      name: tag_value
      in: query
      style: form
      explode: true
      schema:
        type: string
        example: follow-up
    tag_target_path:
      name: tag_target_path
      in: query
      style: form
      explode: true
      schema:
        type: string
        example: /context/start_time/value
    key:
      name: key
      in: path
      description: |
        The ITEM_TAG key.
      required: true
      style: simple
      schema:
        type: string
        example: flag
  headers:
    ContentType_canonical:
      schema:
        type: string
        enum:
          - application/xml
          - application/json
    ETag_EHR:
      description: |
        The `ETag` (i.e. entity tag) response header is the `ehr_id` identifier, enclosed by double quotes.
      schema:
        type: string
        example: W/"7d44b88c-4199-4bad-97dc-d78268e01398"
    Location_EHR:
      description: |
        The `Location` response header indicates the URL of the EHR resource.
      schema:
        type: string
        format: url
        example: https://openEHRSys.example.com/v1/ehr/7d44b88c-4199-4bad-97dc-d78268e01398
    ETag:
      description: |
        The `ETag` (i.e. entity tag) response header is an identifier (e.g. a `version_uid` enclosed by double quotes) for a specific version of a resource.
      schema:
        type: string
        example: W/"6cb19121-4307-4648-9da0-d62e4d51f19b::openEHRSys.example.com::2"
    Location_deprecated:
      description: |
        The `Location` is [deprecated](overview.html#tag/Requests_and_responses/HTTP-headers/Location) for this action.
      deprecated: true
      schema:
        type: string
    ContentType_LOCATABLE:
      schema:
        type: string
        enum:
          - application/xml
          - application/json
          - application/openehr.wt.flat+json
          - application/openehr.wt.structured+json
    openehr-item-tag:
      description: |
        The list of all ITEM_TAG associated with the current VERSIONED_OBJECT - see [details](overview.html#tag/Requests_and_responses/HTTP-headers/openehr-item-tag-and-openehr-version-item-tag).
      schema:
        type: string
    openehr-version-item-tag:
      description: |
        The list of all ITEM_TAG associated with the current VERSION - see [details](overview.html#tag/Requests_and_responses/HTTP-headers/openehr-item-tag-and-openehr-version-item-tag).
      schema:
        type: string
    Location_EHR_STATUS:
      description: |
        The `Location` response header indicates the URL of the EHR_STATUS resource.
      schema:
        type: string
        format: url
        example: https://openEHRSys.example.com/v1/ehr/7d44b88c-4199-4bad-97dc-d78268e01398/ehr_status/6cb19121-4307-4648-9da0-d62e4d51f19b::openEHRSys.example.com::2
    Location_version:
      description: |
        The `Location` response header indicates the URL of the resource version resulted from the operation.
      schema:
        type: string
        format: url
    ETag_VERSION:
      description: |
        The `ETag` (i.e. entity tag) response header is the VERSION identifier (i.e. the `version_uid`) enclosed by double quotes.
      schema:
        type: string
        example: W/"6cb19121-4307-4648-9da0-d62e4d51f19b::openEHRSys.example.com::2"
    ETag_COMPOSITION:
      description: |
        The `ETag` (i.e. entity tag) response header is an identifier (e.g. a `version_uid` enclosed by double quotes) for a specific version of a resource.
      schema:
        type: string
        example: W/"8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1
    Location_COMPOSITION:
      description: |
        The `Location` response header indicates the URL of the COMPOSITION resource.
      schema:
        type: string
        format: url
        example: https://openEHRSys.example.com/v1/ehr/7d44b88c-4199-4bad-97dc-d78268e01398/composition/8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1
    ETag_VERSION_of_COMPOSITION:
      description: |
        The `ETag` (i.e. entity tag) response header is the VERSION identifier (i.e. the `version_uid`) enclosed by double quotes.
      schema:
        type: string
        example: W/"8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::2"
    ETag_FOLDER:
      description: |
        The `ETag` (i.e. entity tag) response header is an identifier (e.g. a `version_uid` enclosed by double quotes) for a specific version of a resource.
      schema:
        type: string
        example: W/"8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1"
    Location_directory:
      description: |
        The `Location` response header indicates the URL of the directory FOLDER resource.
      schema:
        type: string
        format: url
        example: https://openEHRSys.example.com/v1/ehr/7d44b88c-4199-4bad-97dc-d78268e01398/directory/8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1
    ETag_CONTRIBUTION:
      description: |
        The `ETag` (i.e. entity tag) response header is the `contribution_uid` identifier, enclosed by double quotes.
      schema:
        type: string
        example: W/"0826851c-c4c2-4d61-92b9-410fb8275ff0"
    Location_CONTRIBUTION:
      description: |
        The `Location` response header indicates the URL of the CONTRIBUTION resource.
      schema:
        type: string
        format: url
        example: https://openEHRSys.example.com/v1/ehr/7d44b88c-4199-4bad-97dc-d78268e01398/contribution/0826851c-c4c2-4d61-92b9-410fb8275ff0
  responses:
    '400':
      description: |
        `400 Bad Request` is returned when the request could not be parsed or is invalid (e.g. malformed request URL syntax, missing required header or parameter, or syntactically invalid header, parameter or content). 
        The response body MAY contain error details.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '409':
      description: |
        `409 Conflict` is returned when a resource with same identifier(s) already exists.
    '422':
      description: |
        `422 Unprocessable Entity` is returned when the content type and syntax is correct, could be converted to a resource, but there are semantic validation errors, such as the underlying template is not known or is not validating the supplied resource.
    200_EHR:
      description: |
        `200 OK` is returned when the requested EHR resource is successfully retrieved.
      headers:
        Content-Type:
          $ref: '#/components/headers/ContentType_canonical'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Ehr'
    404_EHR_subject:
      description: |
        `404 Not Found` is returned when an EHR with supplied subject parameters does not exist.
    201_EHR:
      description: |
        `201 Created` is returned when the EHR has been successfully created, 
        with the full resource in the body when `Prefer` header is `return=representation`, or only its identifiers when `Prefer` header is `return=identifier`.
      headers:
        ETag:
          $ref: '#/components/headers/ETag_EHR'
        Location:
          $ref: '#/components/headers/Location_EHR'
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/Ehr'
              - $ref: '#/components/schemas/Identifier'
    409_EHR:
      description: |
        `409 Conflict` Unable to create a new EHR due to a conflict with an already existing EHR with the same subject id, namespace pair, whenever EHR_STATUS is supplied.
    404_unknown_ehr_id:
      description: |
        `404 Not Found` is returned when an EHR with `ehr_id` does not exist.
    409_EHR_with_id:
      description: |
        `409 Conflict` Unable to create a new EHR due to a conflict with an already existing EHR. 
        Can happen when the supplied `ehr_id` is already used by an existing EHR.
    200_EHR_STATUS_retrieved:
      description: |
        `200 OK` is returned when the requested EHR_STATUS is successfully retrieved.
      headers:
        ETag:
          $ref: '#/components/headers/ETag'
        Location:
          $ref: '#/components/headers/Location_deprecated'
        Content-Type:
          $ref: '#/components/headers/ContentType_LOCATABLE'
        openehr-item-tag:
          $ref: '#/components/headers/openehr-item-tag'
        openehr-version-item-tag:
          $ref: '#/components/headers/openehr-version-item-tag'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EhrStatus'
    404_unknown_ehr_id_or_version_uid:
      description: |
        `404 Not Found` is returned when an EHR with `ehr_id` does not exist, or when the `version_uid` does not exist.
    404_unknown_ehr_id_or_no_version_at_time:
      description: |
        `404 Not Found` is returned when an EHR with `ehr_id` does not exist, or when a version of the resource identified by the request parameters (at specified `version_at_time`) does not exist.
    200_EHR_STATUS_updated:
      description: |
        `200 OK` is returned when the EHR_STATUS is successfully updated, with the full resource in the response body when `Prefer` header is `return=representation`, or only its identifiers when `Prefer` header is `return=identifier`.
      headers:
        ETag:
          $ref: '#/components/headers/ETag'
        Location:
          $ref: '#/components/headers/Location_EHR_STATUS'
        Content-Type:
          $ref: '#/components/headers/ContentType_LOCATABLE'
        openehr-item-tag:
          $ref: '#/components/headers/openehr-item-tag'
        openehr-version-item-tag:
          $ref: '#/components/headers/openehr-version-item-tag'
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/EhrStatus'
              - $ref: '#/components/schemas/Identifier'
    204_version_updated:
      description: |
        `204 No Content` is returned when the update operation was successful and the `Prefer` header is missing or is set to `return=minimal`.
      headers:
        ETag:
          $ref: '#/components/headers/ETag'
        Location:
          $ref: '#/components/headers/Location_version'
        openehr-item-tag:
          $ref: '#/components/headers/openehr-item-tag'
        openehr-version-item-tag:
          $ref: '#/components/headers/openehr-version-item-tag'
    412_EHR_STATUS:
      description: |
        `412 Precondition Failed` is returned when `If-Match` request header doesn't match the latest version on the service side.
        Returns also latest `version_uid` in the `ETag` header.
      headers:
        ETag:
          $ref: '#/components/headers/ETag'
        Location:
          $ref: '#/components/headers/Location_deprecated'
    200_VERSIONED_EHR_STATUS:
      description: |
        `200 OK` is returned when the requested VERSIONED_EHR_STATUS is successfully retrieved.
      headers:
        Content-Type:
          $ref: '#/components/headers/ContentType_canonical'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/VersionedEhrStatus'
    200_REVISION_HISTORY:
      description: |
        `200 OK` is returned when the requested REVISION_HISTORY is successfully retrieved.
      headers:
        Content-Type:
          $ref: '#/components/headers/ContentType_canonical'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RevisionHistory'
    200_VERSION_of_EHR_STATUS_at_time:
      description: |
        `200 OK` is returned when the requested VERSION is successfully retrieved.
      headers:
        ETag:
          $ref: '#/components/headers/ETag_VERSION'
        Location:
          $ref: '#/components/headers/Location_deprecated'
        Content-Type:
          $ref: '#/components/headers/ContentType_canonical'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/VersionOfEhrStatus'
    200_VERSION_of_EHR_STATUS_by_id:
      description: |
        `200 OK` is returned when the requested VERSION is successfully retrieved.
      headers:
        Content-Type:
          $ref: '#/components/headers/ContentType_canonical'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/VersionOfEhrStatus'
    201_COMPOSITION:
      description: |
        `201 Created` is returned when the COMPOSITION is successfully created. 
        If `Prefer` header is `return=representation`, the full resource is included in the response body; if is `return=identifier`, only its unique identifier is included. 
        If the `Prefer` header is missing or set to `return=minimal`, the body is empty.
      headers:
        ETag:
          $ref: '#/components/headers/ETag_COMPOSITION'
        Location:
          $ref: '#/components/headers/Location_COMPOSITION'
        Content-Type:
          $ref: '#/components/headers/ContentType_LOCATABLE'
        openehr-item-tag:
          $ref: '#/components/headers/openehr-item-tag'
        openehr-version-item-tag:
          $ref: '#/components/headers/openehr-version-item-tag'
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/Composition'
              - $ref: '#/components/schemas/Identifier'
    200_COMPOSITION_retrieved:
      description: |
        `200 OK` is returned when the requested COMPOSITION is successfully retrieved.
      headers:
        ETag:
          $ref: '#/components/headers/ETag_COMPOSITION'
        Location:
          $ref: '#/components/headers/Location_deprecated'
        Content-Type:
          $ref: '#/components/headers/ContentType_LOCATABLE'
        openehr-item-tag:
          $ref: '#/components/headers/openehr-item-tag'
        openehr-version-item-tag:
          $ref: '#/components/headers/openehr-version-item-tag'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Composition'
    204_deleted_at_time:
      description: |
        `204 No Content` is returned when the resource identified by the request parameters (at specified `version_at_time`) time has been deleted.
    200_COMPOSITION_updated:
      description: |
        `200 OK` is returned when the COMPOSITION is successfully updated, with the full resource in the response body when `Prefer` header is `return=representation`, or only its identifiers when `Prefer` header is `return=identifier`.
      headers:
        ETag:
          $ref: '#/components/headers/ETag_COMPOSITION'
        Location:
          $ref: '#/components/headers/Location_COMPOSITION'
        Content-Type:
          $ref: '#/components/headers/ContentType_LOCATABLE'
        openehr-item-tag:
          $ref: '#/components/headers/openehr-item-tag'
        openehr-version-item-tag:
          $ref: '#/components/headers/openehr-version-item-tag'
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/Composition'
              - $ref: '#/components/schemas/Identifier'
    404_unknown_ehr_id_or_uid_based_id:
      description: |
        `404 Not Found` is returned when an EHR with `ehr_id` does not exist, or when the `uid_based_id` does not exist.
    412_COMPOSITION:
      description: |
        `412 Precondition Failed` is returned when `If-Match` request header doesn't match the latest version on the service side.
        Returns also latest `version_uid` in the `ETag` header.
      headers:
        ETag:
          $ref: '#/components/headers/ETag_COMPOSITION'
        Location:
          $ref: '#/components/headers/Location_deprecated'
    204_version_deleted:
      description: |
        `204 No Content` is returned for a successful delete operation.
      headers:
        ETag:
          $ref: '#/components/headers/ETag'
        Location:
          $ref: '#/components/headers/Location_deprecated'
    400_already_deleted:
      description: |
        `400 Bad Request` is returned when the request could not be parsed or is invalid (e.g. malformed request URL syntax, missing required header or parameter, or syntactically invalid header, parameter or content) or when the resource identified by the request parameters is already deleted.
    409_COMPOSITION_with_uid_based_id:
      description: |
        `409 Conflict` is returned when supplied `uid_based_id` doesn't match the latest version.
        Returns also latest `version_uid` in the `ETag` header.
      headers:
        ETag:
          $ref: '#/components/headers/ETag_COMPOSITION'
        Location:
          $ref: '#/components/headers/Location_deprecated'
    200_VERSIONED_COMPOSITION:
      description: |
        `200 OK` is returned when the requested VERSIONED_COMPOSITION is successfully retrieved.
      headers:
        Content-Type:
          $ref: '#/components/headers/ContentType_canonical'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/VersionedComposition'
    404_unknown_ehr_id_or_versioned_object_uid:
      description: |
        `404 Not Found` is returned when an EHR with `ehr_id` does not exist, or when the `versioned_object_uid` does not exist.
    200_VERSION_of_COMPOSITION_at_time:
      description: |
        `200 OK` is returned when the requested VERSION is successfully retrieved.
      headers:
        ETag:
          $ref: '#/components/headers/ETag_VERSION_of_COMPOSITION'
        Location:
          $ref: '#/components/headers/Location_deprecated'
        Content-Type:
          $ref: '#/components/headers/ContentType_canonical'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/VersionOfComposition'
    404_unknown_ehr_id_or_versioned_object_uid_or_no_version_at_time:
      description: |
        `404 Not Found` is returned when an EHR with `ehr_id` does not exist, or when `versioned_object_uid` does not exist, or when a version of the resource does not exist at the specified `version_at_time`.
    200_VERSION_of_COMPOSITION_by_id:
      description: |
        `200 OK` is returned when the requested VERSION is successfully retrieved.
      headers:
        Content-Type:
          $ref: '#/components/headers/ContentType_canonical'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/VersionOfComposition'
    404_unknown_ehr_id_or_versioned_object_uid_or_version_uid:
      description: |
        `404 Not Found` is returned when an EHR with `ehr_id` does not exist, or when `versioned_object_uid` does not exist, or when a VERSION with `version_uid` does not exist.
    200_FOLDER_retrieved:
      description: |
        `200 OK` is returned when the FOLDER is successfully retrieved.
      headers:
        Content-Type:
          $ref: '#/components/headers/ContentType_LOCATABLE'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Folder'
    404_directory_unknown_ehr_id_or_no_version_at_time_or_no_path:
      description: |
        `404 Not Found` is returned when an EHR with `ehr_id` does not exist, or when a directory does not exist at the specified `version_at_time`, or when `path` does not exist within the directory.
    200_directory_updated:
      description: |
        `200 OK` is returned when directory was successfully updated, with the full resource in the response body when `Prefer` header is `return=representation`, or only its identifiers when `Prefer` header is `return=identifier`.
      headers:
        ETag:
          $ref: '#/components/headers/ETag_FOLDER'
        Location:
          $ref: '#/components/headers/Location_directory'
        Content-Type:
          $ref: '#/components/headers/ContentType_LOCATABLE'
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/Folder'
              - $ref: '#/components/schemas/Identifier'
    412_directory:
      description: |
        `412 Precondition Failed` is returned when `If-Match` request header doesn't match the latest version on the service side.
        Returns also latest `version_uid` in the `ETag` header.
      headers:
        ETag:
          $ref: '#/components/headers/ETag_FOLDER'
        Location:
          $ref: '#/components/headers/Location_deprecated'
    201_directory:
      description: |
        `201 Created` is returned when the FOLDER is successfully created. 
        If `Prefer` header is `return=representation`, the full resource is included in the response body; if is `return=identifier`, only its unique identifier is included. 
        If the `Prefer` header is missing or set to `return=minimal`, the body is empty.
      headers:
        ETag:
          $ref: '#/components/headers/ETag_FOLDER'
        Location:
          $ref: '#/components/headers/Location_directory'
        Content-Type:
          $ref: '#/components/headers/ContentType_LOCATABLE'
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/Folder'
              - $ref: '#/components/schemas/Identifier'
    204_deleted:
      description: |
        `204 No Content` is returned when the resource identified by the request parameters has been (logically) deleted.
    404_directory_unknown_ehr_id_or_no_version_uid_or_no_path:
      description: |
        `404 Not Found` is returned when an EHR with `ehr_id` does not exist, or when a directory with `version_uid` does not exist, or when `path` does not exist within the directory.
    201_CONTRIBUTION:
      description: |
        `201 Created` is returned when the CONTRIBUTION is successfully created.
        If `Prefer` header is `return=representation`, the full resource is included in the response body; if is `return=identifier`, only its unique identifier is included.
        If the `Prefer` header is missing or set to `return=minimal`, the body is empty.

        When the request `Accept` header selects a Simplified Formats MIME type (`application/openehr.wt.flat+json` or `application/openehr.wt.structured+json`) and `Prefer: return=representation`, the response body is still a canonical CONTRIBUTION envelope; only each `versions[i].data` payload is serialized in the requested FLAT or STRUCTURED form.
      headers:
        ETag:
          $ref: '#/components/headers/ETag_CONTRIBUTION'
        Location:
          $ref: '#/components/headers/Location_CONTRIBUTION'
        Content-Type:
          $ref: '#/components/headers/ContentType_LOCATABLE'
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/Contribution'
              - $ref: '#/components/schemas/Identifier'
    400_CONTRIBUTION:
      description: |
        `400 Bad Request` is returned when the request could not be parsed or is invalid (e.g. malformed request URL syntax, missing required header or parameter, or syntactically invalid header, parameter or content, or the modification type does not match the operation - i.e. first version of a MODIFICATION).
        The response body MAY contain error details.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    200_CONTRIBUTION:
      description: |
        `200 OK` is returned when the CONTRIBUTION is successfully retrieved.

        When the request `Accept` header selects a Simplified Formats MIME type (`application/openehr.wt.flat+json` or `application/openehr.wt.structured+json`), the response body is still a canonical CONTRIBUTION envelope; only each `versions[i].data` payload is serialized in the requested FLAT or STRUCTURED form.
      headers:
        Content-Type:
          $ref: '#/components/headers/ContentType_LOCATABLE'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Contribution'
    404_CONTRIBUTION:
      description: |
        `404 Not Found` is returned when an EHR with `ehr_id` does not exist, or when a CONTRIBUTION with `contribution_uid` does not exist.
    200_COMPOSITION_ItemTagList_retrieved:
      description: |
        `200 OK` is returned when the requested ITEM_TAG list is successfully retrieved.
      headers:
        Content-Type:
          $ref: '#/components/headers/ContentType_canonical'
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/ItemTagOfComposition'
    200_COMPOSITION_ItemTagList_updated:
      description: |
        `200 OK` is returned when the requested ITEM_TAG list is successfully retrieved.
      headers:
        Content-Type:
          $ref: '#/components/headers/ContentType_canonical'
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/ItemTagOfComposition'
    204_updated:
      description: |
        `204 No Content` is returned when the update operation was successful and the `Prefer` header is missing or is set to `return=minimal`.
    404_unknown_ehr_id_or_uid_based_id_or_key:
      description: |
        `404 Not Found` is returned when an EHR with `ehr_id` does not exist, or when the `uid_based_id` does not exist, or when the ITEM_TAG identified by the `key` does not exist.
    200_EHR_STATUS_ItemTagList_retrieved:
      description: |
        `200 OK` is returned when the requested ITEM_TAG list is successfully retrieved.
      headers:
        Content-Type:
          $ref: '#/components/headers/ContentType_canonical'
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/ItemTagOfEhrStatus'
    200_EHR_STATUS_ItemTagList_updated:
      description: |
        `200 OK` is returned when the requested ITEM_TAG list is successfully retrieved.
      headers:
        Content-Type:
          $ref: '#/components/headers/ContentType_canonical'
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/ItemTagOfEhrStatus'
x-tagGroups:
  - name: Resource endpoints
    tags:
      - EHR
      - EHR_STATUS
      - COMPOSITION
      - DIRECTORY
      - CONTRIBUTION
      - ITEM_TAG
  - name: Related schemas
    tags:
      - CONTENT_ITEM_schema
      - ITEM_schema
      - ITEM_STRUCTURE_schema
