openapi: 3.2.0 info: title: Demographic ROLE API version: development x-status: DEVELOPMENT x-spec: demographic description: Management of the ROLE 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: Role description: Management of the ROLE class. paths: /demographic/role: post: operationId: role_create summary: Create ROLE description: Creates the first version of a new ROLE. tags: - Role parameters: - $ref: '#/components/parameters/Prefer' - $ref: '#/components/parameters/openehr-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::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_ ROLE version. See Resource identification for more details about the identifiers usage and meaning.' tags: - Role parameters: - $ref: '#/components/parameters/uid_based_id' - $ref: '#/components/parameters/version_at_time' - $ref: '#/components/parameters/Prefer' responses: '200': $ref: '#/components/responses/200_ROLE_retrieved' '204': $ref: '#/components/responses/204_deleted_at_time' '404': $ref: '#/components/responses/404_not_found_or_no_version_at_time' put: operationId: role_update summary: Update ROLE description: 'Updates ROLE 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 ROLE.uid.value, it must match the `uid_based_id` in the URL. The existing latest `version_uid` of ROLE resource (i.e. the `preceding_version_uid`) must be specified in the `If-Match` header.' tags: - Role 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 ROLE. ' content: application/json: schema: $ref: '#/components/schemas/Role' required: true responses: '200': $ref: '#/components/responses/200_ROLE_updated' '204': $ref: '#/components/responses/204_version_updated' '400': $ref: '#/components/responses/400' '404': $ref: '#/components/responses/404' '412': $ref: '#/components/responses/412_ROLE' '422': $ref: '#/components/responses/422' delete: operationId: role_delete summary: Delete ROLE description: 'Deletes the ROLE 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: - Role 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_ROLE_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). ' ListOfCapability: title: ListOfCapability type: array items: $ref: '#/components/schemas/Capability' 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 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: '' Role: title: ROLE required: - name - archetype_node_id - identities - performer type: object properties: _type: enum: - ROLE 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' time_validity: $ref: '#/components/schemas/DvIntervalOfDate' performer: $ref: '#/components/schemas/PartyRef' capabilities: $ref: '#/components/schemas/ListOfCapability' Capability: title: CAPABILITY required: - name - archetype_node_id - credentials type: object properties: _type: enum: - CAPABILITY 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' credentials: $ref: '#/components/schemas/UItemStructure' time_validity: $ref: '#/components/schemas/DvIntervalOfDate' 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' 200_ROLE_updated: description: '`200 OK` is returned when the ROLE 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_ROLE' openehr-item-tag: $ref: '#/components/headers/openehr-item-tag' content: application/json: schema: oneOf: - $ref: '#/components/schemas/Role' - $ref: '#/components/schemas/Identifier' 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. ' 200_ROLE_retrieved: description: '`200 OK` is returned when the requested ROLE 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/Role' 412_ROLE: 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' 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' 409_ROLE_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' '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. ' '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. ' 201_ROLE: description: "`201 Created` is returned when the ROLE 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_ROLE' openehr-item-tag: $ref: '#/components/headers/openehr-item-tag' content: application/json: schema: oneOf: - $ref: '#/components/schemas/Role' - $ref: '#/components/schemas/Identifier' 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_ROLE: description: 'The `Location` response header indicates the URL of the ROLE resource. ' schema: type: string format: url x-ext-urls: {}