Cadasto PERSON API

openapi: 3.2.0
info:
  title: Demographic PERSON API
  version: development
  x-status: DEVELOPMENT
  x-spec: demographic
  description: Management of the PERSON class.
servers:
- url: https://{baseUrl}/v1
  description: An example openEHR server URL.
  variables:
    baseUrl:
      default: cataniamc.prod.cadasto.com
      description: The (example) server base URL prefix providing openEHR services. This may contain server name, port and base path prefix.
security: []
tags:
- name: Person
  description: Management of the PERSON class.
paths:
  /demographic/person:
    post:
      operationId: person_create
      summary: Create PERSON
      description: Creates the first version of a new PERSON.
      tags:
      - Person
      parameters:
      - $ref: '#/components/parameters/Prefer'
      - $ref: '#/components/parameters/openehr-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::cataniamc.prod.cadasto.com::1`), whereas the later (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 for more details about the identifiers usage and meaning.'
      tags:
      - Person
      parameters:
      - $ref: '#/components/parameters/uid_based_id'
      - $ref: '#/components/parameters/version_at_time'
      - $ref: '#/components/parameters/Prefer'
      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.'
      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/openehr-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'
components:
  schemas:
    PartyIdentity:
      title: PARTY_IDENTITY
      required:
      - name
      - archetype_node_id
      - details
      type: object
      properties:
        _type:
          type: string
        name:
          $ref: '#/components/schemas/UDvText'
        archetype_node_id:
          type: string
          xml:
            attribute: true
        uid:
          $ref: '#/components/schemas/UUidBasedId'
        links:
          type: array
          items:
            $ref: '#/components/schemas/Link'
        archetype_details:
          $ref: '#/components/schemas/Archetyped'
        feeder_audit:
          $ref: '#/components/schemas/FeederAudit'
        details:
          $ref: '#/components/schemas/UItemStructure'
    ListOfContact:
      title: ListOfContact
      type: array
      items:
        $ref: '#/components/schemas/Contact'
    ArchetypeId:
      title: ARCHETYPE_ID
      type: object
      properties:
        _type:
          enum:
          - ARCHETYPE_ID
          type: string
        value:
          type: string
      required:
      - value
    ReferenceRange:
      title: REFERENCE_RANGE
      required:
      - meaning
      - range
      type: object
      properties:
        meaning:
          $ref: '#/components/schemas/UDvText'
        range:
          $ref: '#/components/schemas/DvInterval'
    ListOfPartyIdentity:
      title: ListOfPartyIdentity
      type: array
      items:
        $ref: '#/components/schemas/PartyIdentity'
    DvIdentifier:
      title: DV_IDENTIFIER
      required:
      - id
      type: object
      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.

        '
    TerminologyId:
      title: TERMINOLOGY_ID
      type: object
      properties:
        _type:
          enum:
          - TERMINOLOGY_ID
          type: string
        value:
          type: string
      required:
      - value
    UPartyIdentified:
      title: PARTY_IDENTIFIED
      type: object
      description: 'Polymorphic PARTY_IDENTIFIED wrapper. See concrete leaf schemas:

        - `UMPartyIdentified`

        - `UMPartyRelated`

        '
    ListOfPartyRelationship:
      title: ListOfPartyRelationShip
      type: array
      items:
        $ref: '#/components/schemas/PartyRelationship'
    Link:
      title: LINK
      required:
      - meaning
      - type
      - target
      type: object
      properties:
        meaning:
          type: string
        type:
          type: string
        target:
          $ref: '#/components/schemas/DvEhrUri'
    UMObjectVersionId:
      title: OBJECT_VERSION_ID
      required:
      - value
      - _type
      type: object
      properties:
        _type:
          enum:
          - OBJECT_VERSION_ID
          type: string
        value:
          type: string
    UDvText:
      title: DV_TEXT
      type: object
      description: 'Polymorphic DV_TEXT wrapper. See concrete leaf schemas:

        - `UMDvText`

        - `UMDvCodedText`

        '
    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
    FeederAuditDetails:
      title: FEEDER_AUDIT_DETAILS
      required:
      - system_id
      type: object
      properties:
        system_id:
          type: string
        location:
          $ref: '#/components/schemas/UPartyIdentified'
        subject:
          $ref: '#/components/schemas/UPartyProxy'
        provider:
          $ref: '#/components/schemas/UPartyIdentified'
        time:
          $ref: '#/components/schemas/DvDateTime'
        version_id:
          type: string
        other_details:
          type: object
          description: 'Any other details of the system audit.  (Structure simplified for documentation performance).

            '
    UPartyProxy:
      title: PARTY_PROXY
      type: object
      description: 'Polymorphic PARTY_PROXY wrapper. See concrete leaf schemas:

        - `UMPartySelf`

        - `UMPartyIdentified`

        - `UMPartyRelated`

        '
    UDvEncapsulated:
      title: DV_ENCAPSULATED
      type: object
      description: 'Polymorphic DV_ENCAPSULATED wrapper. See concrete leaf schemas:

        - `UMDvMultimedia`

        - `UMDvParsable`

        '
    UUidBasedId:
      title: UID_BASED_ID
      type: object
      oneOf:
      - $ref: '#/components/schemas/UMHierObjectId'
      - $ref: '#/components/schemas/UMObjectVersionId'
      discriminator:
        propertyName: _type
        mapping:
          HIER_OBJECT_ID: '#/components/schemas/UMHierObjectId'
          OBJECT_VERSION_ID: '#/components/schemas/UMObjectVersionId'
    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
      additionalProperties: false
    DvDuration:
      title: DV_DURATION
      type: object
      properties:
        _type:
          enum:
          - DV_DURATION
          type: string
        normal_status:
          $ref: '#/components/schemas/CodePhrase'
        normal_range:
          $ref: '#/components/schemas/DvInterval'
        other_reference_ranges:
          type: array
          items:
            $ref: '#/components/schemas/ReferenceRange'
        magnitude_status:
          type: string
          default: '='
        accuracy_is_percent:
          type: boolean
        accuracy:
          type: number
    UMDvDate:
      title: DV_DATE
      required:
      - value
      - _type
      type: object
      properties:
        _type:
          enum:
          - DV_DATE
          type: string
        normal_status:
          $ref: '#/components/schemas/CodePhrase'
        normal_range:
          $ref: '#/components/schemas/DvInterval'
        other_reference_ranges:
          type: array
          items:
            $ref: '#/components/schemas/ReferenceRange'
        magnitude_status:
          type: string
          default: '='
        accuracy:
          $ref: '#/components/schemas/DvDuration'
        value:
          type: string
          format: date
    UItemStructure:
      title: ITEM_STRUCTURE
      type: object
      description: 'Polymorphic ITEM_STRUCTURE wrapper. See concrete leaf schemas:

        - `ItemSingle`

        - `ItemList`

        - `ItemTable`

        - `ItemTree`

        '
    Address:
      title: ADDRESS
      required:
      - name
      - archetype_node_id
      - details
      type: object
      properties:
        _type:
          type: string
        name:
          $ref: '#/components/schemas/UDvText'
        archetype_node_id:
          type: string
          xml:
            attribute: true
        uid:
          $ref: '#/components/schemas/UUidBasedId'
        links:
          type: array
          items:
            $ref: '#/components/schemas/Link'
        archetype_details:
          $ref: '#/components/schemas/Archetyped'
        feeder_audit:
          $ref: '#/components/schemas/FeederAudit'
        details:
          $ref: '#/components/schemas/UItemStructure'
    Contact:
      title: CONTACT
      required:
      - name
      - archetype_node_id
      - addresses
      type: object
      properties:
        _type:
          enum:
          - CONTACT
          type: string
        name:
          $ref: '#/components/schemas/UDvText'
        archetype_node_id:
          type: string
          xml:
            attribute: true
        uid:
          $ref: '#/components/schemas/UUidBasedId'
        links:
          type: array
          items:
            $ref: '#/components/schemas/Link'
        archetype_details:
          $ref: '#/components/schemas/Archetyped'
        feeder_audit:
          $ref: '#/components/schemas/FeederAudit'
        addresses:
          type: array
          items:
            $ref: '#/components/schemas/Address'
        time_validity:
          $ref: '#/components/schemas/DvIntervalOfDate'
    PartyRef:
      title: PARTY_REF
      type: object
      properties:
        namespace:
          type: string
        type:
          pattern: ^PERSON|ORGANISATION|GROUP|AGENT|ROLE|PARTY|ACTOR$
          type: string
        id:
          $ref: '#/components/schemas/UMHierObjectId'
      description: Identifier for parties in a demographic or identity service.
      required:
      - namespace
      - type
      - id
    DvEhrUri:
      title: DV_EHR_URI
      type: object
      properties:
        _type:
          enum:
          - DV_EHR_URI
          type: string
        value:
          type: string
      required:
      - value
    Person:
      title: PERSON
      type: object
      properties:
        _type:
          enum:
          - PERSON
          type: string
        name:
          $ref: '#/components/schemas/UDvText'
        archetype_node_id:
          type: string
          xml:
            attribute: true
        uid:
          $ref: '#/components/schemas/UUidBasedId'
        links:
          type: array
          items:
            $ref: '#/components/schemas/Link'
        archetype_details:
          $ref: '#/components/schemas/Archetyped'
        feeder_audit:
          $ref: '#/components/schemas/FeederAudit'
        identities:
          $ref: '#/components/schemas/ListOfPartyIdentity'
        contacts:
          $ref: '#/components/schemas/ListOfContact'
        details:
          $ref: '#/components/schemas/UItemStructure'
        relationships:
          $ref: '#/components/schemas/ListOfPartyRelationship'
        languages:
          type: array
          items:
            $ref: '#/components/schemas/UDvText'
        roles:
          type: array
          items:
            $ref: '#/components/schemas/PartyRef'
      required:
      - name
      - archetype_node_id
      - identities
    UMHierObjectId:
      title: HIER_OBJECT_ID
      required:
      - value
      - _type
      type: object
      properties:
        _type:
          enum:
          - HIER_OBJECT_ID
          type: string
        value:
          type: string
          format: uuid
    PartyRelationship:
      title: PARTY_RELATIONSHIP
      required:
      - name
      - archetype_node_id
      - source
      - target
      type: object
      properties:
        _type:
          type: string
        name:
          $ref: '#/components/schemas/UDvText'
        archetype_node_id:
          type: string
          xml:
            attribute: true
        uid:
          $ref: '#/components/schemas/UUidBasedId'
        links:
          type: array
          items:
            $ref: '#/components/schemas/Link'
        archetype_details:
          $ref: '#/components/schemas/Archetyped'
        feeder_audit:
          $ref: '#/components/schemas/FeederAudit'
        source:
          $ref: '#/components/schemas/PartyRef'
        target:
          $ref: '#/components/schemas/PartyRef'
        details:
          $ref: '#/components/schemas/UItemStructure'
        time_validity:
          $ref: '#/components/schemas/DvIntervalOfDate'
    DvIntervalOfDate:
      title: DV_INTERVAL_of_DATE
      type: object
      properties:
        _type:
          type: string
          default: DV_INTERVAL
        lower_unbounded:
          type: boolean
        upper_unbounded:
          type: boolean
        lower_included:
          type: boolean
        upper_included:
          type: boolean
        lower:
          $ref: '#/components/schemas/UMDvDate'
        upper:
          $ref: '#/components/schemas/UMDvDate'
      required:
      - lower_unbounded
      - upper_unbounded
      - lower_included
      - upper_included
    Error:
      title: Error
      required:
      - message
      - validationErrors
      type: object
      properties:
        message:
          type: string
        validationErrors:
          type: array
          items:
            type: string
          description: ''
    TemplateId:
      title: TEMPLATE_ID
      type: object
      properties:
        _type:
          enum:
          - TEMPLATE_ID
          type: string
        value:
          type: string
      required:
      - value
    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/UDvEncapsulated'
        originating_system_audit:
          $ref: '#/components/schemas/FeederAuditDetails'
        feeder_system_audit:
          $ref: '#/components/schemas/FeederAuditDetails'
    DvDateTime:
      title: DV_DATE_TIME
      required:
      - value
      type: object
      properties:
        _type:
          enum:
          - DV_DATE_TIME
          type: string
        normal_status:
          $ref: '#/components/schemas/CodePhrase'
        normal_range:
          $ref: '#/components/schemas/DvInterval'
        other_reference_ranges:
          type: array
          items:
            $ref: '#/components/schemas/ReferenceRange'
        magnitude_status:
          type: string
          default: '='
        accuracy:
          $ref: '#/components/schemas/DvDuration'
        value:
          type: string
          format: date-time
    Identifier:
      title: Identifier
      required:
      - uid
      type: object
      properties:
        uid:
          type: string
          description: The (version) resource identifier.
    DvInterval:
      title: DV_INTERVAL
      required:
      - lower_unbounded
      - upper_unbounded
      - lower_included
      - upper_included
      type: object
      properties:
        _type:
          type: string
          default: DV_INTERVAL
        lower_unbounded:
          type: boolean
        upper_unbounded:
          type: boolean
        lower_included:
          type: boolean
        upper_included:
          type: boolean
    UpdateItemTag:
      title: UPDATE_ITEM_TAG
      required:
      - key
      type: object
      additionalProperties: false
      properties:
        key:
          type: string
          description: Tag key (identifier). Stored case-insensitively.
        value:
          type: string
          description: Optional tag value.
        target_path:
          type: string
          maxLength: 500
          description: Optional pointer into the target resource (AQL path). Maximum length 500 characters.
  parameters:
    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
    Prefer:
      name: Prefer
      in: header
      description: 'RFC 7240 preference header. Multiple tokens may be sent in a single header as a

        comma-separated list (e.g. `Prefer: return=representation, include_item_tags`)

        or as repeated headers. Cadasto recognises the following tokens:


        | Token | Where it applies | Effect |

        |-------|------------------|--------|

        | `return=representation` | write endpoints | Return the full updated resource in the response body. |

        | `return=identifier` | write endpoints | Return only the resource identifier (e.g. the `uid`). |

        | `return=minimal` (default on writes) | write endpoints | Empty response body. |

        | `include_item_tags` *(Cadasto extension)* | read endpoints, and write endpoints when the request does not already carry an `openehr-item-tag` header | Emit the `openehr-item-tag` response header with the current tags. On writes that ship `openehr-item-tag` in the request, the token is implied — the response always echoes the tags. Omitted by default on reads. See the [ITEM_TAG guide](/docs/guides/item-tag) for details. |


        The `Preference-Applied` response header echoes the tokens the server actually honoured (`return=`, plus `include_item_tags` / `resolve_refs` when applied).

        '
      required: false
      style: simple
      schema:
        type: string
    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
    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
    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
    openehr-item-tag:
      name: openehr-item-tag
      in: header
      description: 'The list of ITEM_TAG resources to associate with the current versioned object,

        committed in the same transaction as the create/update.


        Two interchangeable formats are accepted:

        - **JSON (recommended)** — same shape as the `/tags` endpoint body

        - **Spec semicolon format** — `key="...",value="..."; key="...",value="...",target_path="..."`


        > **Cadasto exception:** the `openehr-version-item-tag` request header — used by

        > upstream openEHR to scope tags to a single VERSION — is **not supported** by

        > Cadasto and will be rejected with `400 Bad Request`. Tags are always scoped to

        > the versioned object. See the

        > [ITEM_TAG guide](/docs/guides/item-tag) for details and error formats.

        '
      required: false
      style: simple
      explode: true
      schema:
        type: array
        items:
          $ref: '#/components/schemas/UpdateItemTag'
    If-Match:
      name: If-Match
      in: header
      description: "Header to make the request conditional. \nTogether with `ETag` request tag, it helps to prevent simultaneous updates of a resource from overwriting each other (\"mid-air collisions\").\nThe format is always an `version_uid` identifier enclosed by double quotes.\nThe 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.\n"
      required: true
      style: simple
      schema:
        type: string
  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). \nThe response body MAY contain error details.\n"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    404_not_found_or_no_version_at_time:
      description: '`404 Not Found` is returned when either the URL configured doesn''t exist at all, or the targeted resource doesn''t exist, or when a VERSION of the resource does not exist at the specified `version_at_time`.

        '
    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.

        '
    412_PERSON:
      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'
    201_PERSON:
      description: "`201 Created` is returned when the PERSON is successfully created. \nIf `Prefer` header is `return=representation`, the full resource is included in the response body; if is `return=identifier`, only its unique identifier is included. \nIf the `Prefer` header is missing or set to `return=minimal`, the body is empty.\n"
      headers:
        ETag:
          $ref: '#/components/headers/ETag'
        Location:
          $ref: '#/components/headers/Location_PERSON'
        openehr-item-tag:
          $ref: '#/components/headers/openehr-item-tag'
      content:
        application/json:
          schema:
            oneOf:
            - $ref: '#/components/schemas/Person'
            - $ref: '#/components/schemas/Identifier'
    200_PERSON_updated:
      description: '`200 OK` is returned when the PERSON 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_PERSON'
        openehr-item-tag:
          $ref: '#/components/headers/openehr-item-tag'
      content:
        application/json:
          schema:
            oneOf:
            - $ref: '#/components/schemas/Person'
            - $ref: '#/components/schemas/Identifier'
    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.

        '
    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'
    '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.

        '
    '404':
      description: '`404 Not Found` is returned when, based on the request parameters, the server did not find a current representation of a target resource, or is not willing to disclose that one exists.

        '
    409_PERSON_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'
        Location:
          $ref: '#/components/headers/Location_deprecated'
    200_PERSON_retrieved:
      description: '`200 OK` is returned when the requested PERSON is successfully retrieved.

        '
      headers:
        ETag:
          $ref: '#/components/headers/ETag'
        Location:
          $ref: '#/components/headers/Location_deprecated'
        openehr-item-tag:
          $ref: '#/components/headers/openehr-item-tag'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Person'
    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'
  headers:
    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
    Location_deprecated:
      description: 'The `Location` is [deprecated](overview.html#tag/Requests_and_responses/HTTP-headers/Location) for this action.

        '
      deprecated: true
      schema:
        type: string
    Location_version:
      description: 'The `Location` response header indicates the URL of the resource version resulted from the operation.

        '
      schema:
        type: string
        format: url
    openehr-item-tag:
      description: "The list of ITEM_TAG resources associated with the current versioned object,\nemitted as a JSON array.\n\n**When this header is emitted:**\n- On write endpoints (`POST` create, `PUT` update) — automatically, when the\n  request carried an `openehr-item-tag` header (tag-aware request → tag-aware\n  response) and the response uses `return=representation`. To force inclusion\n  on a write that did not send tags, add `Prefer: include_item_tags`.\n- On read endpoints (`GET`) — only when the client opts in by sending\n  `Prefer: include_item_tags`. Without the opt-in the additional tag lookup is\n  skipped and the header is omitted entirely.\n\nThe header is also omitted when the resource has no tags.\n\n> **Cadasto exception:** the `openehr-version-item-tag` response header — used by\n> upstream openEHR to convey VERSION-scoped tags — is **never emitted** by Cadasto.\n> All tags are scoped to the versioned object as a whole.\n"
      schema:
        type: string
    Location_PERSON:
      description: 'The `Location` response header indicates the URL of the PERSON resource.

        '
      schema:
        type: string
        format: url
x-ext-urls: {}