[qoc] endpoint /qoc/indicator/?/?/practices/? is now available

paths/qoc_indicator_{setKey}_{indicatorKey}_practices_{group}.yaml

@@ -0,0 +1,48 @@
+get:
+  tags:
+    - Quality of Care
+  summary: Show per-practice details for each practice in a group 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: group
+      in: path
+      description: The key as listed in the `list-groups` endpoint.
+      required: true
+      schema:
+        type: string
+      example: hwf
+    - 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 per-practice stats that can be rendered as a table or graph.
+      content:
+        application/json:
+          schema:
+            $ref: '../schemas/IndicatorParticipants.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_participating-practices_{group}_{setKey}.yaml

@@ -29,7 +29,7 @@ get:
   responses:
     '200':
       description: >-
-        A list of available groups.
+        A list of practices participating in this group.
       content:
         application/json:
           schema:

schemas/IndicatorDetail.yaml

@@ -5,18 +5,13 @@ 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.
+    $ref: 'Indicator.yaml#/properties/key'
-    type: string
+  title:
-    example: ZOO-dm
+    $ref: 'Indicator.yaml#/properties/title'
-  name:
+  type:
-    description: Human readable dutch text; should fit in one line. *HTML*.
+    $ref: 'Indicator.yaml#/properties/type'
-    type: string
-    example: Diabetes Mellitus type 2 – per InEen 2023 accreditatie
   refDate:
-    description: 'All calculations are done on this date (dutch: _peildatum_).'
+    $ref: 'IndicatorSet.yaml#/properties/refDate'
-    type: string
-    format: date
-    example: 2023-04-01
   description:
     description: A more detailed description of what this indicator calculates. *HTML*
     type: string

schemas/IndicatorParticipants.yaml

@@ -0,0 +1,100 @@
+description: |-
+  A report about a specific aspect of a care program, listing the stats of each participating GP practice.
+type: object
+properties:
+  group:
+    description: Repeats the `group` parameter.
+    type: string
+    example: hwf
+  key:
+    $ref: 'Indicator.yaml#/properties/key'
+  title:
+    $ref: 'Indicator.yaml#/properties/title'
+  type:
+    $ref: 'Indicator.yaml#/properties/type'
+  refDate:
+    $ref: 'IndicatorSet.yaml#/properties/refDate'
+  description:
+    $ref: 'IndicatorDetail.yaml#/properties/description'
+  descriptionDetail:
+    $ref: 'IndicatorDetail.yaml#/properties/descriptionDetail'
+  xMin:
+    $ref: 'Indicator.yaml#/properties/xMin'
+  xMax:
+    $ref: 'Indicator.yaml#/properties/xMax'
+  markers:
+    $ref: 'Indicator.yaml#/properties/markers'
+  unitDesc:
+    $ref: 'Indicator.yaml#/properties/unitDesc'
+  legend:
+    $ref: 'Indicator.yaml#/properties/legend'
+  skipped:
+    description: One entry for each GP practice participating in the chosen group but excluded from this chronic care program
+    type: array
+    items:
+      type: object
+      properties:
+        name:
+          description: Name of the GP practice
+          type: string
+        agb:
+          description: AGB of the GP practice, if known.
+          type: integer
+        skipReason:
+          description: Human readable string describing why this GP practice is excluded (in dutch, *HTML*).
+          type: string
+      required:
+        - name
+        - skipReason
+  participants:
+    description: One entry for each GP practice participating in the chosen group and in this chronic care program
+    type: array
+    items:
+      type: object
+      properties:
+        gpis:
+          $ref: 'GPIS.yaml'
+        name:
+          $ref: '#/properties/skipped/items/properties/name'
+        agb:
+          $ref: '#/properties/skipped/items/properties/agb'
+        amplitude:
+          description: |-
+            The relative weight of this practice compared to all practices (the ratio of this practice's population vs. the total population).
+            A higher number means this practice has many patients in its `population`, a lower meaning means fewer.
+          type: number
+          format: double
+          minimum: 0.0
+          maximum: 1.0
+        population:
+          description: |-
+            The amount of patients for this GP practice that are relevant for this indicator: Each patient in this population is assigned
+            into one of the categories of this indicator (which may be the 'not measured for this patient' category).
+          type: integer
+          minimum: 0
+          format: int32
+        values:
+          description: |-
+            For each entry in the `legend`, one value representing how many patients are assigned into that category. For legend-less indicators,
+            this array will only contain a single number.
+          type: array
+          items:
+            type: integer
+            minimum: 0
+            format: int32
+      required:
+        - gpis
+        - name
+        - amplitude
+        - population
+        - values
+required:
+  - group
+  - key
+  - title
+  - type
+  - refDate
+  - description
+  - markers
+  - skipped
+  - participants

zoo-api.yaml

@@ -52,6 +52,8 @@ paths:
     $ref: 'paths/qoc_indicatorset_{setKey}.yaml'
   /qoc/indicator/{setKey}/{indicatorKey}/patients:
     $ref: 'paths/qoc_indicator_{setKey}_{indicatorKey}_patients.yaml'
+  /qoc/indicator/{setKey}/{indicatorKey}/practices/{group}:
+    $ref: 'paths/qoc_indicator_{setKey}_{indicatorKey}_practices_{group}.yaml'
   /qoc/list-groups:
     $ref: 'paths/qoc_list-groups.yaml'
   /qoc/participating-practices/{group}/{setKey}: