openEHR Demographic API

openapi: 3.0.3
info:
  title: Demographic API
  version: development
  x-status: DEVELOPMENT
  x-spec: demographic
  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 Demographic API in a RESTful manner.

    ### Related Documents

    Prerequisite documents for reading this document include:

    - The [Demographic Information Model](https://specifications.openehr.org/releases/RM/latest/demographic.html#_demographic_package)

    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 `DEVELOPMENT` state, and can be downloaded as [OpenAPI specification](https://spec.openapis.org/oas/v3.0.3) file (in YAML format) [for validation](computable/OAS/demographic-validation.openapi.yaml), or [for code generators](computable/OAS/demographic-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/demographic.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: AGENT
    description: |
      Management of the [AGENT](https://specifications.openehr.org/releases/RM/latest/demographic.html#_agent_class) class.
  - name: GROUP
    description: |
      Management of the [GROUP](https://specifications.openehr.org/releases/RM/latest/demographic.html#_group_class) class.
  - name: ORGANISATION
    description: |
      Management of the [ORGANISATION](https://specifications.openehr.org/releases/RM/latest/demographic.html#_organisation_class) class.
  - name: PERSON
    description: |
      Management of the [PERSON](https://specifications.openehr.org/releases/RM/latest/demographic.html#_person_class) class.
  - name: ROLE
    description: |
      Management of the [ROLE](https://specifications.openehr.org/releases/RM/latest/demographic.html#_role_class) class.
  - name: VERSIONED_PARTY
    description: |
      Management of the [VERSIONED_PARTY](https://specifications.openehr.org/releases/RM/latest/demographic.html#_versioned_party_class) class.
  - name: CONTRIBUTION
    description: |
      Management of [CONTRIBUTION](https://specifications.openehr.org/releases/RM/latest/common.html#_contribution_class) class.
  - name: ITEM_TAG
    description: |
      Management of [ITEM_TAG](https://specifications.openehr.org/releases/RM/development/common.html#_item_tag_class) resources.
  - name: CAPABILITY_schema
    x-displayName: CAPABILITY
    description: |
      The `CAPABILITY` schema, formally specified in the Reference Model as the [CAPABILITY](https://specifications.openehr.org/releases/RM/latest/demographic.html#_capability_class) class:
      <SchemaDefinition schemaRef="#/components/schemas/Capability" />
  - name: CONTACT_schema
    x-displayName: CONTACT
    description: |
      The `CONTACT` schema, formally specified in the Reference Model as the [CONTACT](https://specifications.openehr.org/releases/RM/latest/demographic.html#_contact_class) class:
      <SchemaDefinition schemaRef="#/components/schemas/Contact" />
  - name: PARTY_IDENTITY_schema
    x-displayName: PARTY_IDENTITY
    description: |
      The `PARTY_IDENTITY` schema, formally specified in the Reference Model as the [PARTY_IDENTITY](https://specifications.openehr.org/releases/RM/latest/demographic.html#_party_identity_class) class:
      <SchemaDefinition schemaRef="#/components/schemas/PartyIdentity" />
  - name: PARTY_RELATIONSHIP_schema
    x-displayName: PARTY_RELATIONSHIP
    description: |
      The `PARTY_RELATIONSHIP` resource, formally specified in the Reference Model as the [PARTY_RELATIONSHIP](https://specifications.openehr.org/releases/RM/latest/demographic.html#_party_relationship_class) class:
      <SchemaDefinition schemaRef="#/components/schemas/PartyRelationship" />
  - name: ITEM_schema
    x-displayName: ITEM
    description: |
      The abstract `ITEM` class:
      <SchemaDefinition schemaRef="#/components/schemas/UItem" />
  - name: ITEM_STRUCTURE_schema
    x-displayName: ITEM_STRUCTURE
    description: |
      The abstract `ITEM_STRUCTURE` class:
      <SchemaDefinition schemaRef="#/components/schemas/UItemStructure" />
paths:
  /demographic/agent:
    post:
      operationId: agent_create
      summary: Create AGENT
      description: |
        Creates the first version of a new AGENT.

        A list of ITEM_TAGs can be associated with the AGENT, 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:
        - AGENT
      parameters:
        - $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 AGENT.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Agent'
        required: true
      responses:
        '201':
          $ref: '#/components/responses/201_AGENT'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
        '422':
          $ref: '#/components/responses/422'
  /demographic/agent/{uid_based_id}:
    get:
      operationId: agent_get
      summary: Get AGENT
      description: |
        Retrieves a version of the AGENT identified by `uid_based_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 AGENT (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_ AGENT 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 AGENT, 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:
        - AGENT
      parameters:
        - $ref: '#/components/parameters/uid_based_id'
        - $ref: '#/components/parameters/version_at_time'
        - $ref: '#/components/parameters/Accept_LOCATABLE'
      responses:
        '200':
          $ref: '#/components/responses/200_AGENT_retrieved'
        '204':
          $ref: '#/components/responses/204_deleted_at_time'
        '404':
          $ref: '#/components/responses/404_not_found_or_no_version_at_time'
    put:
      operationId: agent_update
      summary: Update AGENT
      description: |
        Updates AGENT identified by `uid_based_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 AGENT.uid.value, it must match the `uid_based_id` in the URL. 

        The existing latest `version_uid` of AGENT 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 AGENT, 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:
        - AGENT
      parameters:
        - $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-version-item-tag'
      requestBody:
        description: |
          The new AGENT.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Agent'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/200_AGENT_updated'
        '204':
          $ref: '#/components/responses/204_version_updated'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
        '412':
          $ref: '#/components/responses/412_AGENT'
        '422':
          $ref: '#/components/responses/422'
    delete:
      operationId: agent_delete
      summary: Delete AGENT
      description: |
        Deletes the AGENT identified by `uid_based_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:
        - AGENT
      parameters:
        - $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'
        '409':
          $ref: '#/components/responses/409_AGENT_with_uid_based_id'
  /demographic/group:
    post:
      operationId: group_create
      summary: Create GROUP
      description: |
        Creates the first version of a new GROUP.

        A list of ITEM_TAGs can be associated with the GROUP, 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:
        - GROUP
      parameters:
        - $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 GROUP.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Group'
        required: true
      responses:
        '201':
          $ref: '#/components/responses/201_GROUP'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
        '422':
          $ref: '#/components/responses/422'
  /demographic/group/{uid_based_id}:
    get:
      operationId: group_get
      summary: Get GROUP
      description: |
        Retrieves a version of the GROUP identified by `uid_based_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 GROUP (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_ GROUP 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 GROUP, 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:
        - GROUP
      parameters:
        - $ref: '#/components/parameters/uid_based_id'
        - $ref: '#/components/parameters/version_at_time'
        - $ref: '#/components/parameters/Accept_LOCATABLE'
      responses:
        '200':
          $ref: '#/components/responses/200_GROUP_retrieved'
        '204':
          $ref: '#/components/responses/204_deleted_at_time'
        '404':
          $ref: '#/components/responses/404_not_found_or_no_version_at_time'
    put:
      operationId: group_update
      summary: Update GROUP
      description: |
        Updates GROUP identified by `uid_based_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 GROUP.uid.value, it must match the `uid_based_id` in the URL. 

        The existing latest `version_uid` of GROUP 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 GROUP, 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:
        - GROUP
      parameters:
        - $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-version-item-tag'
      requestBody:
        description: |
          The new GROUP.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Group'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/200_GROUP_updated'
        '204':
          $ref: '#/components/responses/204_version_updated'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
        '412':
          $ref: '#/components/responses/412_GROUP'
        '422':
          $ref: '#/components/responses/422'
    delete:
      operationId: group_delete
      summary: Delete GROUP
      description: |
        Deletes the GROUP identified by `uid_based_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:
        - GROUP
      parameters:
        - $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'
        '409':
          $ref: '#/components/responses/409_GROUP_with_uid_based_id'
  /demographic/organisation:
    post:
      operationId: organisation_create
      summary: Create ORGANISATION
      description: |
        Creates the first version of a new ORGANISATION.

        A list of ITEM_TAGs can be associated with the ORGANISATION, 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:
        - ORGANISATION
      parameters:
        - $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 ORGANISATION.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Organisation'
        required: true
      responses:
        '201':
          $ref: '#/components/responses/201_ORGANISATION'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
        '422':
          $ref: '#/components/responses/422'
  /demographic/organisation/{uid_based_id}:
    get:
      operationId: organisation_get
      summary: Get ORGANISATION
      description: |
        Retrieves a version of the ORGANISATION identified by `uid_based_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 ORGANISATION (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_ ORGANISATION 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 ORGANISATION, 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:
        - ORGANISATION
      parameters:
        - $ref: '#/components/parameters/uid_based_id'
        - $ref: '#/components/parameters/version_at_time'
        - $ref: '#/components/parameters/Accept_LOCATABLE'
      responses:
        '200':
          $ref: '#/components/responses/200_ORGANISATION_retrieved'
        '204':
          $ref: '#/components/responses/204_deleted_at_time'
        '404':
          $ref: '#/components/responses/404_not_found_or_no_version_at_time'
    put:
      operationId: organisation_update
      summary: Update ORGANISATION
      description: |
        Updates ORGANISATION identified by `uid_based_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 ORGANISATION.uid.value, it must match the `uid_based_id` in the URL. 

        The existing latest `version_uid` of ORGANISATION 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 ORGANISATION, 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:
        - ORGANISATION
      parameters:
        - $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-version-item-tag'
      requestBody:
        description: |
          The new ORGANISATION.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Organisation'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/200_ORGANISATION_updated'
        '204':
          $ref: '#/components/responses/204_version_updated'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
        '412':
          $ref: '#/components/responses/412_ORGANISATION'
        '422':
          $ref: '#/components/responses/422'
    delete:
      operationId: organisation_delete
      summary: Delete ORGANISATION
      description: |
        Deletes the ORGANISATION identified by `uid_based_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:
        - ORGANISATION
      parameters:
        - $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'
        '409':
          $ref: '#/components/responses/409_ORGANISATION_with_uid_based_id'
  /demographic/person:
    post:
      operationId: person_create
      summary: Create PERSON
      description: |
        Creates the first version of a new PERSON.

        A list of ITEM_TAGs can be associated with the PERSON, 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:
        - PERSON
      parameters:
        - $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 PERSON.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Person'
        required: true
      responses:
        '201':
          $ref: '#/components/responses/201_PERSON'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
        '422':
          $ref: '#/components/responses/422'
  /demographic/person/{uid_based_id}:
    get:
      operationId: person_get
      summary: Get PERSON
      description: |
        Retrieves a version of the PERSON identified by `uid_based_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 PERSON (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_ PERSON 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 PERSON, 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:
        - PERSON
      parameters:
        - $ref: '#/components/parameters/uid_based_id'
        - $ref: '#/components/parameters/version_at_time'
        - $ref: '#/components/parameters/Accept_LOCATABLE'
      responses:
        '200':
          $ref: '#/components/responses/200_PERSON_retrieved'
        '204':
          $ref: '#/components/responses/204_deleted_at_time'
        '404':
          $ref: '#/components/responses/404_not_found_or_no_version_at_time'
    put:
      operationId: person_update
      summary: Update PERSON
      description: |
        Updates PERSON identified by `uid_based_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 PERSON.uid.value, it must match the `uid_based_id` in the URL. 

        The existing latest `version_uid` of PERSON 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 PERSON, 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:
        - PERSON
      parameters:
        - $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-version-item-tag'
      requestBody:
        description: |
          The new PERSON.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Person'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/200_PERSON_updated'
        '204':
          $ref: '#/components/responses/204_version_updated'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
        '412':
          $ref: '#/components/responses/412_PERSON'
        '422':
          $ref: '#/components/responses/422'
    delete:
      operationId: person_delete
      summary: Delete PERSON
      description: |
        Deletes the PERSON identified by `uid_based_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:
        - PERSON
      parameters:
        - $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'
        '409':
          $ref: '#/components/responses/409_PERSON_with_uid_based_id'
  /demographic/role:
    post:
      operationId: role_create
      summary: Create ROLE
      description: |
        Creates the first version of a new ROLE.

        A list of ITEM_TAGs can be associated with the ROLE, 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:
        - ROLE
      parameters:
        - $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 ROLE.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Role'
        required: true
      responses:
        '201':
          $ref: '#/components/responses/201_ROLE'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
        '422':
          $ref: '#/components/responses/422'
  /demographic/role/{uid_based_id}:
    get:
      operationId: role_get
      summary: Get ROLE
      description: |
        Retrieves a version of the ROLE identified by `uid_based_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 ROLE (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_ ROLE version.

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

        Wh

# --- truncated at 32 KB (172 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/openehr/refs/heads/main/openapi/openehr-demographic-openapi.yml