adding and updating demographic spec (#99 SPECITS-70)

specifications/demographic.openapi.yaml

@@ -24,76 +24,42 @@ security: []
 paths:
   '/demographic/actor':
     post:
-      $ref: ./operations/actor_create.yaml
-  # '/ehr/{ehr_id}/composition/{uid_based_id}':
-  #   get:
-  #     $ref: ./operations/composition_get.yaml
-  #   put:
-  #     $ref: ./operations/composition_update.yaml
-  #   delete:
-  #     $ref: ./operations/composition_delete.yaml
-  # '/ehr/{ehr_id}/versioned_composition/{versioned_object_uid}':
-  #   get:
-  #     $ref: ./operations/versioned_composition_get.yaml
-  # '/ehr/{ehr_id}/versioned_composition/{versioned_object_uid}/revision_history':
-  #   get:
-  #     $ref: ./operations/versioned_composition_revision_history.yaml
-  # '/ehr/{ehr_id}/versioned_composition/{versioned_object_uid}/version':
-  #   get:
-  #     $ref: ./operations/versioned_composition_version_get_at_time.yaml
-  # '/ehr/{ehr_id}/versioned_composition/{versioned_object_uid}/version/{version_uid}':
-  #   get:
-  #     $ref: ./operations/versioned_composition_version_get_by_id.yaml
-  # '/ehr/{ehr_id}/directory':
-  #   post:
-  #     $ref: ./operations/directory_create.yaml
-  #   put:
-  #     $ref: ./operations/directory_update.yaml
-  #   delete:
-  #     $ref: ./operations/directory_delete.yaml
-  #   get:
-  #     $ref: ./operations/directory_get_at_time.yaml
-  # '/ehr/{ehr_id}/directory/{version_uid}':
-  #   get:
-  #     $ref: ./operations/directory_get_by_version_id.yaml
-  # '/ehr/{ehr_id}/contribution':
-  #   post:
-  #     $ref: ./operations/contribution_create.yaml
-  # '/ehr/{ehr_id}/contribution/{contribution_uid}':
-  #   get:
-  #     $ref: ./operations/contribution_get.yaml
-# tags: TODO: add demographic tags
-#   - name: DIRECTORY
-#     description: |
-#       Management of the [directory](https://specifications.openehr.org/releases/RM/latest/ehr.html#_directory) [FOLDER](https://specifications.openehr.org/releases/RM/latest/common.html#_folder_class) resource.
-#       Actions upon resources of this group are also formally described in the [I_EHR_DIRECTORY](https://specifications.openehr.org/releases/SM/latest/openehr_platform.html#_i_ehr_directory_interface) Abstract Service Model interface.
-#   - name: CONTRIBUTION
-#     description: |
-#       Management of [CONTRIBUTION](https://specifications.openehr.org/releases/RM/latest/common.html#_contribution_class) resource.
-#       Actions upon resources of this group are also formally described in the [I_EHR_CONTRIBUTION](https://specifications.openehr.org/releases/SM/latest/openehr_platform.html#_i_ehr_contribution_interface) Abstract Service Model interface.
-#   - name: DIRECTORY_schema
-#     x-displayName: DIRECTORY
-#     description:
-#       $ref: ./tags/DIRECTORY_schema.md
-#   - name: CONTRIBUTION_schema
-#     x-displayName: CONTRIBUTION
-#     description:
-#       $ref: ./tags/CONTRIBUTION_schema.md
-x-tagGroups:
-  - name: Resource endpoints
-    tags:
-      - DEMOGRAPHIC
-      - ACTOR
-      - DIRECTORY
-      - CONTRIBUTION
-  - name: Resource schemas
-    tags:
-      - DEMOGRAPHIC_schema
-      - DIRECTORY_schema
-      - CONTRIBUTION_schema
-# components:
-#   schemas:
-#     UAbstractItemStructure:
-#       $ref: ./schemas/data_structures/UAbstractItemStructure.yaml
-    # UAbstractContentItem:
-    #   $ref: ./schemas/ehr/UAbstractContentItem.yaml
+      $ref: ./operations/party_create.yaml
+  '/demographic/party/{uid_based_id}':
+    get:
+      $ref: ./operations/party_get.yaml
+    put:
+      $ref: ./operations/party_update.yaml
+    delete:
+      $ref: ./operations/party_delete.yaml
+  '/demographic/versioned_party/{versioned_object_uid}':
+    get:
+      $ref: ./operations/versioned_party_get.yaml
+  '/demographic/versioned_party/{versioned_object_uid}/revision_history':
+    get:
+      $ref: ./operations/versioned_party_revision_history.yaml
+  '/demographic/versioned_party/{versioned_object_uid}/version':
+    get:
+      $ref: ./operations/versioned_party_version_get_at_time.yaml
+  '/demographic/versioned_party/{versioned_object_uid}/version/{version_uid}':
+    get:
+      $ref: ./operations/versioned_party_version_get_by_id.yaml
+  '/demographic/contribution':
+    post:
+      $ref: ./operations/contribution_create.yaml
+  '/demographic/contribution/{contribution_uid}':
+    get:
+      $ref: ./operations/contribution_get.yaml
+tags:
+  - name: PARTY
+    description: |
+      Management of the [directory](https://specifications.openehr.org/releases/RM/latest/ehr.html#_directory) [FOLDER](https://specifications.openehr.org/releases/RM/latest/common.html#_folder_class) resource.
+      Actions upon resources of this group are also formally described in the [I_EHR_DIRECTORY](https://specifications.openehr.org/releases/SM/latest/openehr_platform.html#_i_ehr_directory_interface) Abstract Service Model interface.
+  - name: CONTRIBUTION
+    description: |
+      Management of [CONTRIBUTION](https://specifications.openehr.org/releases/RM/latest/common.html#_contribution_class) resource.
+      Actions upon resources of this group are also formally described in the [I_EHR_CONTRIBUTION](https://specifications.openehr.org/releases/SM/latest/openehr_platform.html#_i_ehr_contribution_interface) Abstract Service Model interface.
+components:
+  schemas:
+    UAbstractItemStructure:
+      $ref: ./schemas/data_structures/UAbstractItemStructure.yaml

specifications/headers/Location_PARTY.yaml

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

specifications/headers/Location_VERSIONED_PARTY_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_party/6cb19121-4307-4648-9da0-d62e4d51f19b/version/6cb19121-4307-4648-9da0-d62e4d51f19b::openEHRSys.example.com::1'

specifications/operations/party_create.yaml

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

specifications/operations/party_delete.yaml

@@ -0,0 +1,20 @@
+operationId: party_delete
+summary: Delete PARTY
+description: |
+  Deletes the PARTY 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:
+  - PARTY
+parameters:
+  - $ref: ../parameters/path/uid_based_id_as_version_uid.yaml
+responses:
+  '204':
+    $ref: ../responses/204_PARTY_deleted.yaml
+  '400':
+    $ref: ../responses/400_already_deleted.yaml
+  '404':
+    $ref: ../responses/404.yaml
+  '409':
+    $ref: ../responses/409_PARTY_with_uid_based_id.yaml

specifications/operations/party_get.yaml

@@ -0,0 +1,23 @@
+operationId: party_get
+summary: Get PARTY
+description: |
+  Retrieves a version of the PARTY 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 PARTY (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_ PARTY version.
+
+  See [Resource identification](overview.html#tag/Resources/Resource-identification) for more details about the identifiers usage and meaning.
+tags:
+  - PARTY
+parameters:
+  - $ref: ../parameters/path/uid_based_id.yaml
+  - $ref: ../parameters/query/version_at_time.yaml
+responses:
+  '200':
+    $ref: ../responses/200_PARTY_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/party_update.yaml

@@ -0,0 +1,35 @@
+operationId: party_update
+summary: Update PARTY
+description: |
+  Updates PARTY 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 PARTY.uid.value, it must match the `uid_based_id` in the URL. 
+
+  The existing latest `version_uid` of PARTY resource (i.e. the `preceding_version_uid`) must be specified in the `If-Match` header.
+tags:
+  - PARTY
+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 PARTY.
+  content:
+    application/json:
+      schema:
+        $ref: ../schemas/demographic/UParty.yaml
+  required: true
+responses:
+  '200':
+    $ref: ../responses/200_PARTY_updated.yaml
+  '400':
+    $ref: ../responses/400_PARTY.yaml
+  '404':
+    $ref: ../responses/404.yaml
+  '412':
+    $ref: ../responses/412_PARTY.yaml
+  '422':
+    $ref: ../responses/422_PARTY.yaml

specifications/operations/versioned_party_get.yaml

@@ -0,0 +1,13 @@
+operationId: versioned_party_get
+summary: Get versioned PARTY
+description: |
+  Retrieves a VERSIONED_PARTY identified by `versioned_object_uid`.
+tags:
+  - PARTY
+parameters:
+  - $ref: ../parameters/path/versioned_object_uid_PARTY.yaml
+responses:
+  '200':
+    $ref: ../responses/200_VERSIONED_PARTY.yaml
+  '404':
+    $ref: ../responses/404.yaml

specifications/operations/versioned_party_revision_history.yaml

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

specifications/operations/versioned_party_version_get_at_time.yaml

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

specifications/operations/versioned_party_version_get_by_id.yaml

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

specifications/parameters/path/versioned_object_uid_PARTY.yaml

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

specifications/responses/200_PARTY_retrieved.yaml

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

specifications/responses/200_PARTY_updated.yaml

@@ -0,0 +1,11 @@
+description: |
+  `200 OK` is returned when the UPDATE 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_PARTY.yaml
+content:
+  application/json:
+    schema:
+      $ref: ../schemas/demographic/UParty.yaml

specifications/responses/200_VERSIONED_PARTY.yaml

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

specifications/responses/200_VERSION_of_PARTY_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_PARTY_VERSION.yaml
+content:
+  application/json:
+    schema:
+      $ref: ../schemas/demographic/UVersionOfParty.yaml

specifications/responses/200_VERSION_of_PARTY_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/UVersionOfParty.yaml

specifications/responses/201_PARTY.yaml

@@ -0,0 +1,12 @@
+description: |
+  `201 Created` is returned when the PARTY 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_PARTY.yaml
+content:
+  application/json:
+    schema:
+      $ref: ../schemas/demographic/UParty.yaml