adding GROUP, ORGANISATION and ROLE resources (#99 SPECITS-70)

specifications/demographic.openapi.yaml

@@ -44,6 +44,50 @@ paths:
   '/demographic/versioned_agent/{versioned_object_uid}/version/{version_uid}':
     get:
       $ref: ./operations/versioned_agent_version_get_by_id.yaml
+  '/demographic/group':
+    post:
+      $ref: ./operations/group_create.yaml
+  '/demographic/group/{uid_based_id}':
+    get:
+      $ref: ./operations/group_get.yaml
+    put:
+      $ref: ./operations/group_update.yaml
+    delete:
+      $ref: ./operations/group_delete.yaml
+  '/demographic/versioned_group/{versioned_object_uid}':
+    get:
+      $ref: ./operations/versioned_group_get.yaml
+  '/demographic/versioned_group/{versioned_object_uid}/revision_history':
+    get:
+      $ref: ./operations/versioned_group_revision_history.yaml
+  '/demographic/versioned_group/{versioned_object_uid}/version':
+    get:
+      $ref: ./operations/versioned_group_version_get_at_time.yaml
+  '/demographic/versioned_group/{versioned_object_uid}/version/{version_uid}':
+    get:
+      $ref: ./operations/versioned_group_version_get_by_id.yaml
+  '/demographic/organisation':
+    post:
+      $ref: ./operations/organisation_create.yaml
+  '/demographic/organisation/{uid_based_id}':
+    get:
+      $ref: ./operations/organisation_get.yaml
+    put:
+      $ref: ./operations/organisation_update.yaml
+    delete:
+      $ref: ./operations/organisation_delete.yaml
+  '/demographic/versioned_organisation/{versioned_object_uid}':
+    get:
+      $ref: ./operations/versioned_organisation_get.yaml
+  '/demographic/versioned_organisation/{versioned_object_uid}/revision_history':
+    get:
+      $ref: ./operations/versioned_organisation_revision_history.yaml
+  '/demographic/versioned_organisation/{versioned_object_uid}/version':
+    get:
+      $ref: ./operations/versioned_organisation_version_get_at_time.yaml
+  '/demographic/versioned_organisation/{versioned_object_uid}/version/{version_uid}':
+    get:
+      $ref: ./operations/versioned_organisation_version_get_by_id.yaml
   '/demographic/person':
     post:
       $ref: ./operations/person_create.yaml
@@ -66,6 +110,28 @@ paths:
   '/demographic/versioned_person/{versioned_object_uid}/version/{version_uid}':
     get:
       $ref: ./operations/versioned_person_version_get_by_id.yaml
+  '/demographic/role':
+    post:
+      $ref: ./operations/role_create.yaml
+  '/demographic/role/{uid_based_id}':
+    get:
+      $ref: ./operations/role_get.yaml
+    put:
+      $ref: ./operations/role_update.yaml
+    delete:
+      $ref: ./operations/role_delete.yaml
+  '/demographic/versioned_role/{versioned_object_uid}':
+    get:
+      $ref: ./operations/versioned_role_get.yaml
+  '/demographic/versioned_role/{versioned_object_uid}/revision_history':
+    get:
+      $ref: ./operations/versioned_role_revision_history.yaml
+  '/demographic/versioned_role/{versioned_object_uid}/version':
+    get:
+      $ref: ./operations/versioned_role_version_get_at_time.yaml
+  '/demographic/versioned_role/{versioned_object_uid}/version/{version_uid}':
+    get:
+      $ref: ./operations/versioned_role_version_get_by_id.yaml
   '/demographic/contribution':
     post:
       $ref: ./operations/contribution_create.yaml
@@ -76,13 +142,41 @@ 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: GROUP
+    description: |
+      Management of the [GROUP](https://specifications.openehr.org/releases/RM/latest/demographic.html#_group_class) and the associated [VERSIONED_GROUP](https://specifications.openehr.org/releases/RM/latest/demographic.html#_versioned_party_class) resource.
+  - name: ORGANISATION
+    description: |
+      Management of the [ORGANISATION](https://specifications.openehr.org/releases/RM/latest/demographic.html#_organisation_class) and the associated [VERSIONED_ORGANISATION](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.
+  - name: ROLE
+    description: |
+      Management of the [ROLE](https://specifications.openehr.org/releases/RM/latest/demographic.html#_ROLE_class) and the associated [VERSIONED_ROLE](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.
+x-tagGroups:
+  - name: Resource endpoints
+    tags:
+      - AGENT
+      - GROUP
+      - ORGANISATION
+      - PERSON
+      - ROLE
+      - CONTRIBUTION
 components:
   schemas:
     UAbstractItemStructure:
       $ref: ./schemas/data_structures/UAbstractItemStructure.yaml
+    VersionOfAgent:
+      $ref: ./schemas/demographic/VersionOfAgent.yaml
+    VersionOfGroup:
+      $ref: ./schemas/demographic/VersionOfGroup.yaml
+    VersionOfOrganisation:
+      $ref: ./schemas/demographic/VersionOfOrganisation.yaml
+    VersionOfPerson:
+      $ref: ./schemas/demographic/VersionOfPerson.yaml
+    VersionOfRole:
+      $ref: ./schemas/demographic/VersionOfRole.yaml

specifications/headers/Location_GROUP.yaml

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

specifications/headers/Location_ORGANISATION.yaml

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

specifications/headers/Location_ROLE.yaml

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

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

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

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

specifications/operations/group_create.yaml

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

specifications/operations/group_delete.yaml

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

specifications/operations/group_get.yaml

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

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

specifications/operations/organisation_create.yaml

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

specifications/operations/organisation_delete.yaml

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

specifications/operations/organisation_get.yaml

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

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