[qoc] Add participating-practices, indicator-detail, and list-groups endpoints

paths/qoc_indicator_{setKey}_{indicatorKey}_patients.yaml

@@ -0,0 +1,42 @@
+get:
+  tags:
+    - Quality of Care
+  summary: Show per-patient details for a specific indicator
+  parameters:
+    - name: setKey
+      in: path
+      description: The key as listed in the `CareProgram` schema.
+      required: true
+      schema:
+        type: string
+      example: ZEL-dm
+    - name: indicatorKey
+      in: path
+      description: The key as listed in the indicatorset.
+      schema:
+        type: string
+        example: ZOO-dm2-hb-3
+    - name: refDate
+      in: query
+      description: |-
+        The date in `2023-04-01` format; defaults to the first day in the next quarter, e.g. on april 5th 2023, defaults to `2023-07-01`.
+      required: false
+      schema:
+        type: string
+        format: date
+        example: 2023-04-01
+  responses:
+    '200':
+      description: >-
+        Some descriptive text explaining this indicator in detail as well as a per-patient report.
+      content:
+        application/json:
+          schema:
+            $ref: '../schemas/IndicatorDetail.yaml'
+    '401':
+      $ref: '../zoo-api.yaml/#/components/responses/NoAuth'
+    '403':
+      $ref: '../zoo-api.yaml#/components/responses/NoAccess'
+    '404':
+      description: The provided `setKey` and/or `indicatorKey` do not refer to a valid program or indicator.
+

paths/qoc_list-groups.yaml

@@ -0,0 +1,42 @@
+get:
+  tags:
+    - Quality of Care
+  summary: Show all groups available for indicator reports. A group is a group of GP practices that do (part) of chronic care together.
+  parameters:
+    - name: refDate
+      in: query
+      description: |-
+        The date in `2023-04-01` format; defaults to the first day in the next quarter, e.g. on april 5th 2023, defaults to `2023-07-01`.
+      required: false
+      schema:
+        type: string
+        format: date
+        example: 2023-04-01
+  responses:
+    '200':
+      description: >-
+        A list of available groups.
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              refDate:
+                description: 'Groups reported are available for this date (dutch: _peildatum_).'
+                type: string
+                format: date
+                example: 2023-04-01
+              groups:
+                description: A list of available groups.
+                type: array
+                items:
+                  description: A tag (generally lower-case, no spaces).
+                  type: string
+                  example: hwf
+            required:
+              - refDate
+              - groups
+    '401':
+      $ref: '../zoo-api.yaml/#/components/responses/NoAuth'
+    '403':
+      $ref: '../zoo-api.yaml#/components/responses/NoAccess'

paths/qoc_participating-practices_{group}_{setKey}.yaml

@@ -0,0 +1,112 @@
+get:
+  tags:
+    - Quality of Care
+  summary: Show each participating GP practice as well as the status of their data for a given indicator report and a given group.
+  parameters:
+    - name: group
+      in: path
+      description: The key as listed in the `list-groups` endpoint.
+      required: true
+      schema:
+        type: string
+      example: hwf
+    - name: setKey
+      in: path
+      description: The key as listed in the `CareProgram` schema.
+      required: true
+      schema:
+        type: string
+      example: ZEL-dm
+    - name: refDate
+      in: query
+      description: |-
+        The date in `2023-04-01` format; defaults to the first day in the next quarter, e.g. on april 5th 2023, defaults to `2023-07-01`.
+      required: false
+      schema:
+        type: string
+        format: date
+        example: 2023-04-01
+  responses:
+    '200':
+      description: >-
+        A list of available groups.
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              group:
+                description: Repeats the `group` parameter.
+                type: string
+                example: hwf
+              calculatedAt:
+                description: |-
+                  *OPTIONAL*. The timestamp when the group average was calculated. If not present, no group average calculation is available.
+                type: string
+                format: dateTime
+                example: 2023-04-01T12:30:00.000Z
+              refDate:
+                description: 'Groups reported are available for this date (dutch: _peildatum_).'
+                type: string
+                format: date
+                example: 2023-04-01
+              key:
+                description: Repeats the `setKey` parameter.
+                type: string
+                example: ZOO-dm
+              title:
+                description: The title of the requested indicator set.
+                type: string
+                example: Diabetes Mellitus type 2
+              participants:
+                description: A list of practices in this group.
+                type: array
+                items:
+                  type: object
+                  properties:
+                    agb:
+                      description: The AGB code for this practice.
+                      type: number
+                      example: 1012345
+                    name:
+                      description: The name of this practice.
+                      type: string
+                      example: Huisartsenpraktijk Mien Dobbelsteen
+                    his:
+                      description: The type of GP Information System
+                      type: string
+                    exclusionReason:
+                      description: |-
+                        If present, this GP is excluded from this care program. The value describes (dutch, *HTML*) why.
+                        If not present, `mostRecentDataAvailable` will be available.
+                      type: string
+                    calculationBasedOn:
+                      description: |-
+                        If present, this GP practice is calculated for this refDate for this care program, and the calculation
+                        is based on a snapshot of HIS data at this instant.
+                      type: string
+                      format: datetime
+                      example: 2023-04-01T12:30:00.000Z
+                    mostRecentDataAvailable:
+                      description: |-
+                        If present, this GP practice's most recent available data is a HIS snapshot with HIS data at this instant.
+                        Usually equal to `calculationBasedOn`, but can be newer. If not present, this GP practice has no data available.
+                      type: string
+                      format: datetime
+                      example: 2023-04-01T12:30:00.000Z
+                  required:
+                    - agb
+                    - name
+                    - his
+            required:
+              - group
+              - refDate
+              - key
+              - title
+              - participants
+    '401':
+      $ref: '../zoo-api.yaml/#/components/responses/NoAuth'
+    '403':
+      $ref: '../zoo-api.yaml#/components/responses/NoAccess'
+    '404':
+      description: The provided `group` and/or `setKey` do not refer to a valid group or program.

schemas/IndicatorDetail.yaml

@@ -0,0 +1,82 @@
+description: |-
+  A report about a specific aspect of a care program, listing how each patient is categorized.
+type: object
+properties:
+  gpis:
+    $ref: 'GPIS.yaml'
+  key:
+    description: Unique identifier, not to be shown to the user, for referring to this indicator set in other API calls.
+    type: string
+    example: ZOO-dm
+  name:
+    description: Human readable dutch text; should fit in one line. *HTML*.
+    type: string
+    example: Diabetes Mellitus type 2 – per InEen 2023 accreditatie
+  refDate:
+    description: 'All calculations are done on this date (dutch: _peildatum_).'
+    type: string
+    format: date
+    example: 2023-04-01
+  description:
+    description: A more detailed description of what this indicator calculates. *HTML*
+    type: string
+  descriptionDetail:
+    description: |-
+      *OPTIONAL* A description of which exact formulas and codes are checked to calculate this indicator. *HTML*.
+    type: string
+  blocks:
+    description: |-
+      A block describes one particular outcome (such as 'patients with conflicting registration').
+    type: array
+    items:
+      type: object
+      required:
+        - title
+        - patients
+      properties:
+        title:
+          description: Describes the nature of what this block of patients represents. *HTML*.
+          type: string
+          example: >-
+            Hoofdbehandelaar is geregistreerd als 'Onbekend'
+        description:
+          description: |-
+            *OPTIONAL* Additional information about this block of patients; usually instructions about recommended medical / GP actions. *HTML*.
+          type: string
+          example: |-
+            Voor deze patiënten hebben we geen registratie van de hoofdbehandelaar kunnen vinden in de uit uw HIS aangeboden informatie.<br />
+            We raden u om deze lijst door te nemen en de hoofdbehandelaar te registreren.
+        patients:
+          description: |-
+            A list of all patients in this block with details about why they are in this block.
+          type: array
+          items:
+            type: object
+            properties:
+              pat_unid:
+                $ref: 'pat-patUnid.yaml'
+              bsn:
+                $ref: 'pat-BSN.yaml'
+              name:
+                $ref: 'pat-Name.yaml'
+              dob:
+                $ref: 'pat-DOB.yaml'
+              expl:
+                description: |-
+                  An explanation of why this patient is in this block, in medmark format.
+                type: string
+                example: |-
+                  [NHG DMHB TZ] = [NHGA 49] op [DATE 20220223].
+            required:
+              - pat_unid
+              - bsn
+              - name
+              - dob
+              - expl
+required:
+  - gpis
+  - key
+  - name
+  - refDate
+  - description
+  - chapters

zoo-api.yaml

@@ -50,6 +50,12 @@ paths:
     $ref: 'paths/qoc_careprogram_{careprogramKey}_fave.yaml'
   /qoc/indicatorset/{setKey}:
     $ref: 'paths/qoc_indicatorset_{setKey}.yaml'
+  /qoc/indicator/{setKey}/{indicatorKey}/patients:
+    $ref: 'paths/qoc_indicator_{setKey}_{indicatorKey}_patients.yaml'
+  /qoc/list-groups:
+    $ref: 'paths/qoc_list-groups.yaml'
+  /qoc/participating-practices/{group}/{setKey}:
+    $ref: 'paths/qoc_participating-practices_{group}_{setKey}.yaml'
 components:
   parameters:
     Authorization: