adding AGENT resource (#99 SPECITS-70)

specifications/demographic.openapi.yaml

@@ -22,6 +22,28 @@ servers:
         description: The (example) server base URL prefix providing openEHR services. This may contain server name, port and base path prefix.
 security: []
 paths:
+  '/demographic/agent':
+    post:
+      $ref: ./operations/agent_create.yaml
+  '/demographic/agent/{uid_based_id}':
+    get:
+      $ref: ./operations/agent_get.yaml
+    put:
+      $ref: ./operations/agent_update.yaml
+    delete:
+      $ref: ./operations/agent_delete.yaml
+  '/demographic/versioned_agent/{versioned_object_uid}':
+    get:
+      $ref: ./operations/versioned_agent_get.yaml
+  '/demographic/versioned_agent/{versioned_object_uid}/revision_history':
+    get:
+      $ref: ./operations/versioned_agent_revision_history.yaml
+  '/demographic/versioned_agent/{versioned_object_uid}/version':
+    get:
+      $ref: ./operations/versioned_agent_version_get_at_time.yaml
+  '/demographic/versioned_agent/{versioned_object_uid}/version/{version_uid}':
+    get:
+      $ref: ./operations/versioned_agent_version_get_by_id.yaml
   '/demographic/person':
     post:
       $ref: ./operations/person_create.yaml
@@ -51,6 +73,9 @@ paths:
     get:
       $ref: ./operations/contribution_get.yaml
 tags:
+  - name: AGENT
+    description: |
+      Management of the [AGENT](https://specifications.openehr.org/releases/RM/latest/demographic.html#_agent_class) and the associated [VERSIONED_AGENT](https://specifications.openehr.org/releases/RM/latest/demographic.html#_versioned_party_class) resource.
   - name: PERSON
     description: |
       Management of the [PERSON](https://specifications.openehr.org/releases/RM/latest/demographic.html#_person_class) and the associated [VERSIONED_PERSON](https://specifications.openehr.org/releases/RM/latest/demographic.html#_versioned_party_class) resource.

specifications/headers/Location_AGENT.yaml

@@ -0,0 +1,6 @@
+description: |
+  The `Location` response header indicates the URL of the AGENT resource.
+schema:
+  type: string
+  format: url
+  example: 'https://openEHRSys.example.com/v1/demographic/agent/6cb19121-4307-4648-9da0-d62e4d51f19b::openEHRSys.example.com::2'

specifications/headers/Location_VERSIONED_AGENT_VERSION.yaml

@@ -0,0 +1,6 @@
+description: |
+  The `Location` response header indicates the URL of the VERSION resource.
+schema:
+  type: string
+  format: url
+  example: 'https://openEHRSys.example.com/v1/demographic/versioned_agent/6cb19121-4307-4648-9da0-d62e4d51f19b/version/6cb19121-4307-4648-9da0-d62e4d51f19b::openEHRSys.example.com::1'

specifications/operations/agent_create.yaml

@@ -0,0 +1,25 @@
+operationId: agent_create
+summary: Create AGENT
+description: |
+  Creates the first version of a new AGENT.
+tags:
+  - AGENT
+parameters:
+  - $ref: ../parameters/header/Prefer.yaml
+requestBody:
+  description: |
+    The AGENT.
+  content:
+    application/json:
+      schema:
+        $ref: ../schemas/demographic/Agent.yaml
+  required: true
+responses:
+  '201':
+    $ref: ../responses/201_AGENT.yaml
+  '400':
+    $ref: ../responses/400.yaml
+  '422':
+    $ref: ../responses/422.yaml
+  '404':
+    $ref: ../responses/404.yaml

specifications/operations/agent_delete.yaml

@@ -0,0 +1,20 @@
+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: ../parameters/path/uid_based_id_as_version_uid.yaml
+responses:
+  '204':
+    $ref: ../responses/204_AGENT_deleted.yaml
+  '400':
+    $ref: ../responses/400_already_deleted.yaml
+  '404':
+    $ref: ../responses/404.yaml
+  '409':
+    $ref: ../responses/409_AGENT_with_uid_based_id.yaml

specifications/operations/agent_get.yaml

@@ -0,0 +1,23 @@
+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 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_ AGENT version.
+
+  See [Resource identification](overview.html#tag/Resources/Resource-identification) for more details about the identifiers usage and meaning.
+tags:
+  - AGENT
+parameters:
+  - $ref: ../parameters/path/uid_based_id.yaml
+  - $ref: ../parameters/query/version_at_time.yaml
+responses:
+  '200':
+    $ref: ../responses/200_AGENT_retrieved.yaml
+  '204':
+    $ref: ../responses/204_because_deleted_at_time.yaml
+  '404':
+    $ref: ../responses/404_not_found_or_no_version_at_time.yaml

specifications/operations/agent_update.yaml

@@ -0,0 +1,35 @@
+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.
+tags:
+  - AGENT
+parameters:
+  - $ref: ../parameters/path/uid_based_id_as_versioned_object_uid.yaml
+  - $ref: ../parameters/header/If-Match.yaml
+  - $ref: ../parameters/header/Prefer.yaml
+requestBody:
+  description: |
+    The new AGENT.
+  content:
+    application/json:
+      schema:
+        $ref: ../schemas/demographic/Agent.yaml
+  required: true
+responses:
+  '200':
+    $ref: ../responses/200_AGENT_updated.yaml
+  '400':
+    $ref: ../responses/400.yaml
+  '404':
+    $ref: ../responses/404.yaml
+  '412':
+    $ref: ../responses/412_AGENT.yaml
+  '422':
+    $ref: ../responses/422.yaml

specifications/operations/versioned_agent_get.yaml

@@ -0,0 +1,13 @@
+operationId: versioned_agent_get
+summary: Get versioned AGENT
+description: |
+  Retrieves a VERSIONED_AGENT identified by `versioned_object_uid`.
+tags:
+  - AGENT
+parameters:
+  - $ref: ../parameters/path/versioned_object_uid_AGENT.yaml
+responses:
+  '200':
+    $ref: ../responses/200_VERSIONED_AGENT.yaml
+  '404':
+    $ref: ../responses/404.yaml

specifications/operations/versioned_agent_revision_history.yaml

@@ -0,0 +1,13 @@
+operationId: versioned_agent_revision_history
+summary: Get versioned AGENT revision history
+description: |
+  Retrieves revision history of the VERSIONED_AGENT identified by `versioned_object_uid`.
+tags:
+  - AGENT
+parameters:
+  - $ref: ../parameters/path/versioned_object_uid_AGENT.yaml
+responses:
+  '200':
+    $ref: ../responses/200_REVISION_HISTORY.yaml
+  '404':
+    $ref: ../responses/404.yaml

specifications/operations/versioned_agent_version_get_at_time.yaml

@@ -0,0 +1,16 @@
+operationId: versioned_agent_version_get_at_time
+summary: Get versioned AGENT version at time
+description: |
+  Retrieves a VERSION from the VERSIONED_AGENT identified by `versioned_object_uid`.
+
+  If `version_at_time` is supplied, retrieves the VERSION extant _at specified time_, otherwise retrieves the _latest_ VERSION.
+tags:
+  - AGENT
+parameters:
+  - $ref: ../parameters/path/versioned_object_uid_AGENT.yaml
+  - $ref: ../parameters/query/version_at_time.yaml
+responses:
+  '200':
+    $ref: ../responses/200_VERSION_of_AGENT_at_time.yaml
+  '404':
+    $ref: ../responses/404_not_found_or_no_version_at_time.yaml

specifications/operations/versioned_agent_version_get_by_id.yaml

@@ -0,0 +1,14 @@
+operationId: versioned_composition_version_get_by_id
+summary: Get versioned AGENT version by id
+description: |
+  Retrieves a VERSION identified by `version_uid` of a VERSIONED_AGENT identified by `versioned_object_uid`.
+tags:
+  - AGENT
+parameters:
+  - $ref: ../parameters/path/versioned_object_uid_AGENT.yaml
+  - $ref: ../parameters/path/version_uid.yaml
+responses:
+  '200':
+    $ref: ../responses/200_VERSION_of_AGENT_by_id.yaml
+  '404':
+    $ref: ../responses/404.yaml

specifications/parameters/path/versioned_object_uid_AGENT.yaml

@@ -0,0 +1,9 @@
+name: versioned_object_uid
+in: path
+description: |
+  VERSIONED_AGENT identifier taken from VERSIONED_AGENT.uid.value.
+required: true
+style: simple
+schema:
+  type: string
+  example: '6cb19121-4307-4648-9da0-d62e4d51f19b'

specifications/responses/200_AGENT_retrieved.yaml

@@ -0,0 +1,11 @@
+description: |
+  `200 OK` is returned when the requested AGENT is successfully retrieved.
+headers:
+  ETag:
+    $ref: ../headers/ETag.yaml
+  Location:
+    $ref: ../headers/Location_AGENT.yaml
+content:
+  application/json:
+    schema:
+      $ref: ../schemas/demographic/Agent.yaml

specifications/responses/200_AGENT_updated.yaml

@@ -0,0 +1,11 @@
+description: |
+  `200 OK` is returned when the AGENT is successfully updated and the updated resource is returned in the body when `Prefer` header value is `return=representation`.
+headers:
+  ETag:
+    $ref: ../headers/ETag.yaml
+  Location:
+    $ref: ../headers/Location_AGENT.yaml
+content:
+  application/json:
+    schema:
+      $ref: ../schemas/demographic/Agent.yaml

specifications/responses/200_VERSIONED_AGENT.yaml

@@ -0,0 +1,6 @@
+description: |
+  `200 OK` is returned when the requested VERSIONED_AGENT is successfully retrieved.
+content:
+  application/json:
+    schema:
+      $ref: ../schemas/demographic/VersionedAgent.yaml

specifications/responses/200_VERSION_of_AGENT_at_time.yaml

@@ -0,0 +1,11 @@
+description: |
+  `200 OK` is returned when the requested VERSION is successfully retrieved.
+headers:
+  ETag:
+    $ref: ../headers/ETag_VERSION.yaml
+  Location:
+    $ref: ../headers/Location_VERSIONED_AGENT_VERSION.yaml
+content:
+  application/json:
+    schema:
+      $ref: ../schemas/demographic/UVersionOfAgent.yaml

specifications/responses/200_VERSION_of_AGENT_by_id.yaml

@@ -0,0 +1,6 @@
+description: |
+  `200 OK` is returned when the requested VERSION is successfully retrieved.
+content:
+  application/json:
+    schema:
+      $ref: ../schemas/demographic/UVersionOfAgent.yaml

specifications/responses/201_AGENT.yaml

@@ -0,0 +1,12 @@
+description: |
+  `201 Created` is returned when the AGENT was created. 
+  Content body is only returned when `Prefer` header has `return=representation`, otherwise only headers are returned.
+headers:
+  ETag:
+    $ref: ../headers/ETag.yaml
+  Location:
+    $ref: ../headers/Location_AGENT.yaml
+content:
+  application/json:
+    schema:
+      $ref: ../schemas/demographic/Agent.yaml

specifications/responses/204_AGENT_deleted.yaml

@@ -0,0 +1,7 @@
+description: |
+  `204 No Content` is returned when AGENT was deleted.
+headers:
+  ETag:
+    $ref: ../headers/ETag.yaml
+  Location:
+    $ref: ../headers/Location_AGENT.yaml

specifications/responses/409_AGENT_with_uid_based_id.yaml

@@ -0,0 +1,8 @@
+description: |
+  `409 Conflict` is returned when supplied `uid_based_id` doesn't match the latest version.
+  Returns also latest version in the `Location` and `ETag` headers.
+headers:
+  ETag:
+    $ref: ../headers/ETag.yaml
+  Location:
+    $ref: ../headers/Location_AGENT.yaml

specifications/responses/412_AGENT.yaml

@@ -0,0 +1,8 @@
+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 `Location` and `ETag` headers.
+headers:
+  ETag:
+    $ref: ../headers/ETag.yaml
+  Location:
+    $ref: ../headers/Location_AGENT.yaml

specifications/schemas/demographic/UMImportedVersionOfAgent.yaml

@@ -0,0 +1,15 @@
+title: IMPORTED_VERSION
+type: object
+allOf:
+  - $ref: ../common/ImportedVersion.yaml
+required:
+  - _type
+properties:
+  _type:
+    type: string
+    enum: [IMPORTED_VERSION]
+  data:
+    $ref: ../demographic/Agent.yaml
+  item:
+    $ref: ../demographic/UMOriginalVersionOfAgent.yaml
+x-discriminator-value: IMPORTED_VERSION

specifications/schemas/demographic/UMOriginalVersionOfAgent.yaml

@@ -0,0 +1,13 @@
+title: ORIGINAL_VERSION
+type: object
+allOf:
+  - $ref: ../common/OriginalVersion.yaml
+required:
+  - _type
+properties:
+  _type:
+    type: string
+    enum: [ORIGINAL_VERSION]
+  data:
+    $ref: ../demographic/Agent.yaml
+x-discriminator-value: ORIGINAL_VERSION

specifications/schemas/demographic/UVersionOfAgent.yaml

@@ -0,0 +1,9 @@
+title: VERSION
+oneOf:
+  - $ref: ../demographic/UMOriginalVersionOfAgent.yaml
+  - $ref: ../demographic/UMImportedVersionOfAgent.yaml
+discriminator:
+  propertyName: _type
+  mapping:
+    ORIGINAL_VERSION: ../demographic/UMOriginalVersionOfAgent.yaml
+    IMPORTED_VERSION: ../demographic/UMImportedVersionOfAgent.yaml

specifications/schemas/demographic/VersionOfAgent.yaml

@@ -0,0 +1,18 @@
+title: VERSION
+type: object
+description: A VERSION resource
+required:
+  - contribution
+  - commit_audit
+  - data
+properties:
+  _type:
+    type: string
+  contribution:
+    $ref: ../base_types/ObjectRef.yaml
+  signature:
+    type: string
+  commit_audit:
+    $ref: ../common/AuditDetails.yaml
+  data:
+    $ref: ../demographic/Agent.yaml

specifications/schemas/demographic/VersionedAgent.yaml

@@ -0,0 +1,21 @@
+title: VERSIONED_AGENT
+description: A VERSIONED_AGENT resource
+type: object
+allOf:
+  - $ref: ../common/VersionedObject.yaml
+properties:
+  _type:
+    type: string
+    default: VERSIONED_AGENT
+x-discriminator-value: VERSIONED_AGENT
+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'