refactor all PARTY operations so that they are now based on concrete …

…type PERSON (#99 SPECITS-70)

specifications/demographic.openapi.yaml

@@ -22,43 +22,41 @@ servers:
         description: The (example) server base URL prefix providing openEHR services. This may contain server name, port and base path prefix.
 security: []
 paths:
-  '/demographic/actor':
+  '/demographic/person':
     post:
-      $ref: ./operations/party_create.yaml
-  '/demographic/party/{uid_based_id}':
+      $ref: ./operations/person_create.yaml
+  '/demographic/person/{uid_based_id}':
     get:
-      $ref: ./operations/party_get.yaml
+      $ref: ./operations/person_get.yaml
     put:
-      $ref: ./operations/party_update.yaml
+      $ref: ./operations/person_update.yaml
     delete:
-      $ref: ./operations/party_delete.yaml
-  '/demographic/versioned_party/{versioned_object_uid}':
+      $ref: ./operations/person_delete.yaml
+  '/demographic/versioned_person/{versioned_object_uid}':
     get:
-      $ref: ./operations/versioned_party_get.yaml
-  '/demographic/versioned_party/{versioned_object_uid}/revision_history':
+      $ref: ./operations/versioned_person_get.yaml
+  '/demographic/versioned_person/{versioned_object_uid}/revision_history':
     get:
-      $ref: ./operations/versioned_party_revision_history.yaml
-  '/demographic/versioned_party/{versioned_object_uid}/version':
+      $ref: ./operations/versioned_person_revision_history.yaml
+  '/demographic/versioned_person/{versioned_object_uid}/version':
     get:
-      $ref: ./operations/versioned_party_version_get_at_time.yaml
-  '/demographic/versioned_party/{versioned_object_uid}/version/{version_uid}':
+      $ref: ./operations/versioned_person_version_get_at_time.yaml
+  '/demographic/versioned_person/{versioned_object_uid}/version/{version_uid}':
     get:
-      $ref: ./operations/versioned_party_version_get_by_id.yaml
+      $ref: ./operations/versioned_person_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
+  - name: PERSON
     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.
+      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.
   - 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:

specifications/headers/Location_PERSON.yaml

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

specifications/headers/Location_VERSIONED_PARTY_VERSION.yaml → specifications/headers/Location_VERSIONED_PERSON_VERSION.yaml

@@ -3,4 +3,4 @@ description: |
 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'
+  example: 'https://openEHRSys.example.com/v1/demographic/versioned_person/6cb19121-4307-4648-9da0-d62e4d51f19b/version/6cb19121-4307-4648-9da0-d62e4d51f19b::openEHRSys.example.com::1'

specifications/operations/person_create.yaml

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

specifications/operations/party_delete.yaml → specifications/operations/person_delete.yaml

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

specifications/operations/party_get.yaml → specifications/operations/person_get.yaml

@@ -1,22 +1,22 @@
-operationId: party_get
-summary: Get PARTY
+operationId: person_get
+summary: Get PERSON
 description: |
-  Retrieves a version of the PARTY identified by `uid_based_id`.
+  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 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).
+  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 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.
+  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.
 tags:
-  - PARTY
+  - PERSON
 parameters:
   - $ref: ../parameters/path/uid_based_id.yaml
   - $ref: ../parameters/query/version_at_time.yaml
 responses:
   '200':
-    $ref: ../responses/200_PARTY_retrieved.yaml
+    $ref: ../responses/200_PERSON_retrieved.yaml
   '204':
     $ref: ../responses/204_because_deleted_at_time.yaml
   '404':

specifications/operations/person_update.yaml

@@ -0,0 +1,35 @@
+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: ../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 PERSON.
+  content:
+    application/json:
+      schema:
+        $ref: ../schemas/demographic/Person.yaml
+  required: true
+responses:
+  '200':
+    $ref: ../responses/200_PERSON_updated.yaml
+  '400':
+    $ref: ../responses/400.yaml
+  '404':
+    $ref: ../responses/404.yaml
+  '412':
+    $ref: ../responses/412_PERSON.yaml
+  '422':
+    $ref: ../responses/422.yaml

specifications/operations/versioned_person_get.yaml

@@ -0,0 +1,13 @@
+operationId: versioned_person_get
+summary: Get versioned PERSON
+description: |
+  Retrieves a VERSIONED_PERSON identified by `versioned_object_uid`.
+tags:
+  - PERSON
+parameters:
+  - $ref: ../parameters/path/versioned_object_uid_PERSON.yaml
+responses:
+  '200':
+    $ref: ../responses/200_VERSIONED_PERSON.yaml
+  '404':
+    $ref: ../responses/404.yaml

specifications/operations/versioned_person_revision_history.yaml

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

specifications/operations/versioned_person_version_get_at_time.yaml

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

specifications/operations/versioned_party_version_get_by_id.yaml → specifications/operations/versioned_person_version_get_by_id.yaml

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

specifications/parameters/path/versioned_object_uid_PARTY.yaml → specifications/parameters/path/versioned_object_uid_PERSON.yaml

@@ -1,7 +1,7 @@
 name: versioned_object_uid
 in: path
 description: |
-  VERSIONED_PARTY identifier taken from VERSIONED_PARTY.uid.value.
+  VERSIONED_PERSON identifier taken from VERSIONED_PERSON.uid.value.
 required: true
 style: simple
 schema: