[indicators] Added the 'future' property.

See commit cef3aff.

examples/qoc_indicatorsets.1.json

@@ -1,8 +1,9 @@
 {
 	"programs": [
 		{
-			"key": "ZOO-dm-poc",
-			"name": "Diabetes Mellitus Oproepen",
+			"key": "ZEL-Odm-1",
+			"name": "Diabetes Mellitus (ZEL)",
+			"subName": "Oproepen",
 			"description": "ZorgOpOrde standaard Diabetes Mellitus ketenzorg voor POHs (oproepen en patiënt populatie gezond houden). Indien er geen specifiek op uw zorggroep aangepaste DM definitie beschikbaar is.",
 			"tags": [
 				"DM",
@@ -12,10 +13,13 @@
 			"defaultShow": false,
 			"favState": "X",
 			"careProgram": "DM",
-			"type": "indicatorset"
-		},{
-			"key": "ZOO-dm-acc",
-			"name": "Diabetes Mellitus Accrediteren",
+			"type": "indicatorset",
+			"callup": true
+		},
+		{
+			"key": "ZEL-Rdm-1",
+			"name": "Diabetes Mellitus (ZEL)",
+			"subName": "Rapportage",
 			"description": "ZorgOpOrde standaard Diabetes Mellitus ketenzorg voor accrediteren, vergelijken met andere zorggroepen, en onderhandelen met de zorgverzekeraars. Indien er geen specifiek op uw zorggroep aangepaste DM definitie beschikbaar is.",
 			"tags": [
 				"DM",
@@ -25,34 +29,8 @@
 			"defaultShow": false,
 			"favState": "X",
 			"careProgram": "DM",
-			"type": "indicatorset"
-		},
-		{
-			"key": "IE22-copd",
-			"name": "InEen 2022 COPD",
-			"description": "InEen '22 invulformat voor COPD ketenzorg"
-			"tags": [
-				"COPD",
-				"InEen2022",
-			],
-			"defaultShow": false,
-			"favState": "T",
-			"type": "link",
-			"link": "/indicators/accreditatie?sets=IE22-copd"
-		},
-		{
-			"key": "ZEL-dm",
-			"name": "Diabetes Mellitus (ZEL) Oproepen",
-			"description": "Zorggroep ZEL (<em>regio NWN/DWO</em>) Diabetes Mellitus ketenzorg voor POHs (oproepen en patiënt populatie gezond houden).",
-			"tags": [
-				"DM",
-				"ZEL",
-				"Oproepen"
-			],
-			"defaultShow": true,
-			"favState": "X",
-			"careProgram": "COPD",
 			"type": "indicatorset",
+			"callup": false
 		},
 		{
 			"key": "ZOO-nierfalen",

paths/customer_basic.yaml

@@ -1,12 +1,14 @@
 get:
-  operationId: customerBasic
+  operationId: customerBasicGet
   tags:
     - Customer management
   summary: Basic info
   parameters:
     - name: agb
       in: query
-      description: AGB of the practice which is known as Zorg op Orde customer (via a care group).
+      description: |-
+        AGB of the practice for which basic info is requested.
+        If the requesting entity is a single GP practice, this parameter can be omitted.
       schema:
         $ref: ../schemas/agb.yaml
   responses:
@@ -30,10 +32,13 @@ get:
                   institutionAgb:
                     description: The AGB of the institution, if the customer is a care group or other institute, otherwise omitted. One of practiceAgb or institutionAgb is always present.
                     $ref: ../schemas/agb.yaml
-                  gpis:
+                  gpisMethod:
+                    description: The current GPIS type and how medical dossiers are transferred to Zorg op Orde.
+                    example: HealthConnected (automatische koppeling)
+                  lastImport:
                     $ref: ../schemas/GPIS.yaml
                   doctors:
-                    description: AGB's of the doctors working in the practice.
+                    description: AGBs of the doctors working in the practice.
                     type: array
                     items:
                       $ref: '../schemas/PatIdentity.yaml#/doctor'
@@ -43,6 +48,7 @@ get:
                       address1:
                         type: string
                         description: The first line of the practice postal address (street name and house number, generally).
+                        example: Dorpsstraat 1
                       postcode:
                         $ref: ../schemas/postcode.yaml
                       city:
@@ -52,23 +58,32 @@ get:
                     properties:
                       tel:
                         type: string
+                        example: "0612345678"
                       email:
                         type: string
+                        example: "M.Dobbelsteen@zorgoporde.nl"
+                  share_authorizations:
+                    description: The GP has granted permission to share certain aspects of the EPD data with the listed third parties.
+                    type: array
+                    example: ["KSYOS_FUNDUS"]
+                    items:
+                      type: string
                   dataProcessing:
                     type: object
                     properties:
                       controllers:
                         description: A list of personnel responsible for the data. Usually the practice owner.
                         type: array
+                        example: ["Mien Dobbelsteen", "Lydie van der Ploeg"]
                         items:
                           type: string
                       agreement:
-                        example: If set, the signer and date of the data processing agreement between the controller (responsible general practitioner) and processor (Zorg op Orde).
                         type: object
                         properties:
                           signedBy:
                             description: Full name of the signer.
                             type: string
+                            example: Lydie van der Ploeg
                           signedOn:
                             description: Date of signing the data processing agreement.
                             example: 20160501T1344
@@ -81,4 +96,49 @@ get:
     '401':
       $ref: '../zoo-api.yaml/#/components/responses/NoAuth'
     '403':
-      $ref: '../zoo-api.yaml/#/components/responses/NoAccess'
+      description: |-
+        User is not allowed to access this API endpoint, or,
+        the practice identified by the `agb` parameter does not have a relationship with the
+        user (for example, they do not belong to your care group).
+post:
+  operationId: customerBasicPost
+  tags:
+    - Customer management
+  summary: Basic info
+  description: Only certain properties of a practice can be updated. After updating the same response is outputted as when using GET.
+  parameters:
+    - name: agb
+      in: query
+      description: |-
+        AGB of the practice for which basic info is requested.
+        If the requesting entity is a single GP practice, this parameter can be omitted.
+      schema:
+        $ref: ../schemas/agb.yaml
+  requestBody:
+    description: |-
+      When authorized as a practice the address and contact data can be changed.
+      Currently, if authorized as a care group, no properties can be changed.
+      
+      Properties can be omitted if you do not want to change them. `address1` and `postcode` cannot be set to empty.
+    content:
+      'application/x-www-form-urlencoded':
+        schema:
+          type: object
+          properties:
+            address1:
+              type: string
+              description: The first line of the practice postal address (street name and house number, generally).
+            postcode:
+              description: Any valid Dutch postcode, with or without whitespacing and in lower- or uppercase.
+              $ref: ../schemas/postcode.yaml
+            city:
+              $ref: ../schemas/city.yaml
+            tel:
+              description: A Dutch phone number of 10 digits. Additional dashes and spacing are removed before validating.
+              type: string
+            email:
+              type: string
+              format: email
+  responses: 
+    $ref: '#/get/responses'
+    

paths/customer_careprogram.yaml

@@ -19,7 +19,10 @@ get:
         $ref: ../schemas/date.yaml
     - name: agbs
       in: query
-      description: A list of AGB's for which the care programs must be retrieved. If not a care group is authorized, or specified during authorization, then this parameter is ignored.
+      description: |-
+        If the requesting entity is a care group, all GP practices in the group will be returned; this parameter can be used to filter the list, so
+        that only those GP practices with one of the AGBs listed here are returned. If the requesting entity is a single GP practice, this parameter
+        is ignored.
       example: 12345678,23456789
       schema:
         type: array
@@ -27,7 +30,7 @@ get:
           $ref: ../schemas/agb.yaml
   responses:
     '200':
-      description: All practices for which the care group takes responsibility.
+      description: care program inclusions status of all relevant GP practices.
       content:
         application/json:
           schema:
@@ -35,19 +38,16 @@ get:
             properties:
               caregroup:
                 type: object
+                description: Information about the care group itself; will not be included if the authorizing entity is a GP practice.
                 properties:
                   name:
                     type: string
                     description: |-
                       Identifying tag name of the care group.
-
-                      In bare mode the first of possible several care groups is written in the response (see above for bare mode).
                     example: demo_fabel
                   careprograms:
                     description: |-
                       All care programs contracted by the care group. Subtract from this set the active care programs from any practice reported in `practices` to know which care programs they may want to activate.
-
-                      Empty array in bare mode (see description above).
                     example:
                       - OuderenZorg
                       - DM

paths/exports_available.yaml

@@ -1,13 +1,13 @@
 get:
   operationId: exportsAvailable
   tags:
-    - Exports
+    - GPIS exports
   summary: List available exports
   responses:
     '200':
       description: |-
-        Lists all available HIS export snapshots.
-        A HIS export snapshot contains parts of medical dossier info for a subset of all patients in a GP practice. Exactly which filters are applied,
+        Lists all available GPIS export snapshots.
+        A GPIS export snapshot contains parts of medical dossier info for a subset of all patients in a GP practice. Exactly which filters are applied,
         which data is provided, and how it is formatted is arranged between Zorg op Orde and a party using the ZOO API.
       content:
         application/json:

paths/exports_{agb}_{filename}.yaml

@@ -1,7 +1,7 @@
 get:
   operationId: exportsDownload
   tags:
-    - Exports
+    - GPIS exports
   summary: Download an available export
   parameters:
     - name: agb
@@ -20,7 +20,7 @@ get:
   responses:
     '200':
       description: |-
-        Fetches the requested HIS export as ZIP file.
+        Fetches the requested GPIS export as ZIP file.
         
         Note that the response will have content type `application/zip` even if the requester's `Accept` header does not indicate this mime type is supported.
     '401':

paths/exports_{agb}_{filename}_{tablename}.yaml

@@ -1,7 +1,7 @@
 get:
   operationId: exportsDownloadPerTable
   tags:
-    - Exports
+    - GPIS exports
   summary: Download one CSV table from an available export
   parameters:
     - name: agb
@@ -27,7 +27,7 @@ get:
   responses:
     '200':
       description: |-
-        Fetches the requested table from the HIS export.
+        Fetches the requested table from the GPIS export.
         
         Note that the response will have the content type of the request resource (usually `text/csv`) even if the requester's `Accept` header does not indicate this mime type is supported.
     '401':

paths/patient_base.yaml

@@ -63,6 +63,8 @@ get:
                 $ref: '../schemas/PatIdentity.yaml#/insurance'
               patid:
                 $ref: '../schemas/PatIdentity.yaml#/patid'
+              patPubId:
+                $ref: '../schemas/PatIdentity.yaml#/patPubId'
               patUnid:
                 $ref: '../schemas/PatIdentity.yaml#/patUnid'
               startDate:

paths/patient_contactList.yaml

@@ -0,0 +1,103 @@
+get:
+  operationId: contactList
+  tags:
+    - Patient
+  summary: Contact list
+  description: Get a contact list for printing address labels, sending e-mail and/ or calling.
+  parameters: 
+    - name: patUnids
+      in: query
+      mandatory: true
+      description: |-
+        A comma separated list of patUnid values, as provided by other API endpoints.
+        For each patUnid the contact details are in the response. If sending lots of patUnids, we suggest you call this API in a POST (which is also allowed, though the semantic intent of this method is GET: It only queries and makes no changes) to avoid HTTP limits on query length.
+      schema:
+        type: array
+        items:
+          $ref: ../schemas/pat-patUnid.yaml
+        example: "1234,5678"
+    - name: fields
+      in: query
+      mandatory: true
+      description: |-
+        Comma separated list of data fields that shold be returned in the response. Available options are:
+        bsn         - adds CSV column/JSON key 'bsn'.
+        patPubId    - adds CSV column/JSON key 'patPubId'.
+        patUnid     - adds CSV column/JSON key 'patUnid'.
+        gender      - adds CSV column/JSON key 'gender', with values 'O', 'M', or 'F'.
+        displayName - adds CSV column/JSON key 'displayName' with the full name of the patient as one would write it on an envelope.
+        fullName    - adds CSV columns 'initials', 'firstNames', 'infixOwn', 'ownLastName', 'infixPartner', 'partnerLastName', and JSON key 'name' with as value an object with those keys.
+        addressLine - adds CSV column/JSON key 'addressLine'.
+        postcode    - adds CSV column/JSON key 'postcode'.
+        city        - adds CSV column/JSON key 'city'.
+        tel         - adds CSV column/JSON key 'tel'.
+        email       - adds CSV column/JSON key 'email'.
+        dob         - adds CSV column/JSON key 'dob'.
+
+        See the descriptions in the JSON output section of this documentation for the formatting of these outputs.
+      example: "displayName,addressLine,postcode,city"
+    - name: Accept
+      in: header
+      description: |-
+        This API is capable of emitting both CSV (RFC 4180) and JSON. If a CSV response is needed, ensure mimetype `text/csv` is
+        mentioned in the `Accept` header at a higher quality than `application/csv`. If no Accept header is provided, the API
+        responds with JSON.
+      schema: 
+        type: string
+        enum: 
+          - text/csv
+          - application/json
+  responses:
+    '200':
+      description: |-
+        A patient contact list for (electronic) mailing or phone contact. Per patient only requested details (via `column`) are provided. Any patient that isn't found isn't included in the output.
+      headers:
+        Content-Type:
+          description: The actual content-type of the response.
+          schema: 
+            type: string
+      content:
+        application/json:
+          schema: 
+            type: array
+            items: 
+              type: object
+              properties:
+                patUnid:
+                  $ref: '../schemas/PatIdentity.yaml#/patUnid'
+                patPubId:
+                  $ref: '../schemas/PatIdentity.yaml#/patPubId'
+                gender:
+                  $ref: '../schemas/PatIdentity.yaml#/gender'
+                displayName:
+                  $ref: '../schemas/pat-Name.yaml#/properties/displayName'
+                name:
+                  $ref: '../schemas/PatIdentity.yaml#/name'
+                addressLine:
+                  description: The concatenation of street, housenumber and -suffix on one line.
+                  type: string
+                postcode:
+                  $ref: ../schemas/postcode.yaml
+                city:
+                  $ref: ../schemas/city.yaml
+                tel:
+                  $ref: '../schemas/PatIdentity.yaml#/contact/properties/tel'
+                email:
+                  $ref: '../schemas/PatIdentity.yaml#/contact/properties/email'
+                bsn:
+                  $ref: '../schemas/PatIdentity.yaml#/bsn'
+                dob:
+                  $ref: '../schemas/PatIdentity.yaml#/dob'
+        text/csv:
+          schema: 
+            type: string
+            description: |-
+              An RFC4180 (with comma separator) output, with headers as requested.
+    '400':
+      description: The request is invalid; for example, it doesn't contain the required `patUnids` or `columns` parameter.
+    '401':
+      $ref: '../zoo-api.yaml#/components/responses/JwtFailure'
+    '406':
+      description: |-
+        An accept header was sent, but neither `text/csv` nor `application/json` is allowed by it.
+        As this endpoint can only render its data in those two content types, no response is possible.

paths/patient_dossier.yaml

@@ -112,6 +112,14 @@ get:
                 description: |-
                   Contains core identification information about this patient; a duplication of the `/patient/base` API.
                 type: object
+                required:
+                  - bsn
+                  - name
+                  - gender
+                  - patid
+                  - patUnid
+                  - category
+                  - startDate
                 properties:
                   bsn:
                     $ref: '../schemas/PatIdentity.yaml#/bsn'
@@ -133,6 +141,8 @@ get:
                     $ref: '../schemas/PatIdentity.yaml#/insurance'
                   patid:
                     $ref: '../schemas/PatIdentity.yaml#/patid'
+                  patPubId:
+                    $ref: '../schemas/PatIdentity.yaml#/patPubId'
                   patUnid:
                     $ref: '../schemas/PatIdentity.yaml#/patUnid'
                   startDate:

paths/patient_fundusByGroup.yaml

@@ -49,11 +49,41 @@ get:
       schema:
         type: string
         enum: ['gp', 'specialist', 'unknown', '']
+    - name: ifNewerThan
+      in: query
+      required: false
+      description: |-
+        Useful to check if new data is available relative to an earlier request: Provide the same date as provided in a previous response's `refDate` value.
+        If no new data is available since then, a `206 - No Content` HTTP response is returned. Date without time part in ISO8601 format.
+      schema:
+        type: string
+        format: date
+        example: "1970-01-13"
     - $ref: '../zoo-api.yaml#/components/parameters/Pretty'
-    - $ref: '../zoo-api.yaml#/components/parameters/RefDateDefaultToday'
     - $ref: '../zoo-api.yaml#/components/parameters/CareGroup'
     - $ref: '../zoo-api.yaml#/components/parameters/Authorization'
   responses:
+    '206':
+      description: |-
+        No new data is available: No new group report has been constructed with a `refDate` newer than `ifNewerThan`.
+    '503':
+      description: The data cannot be provided, because EPD data has not been provided to Zorg op Orde, or ZOO has not had a chance to run the fundus calculations on this data.
+      content:
+        application/json:
+          schema:
+            type: object
+            required:
+              - agb
+              - regionName
+            properties:
+              agb:
+                description: |-
+                  The same AGB as supplied via authentication or the `agb` parameter: The AGB of the care group being queried.
+                $ref: ../schemas/agb.yaml
+              regionName:
+                description: |-
+                  A human readable name describing the care group being queried (The entity whose AGB code is sent as `agb`).
+                type: string
     '200':
       description: All patients where funduscopy status is relevant are returned.
       content:
@@ -71,10 +101,7 @@ get:
               agb:
                 description: |-
                   The same AGB as supplied via authentication or the `agb` parameter: The AGB of the care group being queried.
-                type: integer
-                format: int32
-                minimum: 1
-                maximum: 99999999
+                $ref: ../schemas/agb.yaml
               regionName:
                 description: |-
                   A human readable name describing the care group being queried (The entity whose AGB code is sent as `agb`).
@@ -83,9 +110,8 @@ get:
                 $ref: ../schemas/date.yaml
                 example: '2024-04-01'
                 description: |-
-                  The date used for all calculations: Any time spans are relative to this date, any measurement requirements
-                  as stated in the care group's policies such as 'must be registered every year or cannot be considered' are applied
-                  to this date, anything that occured after this date is ignored.
+                    All fundus calculations for each practice that is part of this group is up to date as of this date.
+                    This date is appropriate to feed to `ifNewerThan` in a future call.
               practices:
                 description: |-
                   One entry for each practice that is part of this care group and participates in at least one funduscopy-related care program.

paths/patient_fundusByPractice.yaml

@@ -42,10 +42,51 @@ get:
       schema:
         type: string
         enum: ['gp', 'specialist', 'unknown', '']
+    - name: ifNewerThan
+      in: query
+      required: false
+      description: |-
+        Useful to check if new data is available relative to an earlier request: Provide the same date as provided in a previous response's `refDate` value.
+        If no new data is available since then, a `206 - No Content` HTTP response is returned. Date without time part in ISO8601 format.
+      schema:
+        type: string
+        format: date
+        example: "1970-01-13"
     - $ref: '../zoo-api.yaml#/components/parameters/Pretty'
-    - $ref: '../zoo-api.yaml#/components/parameters/RefDateDefaultToday'
     - $ref: '../zoo-api.yaml#/components/parameters/Authorization'
   responses:
+    '206':
+      description: |-
+        No new data is available: The EPD has not provided new information since `ifNewerThan`, or Zorg op Orde has not had a chance to rerun the fundus calculations on newly provided EPD data.
+    '503':
+      description: The data cannot be provided, because EPD data has not been provided to Zorg op Orde, or ZOO has not had a chance to run the fundus calculations on this data.
+      content:
+        application/json:
+          schema:
+            type: object
+            required:
+              - practice
+            properties:
+              practice:
+                type: object
+                required:
+                  - agb
+                  - name
+                  - gpis
+                  - refDate
+                properties:
+                  agb:
+                    description: |-
+                      The AGB code of the GP practice whose patients are provided in this object.
+                    $ref: ../schemas/agb.yaml
+                  name:
+                    description: |-
+                      A human readable name describing the GP practice (The entity whose AGB code is sent as `agb`).
+                    type: string
+                  gpis:
+                    $ref: ../schemas/GPIS.yaml
+                  refDate:
+                    $ref: "../schemas/fundus-status.yaml#/properties/refDate"
     '200':
       description: All patients where funduscopy status is relevant is returned.
       content:
@@ -53,18 +94,11 @@ get:
           schema:
             type: object
             required:
-              - refDate
               - practice
+              - refDate
             properties:
               dict:
                 $ref: '../schemas/TermsDictionary.yaml'
-              refDate:
-                $ref: ../schemas/date.yaml
-                description: |-
-                  The date used for all calculations: Any time spans are relative to this date, any measurement requirements
-                  as stated in the care group's policies such as 'must be registered every year or cannot be considered' are applied
-                  to this date, anything that occured after this date is ignored.
-                example: '2024-04-01'
               practice:
                 $ref: "../schemas/fundus-status.yaml"
     '400':

paths/population_frequentUser_patients.yaml

@@ -95,6 +95,8 @@ get:
                   $ref: '../schemas/PatIdentity.yaml#/insurance'
                 patid:
                   $ref: '../schemas/PatIdentity.yaml#/patid'
+                patPubId:
+                  $ref: '../schemas/PatIdentity.yaml#/patPubId'
                 patUnid:
                   $ref: '../schemas/PatIdentity.yaml#/patUnid'
                 feats:

paths/population_statistics_deprived_{neighborhood}.yaml

@@ -62,6 +62,8 @@ get:
                   $ref: '../schemas/PatIdentity.yaml#/insurance'
                 patid:
                   $ref: '../schemas/PatIdentity.yaml#/patid'
+                patPubId:
+                  $ref: '../schemas/PatIdentity.yaml#/patPubId'
                 patUnid:
                   $ref: '../schemas/PatIdentity.yaml#/patUnid'
                 startDate:

paths/qoc_careprogram.yaml

@@ -1,32 +0,0 @@
-get:
-  operationId: carePrograms
-  tags:
-    - Quality of Care
-  summary: All care programs
-  description: |-
-    List all available care programs. Includes all care programs that the user is allowed to enable or preview, i.e. even ones that shouldn't be shown by default.
-  parameters:
-    - $ref: '../zoo-api.yaml#/components/parameters/Authorization'
-  responses:
-    '200':
-      description: |-
-        Care programs are returned.
-        
-        Examples:
-        * <a href="examples/qoc_careprogram.1.json">Example complete response</a>
-        * <a href="examples/qoc_careprogram.ui_example.png">Example UI render (<em>Somewhat outdated</em>)</a>
-      
-      content:
-        application/json:
-          schema:
-            type: object
-            properties:
-              programs:
-                description: The kind of chronic care that this care program caters to. Can be omitted in cases where this care program doesn't cover a generally accepted protocollized chronic care condition (Often, new research).
-                type: array
-                items: 
-                  $ref: '../schemas/CareProgram-enum.yaml'
-    '401':
-      $ref: '../zoo-api.yaml/#/components/responses/NoAuth'
-    '403':
-      $ref: '../zoo-api.yaml/#/components/responses/NoAccess'

paths/qoc_careprograms.yaml

@@ -0,0 +1,30 @@
+get:
+  operationId: carePrograms
+  tags:
+    - Quality of Care
+  summary: Care programs
+  description: Enumerate all care programs (ketens) in which the customer participates.
+  parameters:
+    - $ref: '../zoo-api.yaml#/components/parameters/Authorization'
+  responses:
+    '200':
+      description: Set of care programs (ketens).
+      content:
+        application/json:
+          schema:
+            type: array
+            items:
+              type: object
+              properties:
+                careprogram:
+                  $ref: '../schemas/CareProgram-enum.yaml'
+                name:
+                  description: |-
+                    Title of this careprogram meant for humans. In other words, the same as `careprogram`, but in dutch and conforming to the naming conventions of the care group.
+                    In particular, VVR/HVZ tend to have wildly different names (certain groups call it CVRM, others HVZ, others 'VRM - Hoog risico', and so forth).
+                  type: string
+                  example: VRM – Hoog Risico
+    '401':
+      $ref: '../zoo-api.yaml/#/components/responses/NoAuth'
+    '403':
+      $ref: '../zoo-api.yaml/#/components/responses/NoAccess'

paths/qoc_checkupList_set_status.yaml

@@ -1,7 +1,7 @@
 post:
   tags:
     - Quality of Care
-  operationId: setPatientCallUpStatus
+  operationId: setPatientCallupStatus
   summary: Call-up status
   description: Set call-up status for patients in a care program.
   parameters:
@@ -24,13 +24,23 @@ post:
           properties: 
             careprogram:
               description: |-
-                The kind of chronic care that this care program caters to. Can be omitted in cases where this care program doesn't cover a generally accepted protocollized chronic care condition (Often, new research).
+                The kind of chronic care you want to set the call up status for.
               $ref: '../schemas/CareProgram-enum.yaml'
             callUpStatus:
-              $ref: '../schemas/callUpStatus-enum.yaml'
-            employee:
               type: string
-              description: The employee that is setting the call-up status. Any string is accepted, but it is recommended to use a employee code derived from this API.
+              enum:
+                - byPolicy
+                - callUp
+                - dontCallUp
+                - scheduled
+              example: callUp
+            employee:
+              $ref: ../schemas/employee-alias.yaml
+            quarter:
+              $ref: ../schemas/date.yaml
+              description: |-
+                Callup plans are specific to a single quarter and are returned only when asking for callup lists with this quarter
+                as the `refDate`. Defaults to 'next quarter' (i.e. on April 5th, would default to July 1st).
             bsns:
               type: array
               items:
@@ -55,7 +65,7 @@ post:
   responses:
     '200':
       description: |-
-        BSNs or patIds whose status has actually updated. BSNs or patIds which were not known in the HIS are ignored and not returned here.
+        BSNs or patIds whose status has actually updated. BSNs or patIds which were not known in the GPIS are ignored and not returned here.
         The caller should determine the difference between the two sets to get the ignored patients. If a BSN matched more than one patient, all these patients were updated.
       content: 
         'application/json':

paths/qoc_checkupList_{setKey}.yaml

@@ -1,10 +1,35 @@
 get:
-  operationId: checkUpListSet
+  operationId: callupList
   tags:
     - Quality of Care
   summary: Call-up status
   description: |-
-    Load call-up status for patients in a care program. Returns each patient in a care program along with the progress on required or suggested measurements indicated for this care program.
+    Load call-up status for patients in a care program.
+    
+    Returns each patient in a care program along with the progress on required or suggested measurements indicated for this care program.
+    Also includes any custom callup policies as part of the response, and the callup plan for this quarter.
+    
+    Every quarter, each patient is assigned a callup plan for just that quarter (it resets for every quarter). A callup plan
+    is either 'call them up' or 'do not call them up'. Most patients start off in an 'open' state where no decision on whether
+    to call them up has been made yet.
+    
+    Callup policies are different: They aren't per quarter; instead they represent medical decisions that impact their chronic
+    care. For example, 'this patient is not available for checkups until next year', or 'this patient is an amputee; do not
+    consider a missing analysis of the feet as relevant'. They can have an explicitly chosen end date.
+    
+    Call up plans have a default. Usually it is 'open' (no decision yet made on whether to call them up this quarter or not),
+    but explicitly set policies as well as implicit policies chosen by the care group can affect this. For example, if a
+    policy is set that the patient is not available for a few quarters, the plan defaults to 'do not call up' instead.
+    
+    To enable making clear to the user via the UI exactly what choices have been made, the API services differentiates between
+    what the default behaviour of a plan is; this is called the `byPolicy` plan - versus what the user explicitly chose.
+    
+    In other words, a patient that defaults to 'do not call up' can be differentiated from a patient where an explicit choice
+    was made to set their callup plan for the quarter to 'do not call up'. A patient that has defaulted to 'do not call up' can
+    have that value change when the policies change; a patient that was explicitly set to 'do not call up' will not change the
+    plan even if underlying policies change.
+    
+    Policies are set vie the `/qoc/callupPolicy` endpoint.
   parameters:
     - name: setKey
       in: path
@@ -24,7 +49,7 @@ get:
       in: query
       description: |-
         Restricts the patient list to those born in the specified month and those with no birthdate (rare case). The list of gp's is limited to those who are responsible to the patients in the restricted list. The initial calculation of the call-up list is not affected by the parameter.
-
+        
         If the parameter is omitted or specified outside its boundaries, then all patients are returned.
       required: false
       schema:
@@ -89,6 +114,7 @@ get:
                       format: int32
                       minimum: 1
                       maximum: 99999999
+                      example: 1099999
                   required:
                     - name
               indicators:
@@ -103,43 +129,97 @@ get:
                         The title of this indicator
                       type: string
                       example: Bloeddruk
+                    key:
+                      description: Unique identifier, not to be shown to the user, for referring to this indicator in other API calls
+                      type: string
+                      example: ZEL-dm2-bp-result
                     optional:
                       description: |-
                         If present, this indicator is optional, and the value contains dutch human readable text explaining why.
                       type: string
                       example: Volgens HKN protocol is BMI meten optioneel bij Astma patiënten; echter stelt het protocol wel een relatie tussen overgewicht en de mate van klachten.
+                    focus:
+                      description: |-
+                        Caregroups can choose key performance indicators; such indicators are considered 'focus' indicators.
+                        Focus indicators tend to be temporary; most caregroups adjust them yearly or every other year.
+                      type: boolean
+                      example: false
                   required:
                     - title
+                    - key
+                    - focus
               patients:
                 type: array
                 items:
                   type: object
                   properties:
-                    patid:
-                      $ref: '../schemas/PatIdentity.yaml#/patid'
+                    patPubId:
+                      $ref: '../schemas/PatIdentity.yaml#/patPubId'
+                    patUnid:
+                      $ref: '../schemas/PatIdentity.yaml#/patUnid'
                     doctor:
                       type: integer
                       format: int32
                       description: |-
                         An index (0-based) into the `doctors` entry: This is the GP responsible for this patient.
+                    chosenStatus:
+                      type: string
+                      description: |-
+                        The callup plan explicitly chosen via an earlier call to the `/qoc/callupList/setStatus` endpoint.
+
+                        The chosen status always defaults to `byPolicy` which indicates that the actual status will be derived
+                        by analysing explicit and implicit policies. This 'by policy' status is provided via `byPolicyStatus`.
+                      enum:
+                        - byPolicy
+                        - callUp
+                        - dontCallUp
+                        - scheduled
+                      example: byPolicy
+                    byPolicyStatus:
+                      type: string
+                      description: |-
+                        The callup plan that applies if no explicit choice is made (i.e. the default choice - `byPolicy`).
+
+                        This status is derived by analysing the care group's policies as well as any explicit policies set
+                        via the `/qoc/callupPolicy` endpoint.
+
+                        `open` means: Whether to call this patient up this quarter hasn't been decided yet, and the policies
+                        do not suggest either choice as a default.
+                      enum:
+                        - open
+                        - callUp
+                        - dontCallUp
                     status:
-                      $ref: '../schemas/callUpStatus-enum.yaml'
+                      type: string
+                      description: |-
+                        Provided by convenience: It's the value of `chosenStatus`, unless that is `byPolicy`, in which case
+                        it is the value of `byPolicyStatus`. In other words, the status that applies to this patient.
+                      enum:
+                        - open
+                        - callUp
+                        - dontCallUp
+                        - scheduled
+                      example: open
                     address1:
                       type: string
                       description: |-
                         The first line of this patient's postal address (Street name and number, generally).
+                      example: Dorpsstraat 1
                     city:
                       type: string
                       description: Patient lives in this city or township.
+                      example: Nowhereville
                     postcode:
                       type: string
                       description: Postcode of the patient.
+                      example: 1234AA
                     bsn:
                       type: integer
                       minimum: 1
                       maximum: 999999999
                       format: int32
                       description: The BSN (dutch social security number) of the patient.
+                      example: 123456789
                     dob:
                       $ref: ../schemas/date.yaml
                       description: Date of birth of the patient.
@@ -147,6 +227,7 @@ get:
                       type: string
                       format: email
                       description: Email address of the patient.
+                      example: foo@bar.fake
                     state:
                       type: string
                       description: |-
@@ -161,9 +242,69 @@ get:
                         * `2`-`8` – `2` is like `1`, except the measurement lasts for 2 quarters up to 8 quarters.
                         * `+` – The measurement lasts for 9 or more quarters (for example, the measurement only needs to be done once ever and it has been done).
                         * `x` – unknown situation (should not occur).
+                      example: 0017-R-0
+                    policies:
+                      type: array
+                      description: |-
+                        Lists all explicitly chosen policies (set via `qoc/callupPolicy`) that apply to this
+                        patient.
+                      items:
+                        type: object
+                        properties:
+                          'type':
+                            type: string
+                            enum:
+                              - PatientIndicator
+                              - PatientSnoozed
+                            description: |-
+                              The kind of policy this is.
+
+                              `PatientSnoozed` indicates the patient is not available for a limited period of time and thus isn't a candidate for calling up.
+
+                              `PatientIndicator` indicates an alternate frequency has been chosen for a specific indicator for this specific patient.
+                            example: PatientIndicator
+                          indicatorKey:
+                            type: string
+                            description: |-
+                              Only set for `PatientIndicator`. Which indicator has a custom frequency.
+                            example: ZEL-dm2-bp-result
+                          expires:
+                            type: string
+                            $ref: ../schemas/date.yaml
+                            description: Date in ISO8601 format; if omitted does not expire. It is considered expired _on_ the stated date.
+                          frequency:
+                            type: string
+                            description: |-
+                              For type `PatientIndicator` only (otherwise, not sent). Indicates that this indicator should be measured
+                              with a different frequency than what this care program by default suggests. The letter for this indicator in the `state` string
+                              takes this alternate frequency into account (or, is rendered as a `-`, indicating 'not relevant', if `never` is the custom frequency).
+                            enum:
+                              - quarter
+                              - sixMonths
+                              - year
+                              - twoYear
+                              - threeYear
+                              - fiveYear
+                              - never
+                            example: sixMonths
+                          reason:
+                            type: string
+                            description: |-
+                              A reason for a policy can be provided when it is set, and is returned here. Omitted if not provided. 
+                            example: Jannie zit tot eind december op een boorplatform.
+                          employee:
+                            $ref: ../schemas/employee-string.yaml
+                          timestamp:
+                            type: string
+                            description: The policy was created (set) at this time.
+                            $ref: ../schemas/dateTimeZ.yaml
+                        required:
+                          - type
                   required:
-                    - patid
+                    - patUnid
                     - doctor
+                    - byPolicyStatus
+                    - chosenStatus
                     - status
                     - dob
                     - state

paths/qoc_checkupPolicy.yaml

@@ -0,0 +1,153 @@
+get:
+  tags:
+    - Quality of Care
+  operationId: getCallupPolicy
+  summary: Call-up policy
+  description: Gets all call-up policies of a patient for all indicators in which the patient participates, or for a specific indicator. Parameters are optional and simply filter the response; in other words, without parameters all policies are returned.
+  parameters:
+    - name: policyType
+      in: query
+      schema:
+        $ref: ../schemas/CallupPolicyType-enum-short.yaml
+    - name: patUnid
+      in: query
+      schema:
+        $ref: ../schemas/pat-patUnid.yaml
+        description: Show only policies for patients that match this unid. Not allowed if asking for `UserIndicator`.
+    - name: bsn
+      in: query
+      schema: 
+        $ref: ../schemas/pat-BSN.yaml
+        description: Show only policies for patients that match this bsn. Not allowed if asking for `UserIndicator`.
+    - name: indicatorKey
+      in: query
+      description: The version suffix of the indicator is ignored. Only for type `UserIndicator` and `PatientIndicator`.
+      schema:
+        type: string
+        example: ZOO-dm2-hb-1
+    - name: refDate
+      in: query
+      description: Return only policies that haven't expired at this date. Defaults to 'next quarter').
+      schema:
+        type: string
+        $ref: ../schemas/date.yaml
+  responses:
+    '200':
+      description: All policies that match the supplied filter conditions.
+      content:
+        'application/json':
+          schema:
+            type: array
+            items: 
+              type: object
+              properties:
+                policyType: 
+                  $ref: ../schemas/CallupPolicyType-enum-short.yaml
+                patUnid:
+                  $ref: ../schemas/pat-patUnid.yaml
+                indicatorKey:
+                  type: string
+                  example: ZOO-dm2-hb
+                userId:
+                  type: integer
+                  example: 123456
+                expires:
+                  $ref: ../schemas/date.yaml
+                  example: "2026-04-01"
+                frequency:
+                  $ref: ../schemas/CallupPolicyFrequency.yaml
+                  example: never
+                reason:
+                  type: string
+                  example: Zit op een boorplatform.
+                employee:
+                  $ref: ../schemas/employee-string.yaml
+                timestamp:
+                  $ref: ../schemas/dateTime.yaml
+    '401':
+      $ref: '../zoo-api.yaml#/components/responses/NoAuth'
+    '403':
+      $ref: '../zoo-api.yaml#/components/responses/NoAccess'
+post: 
+  tags:
+    - Quality of Care
+  operationId: postCallupPolicy
+  summary: Call-up policy
+  description: |-
+    Set a call-up policy. Policies last until a specific expiry (or forever). See the descriptions of policy types to get an idea of what policies do and what they represent.
+  requestBody:
+    content: 
+      'application/json':
+        schema: 
+          type: object
+          properties:
+            policyType:
+              $ref: ../schemas/CallupPolicyType-enum-full.yaml
+            patUnid:
+              $ref: ../schemas/pat-patUnid.yaml
+              example: 123456
+            bsn:
+              $ref: ../schemas/pat-BSN.yaml
+            indicatorKey:
+              description: |-
+                The key of the indicator as listed in the indicator set. The version of the indicator is ignored (if the string ends in a dash and a number, those are stripped). Only relevant for `IndicatorUser` and `UserIndicator`.
+              example: ZOO-dm2-hb-3
+              type: string
+            reason:
+              type: string
+              description: An optional human written reason for why the policy is being applied.
+              example: Zit op een boorplatform.
+            expires:
+              description: |-
+                If provided, this policy does not apply on and after this date. Mandatory for certain types of policy.
+              $ref: ../schemas/date.yaml
+            frequency:
+              $ref: ../schemas/CallupPolicyFrequency.yaml
+            employee:
+              $ref: ../schemas/employee-string.yaml
+          required:
+            - policyType
+            - employee
+  responses:
+    '204':
+      description: If the policy has been processed without any errors.
+    '401':
+      $ref: '../zoo-api.yaml/#/components/responses/NoAuth'
+    '403':
+      $ref: '../zoo-api.yaml#/components/responses/NoAccess'
+delete:
+  tags:
+    - Quality of Care
+  operationId: deleteCallupPolicy
+  summary: Call-up policy
+  description: Unset a call-up policy.
+  parameters:
+    - name: policyType
+      in: query
+      schema:
+        $ref: ../schemas/CallupPolicyType-enum-short.yaml
+    - name: patUnid
+      in: query
+      schema:
+        $ref: ../schemas/pat-patUnid.yaml
+        example: 123456
+    - name: bsn
+      in: query
+      schema:
+        $ref: ../schemas/pat-BSN.yaml
+    - name: indicatorKey
+      in: query
+      description: The version suffix of the indicator is ignored (if any). Only relevant for `IndicatorUser` and `UserIndicator`.
+      schema:
+        type: string
+        example: ZOO-dm2-hb-1
+    - name: reason
+      in: query
+      description: Some random string describing the reason. May be omitted.
+      schema:
+        type: string
+    - name: employee
+      description: Employee who withdraws the policy for the patient and indicator combination.
+      in: query
+      schema:
+        $ref: ../schemas/employee-string.yaml

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

@@ -3,7 +3,7 @@ get:
   tags:
     - Quality of Care
   summary: Indicator, practice details
-  description: Show per-practice details for each practice in a group for a specific indicator
+  description: Show per-practice details for each practice in a group for a specific indicator.
   parameters:
     - name: setKey
       in: path
@@ -14,7 +14,7 @@ get:
       example: ZEL-dm
     - name: indicatorKey
       in: path
-      description: The key as listed in the indicatorset.
+      description: The key as listed in the indicator set.
       required: true
       schema:
         type: string

paths/qoc_indicatorset_{setKey}.yaml

@@ -2,12 +2,14 @@ get:
   operationId: indicatorSet
   tags:
     - Quality of Care
-  summary: Indicator report
-  description: Load an indicator-based report.
+  summary: Indicator set
+  description: |-
+    Provides indicators for a care program. An indicator set holds all indicators for a combination of a care program, reference date and a customer.
+    Care groups and practices see different output. The authorisation for the care group to access care program data is taken in account.
   parameters:
     - name: setKey
       in: path
-      description: The key as listed in the `CareProgram` schema.
+      description: The key as listed in the [/qoc/careprogram](#tag/Quality-of-Care/operation/carePrograms) response.
       required: true
       schema:
         type: string
@@ -15,7 +17,7 @@ get:
     - 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`.
+        The date in `2023-04-01` format; defaults to the sensible date for the indicator set you query, which is generally the first day of either this quarter, or the next quarter.
       required: false
       schema:
         $ref: ../schemas/date.yaml
@@ -39,4 +41,3 @@ get:
       $ref: '../zoo-api.yaml#/components/responses/NoAccess'
     '404':
       description: The provided `setKey` doesn't refer to a valid program.
-

paths/qoc_indicatorsets.yaml

@@ -0,0 +1,88 @@
+get:
+  operationId: indicatorSets
+  tags:
+    - Quality of Care
+  summary: Indicator sets
+  description: |-
+    List all available indicator sets. Includes all sets that the user is allowed to enable or preview, i.e. even ones that shouldn't be shown by default.
+
+    This endpoint is also reachable using URL `/qoc/careprogram`, but that endpoint is deprecated.
+  parameters:
+    - name: carePrograms
+      in: query
+      description: |-
+        A comma separated list of care program types, for example `DM,COPD`. The response is limited to the specified care programs.
+      schema:
+        type: array
+        items:
+          $ref: '../schemas/CareProgram-enum.yaml'
+    - $ref: '../zoo-api.yaml#/components/parameters/Authorization'
+  responses:
+    '200':
+      description: |-
+        Indicator sets are returned.
+        
+        Examples:
+        * <a href="examples/qoc_indicatorsets.1.json">Example complete response</a>
+        * <a href="examples/qoc_indicatorsets.ui_example.png">Example UI render (somewhat outdated)</a>
+      links:
+        GetIndicatorSet:
+          operationId: indicatorSet
+          parameters:
+            setKey: $response.body#/key
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              indicatorsets:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    key:
+                      type: string
+                      description: Key of the indicator set or casefinder.
+                    name:
+                      type: string
+                      description: |-
+                        Something like `DM (Calisota)` – describes the careprogram itself (and not the purpose of this indicatorset - see `subName` for that).
+                    subName:
+                      type: string
+                      description: |-
+                        Something like `Oproepen` or `Rapportage 75+` – describes the purpose of this indicatorset; a number of sets all with the same name but with different subNames can exist, representing different views and protocol approaches to the same care program. Omitted if not relevant (in that case `name` describes this set/casefinder fully).
+                    description:
+                      type: string
+                      description: A longer description in dutch describing e.g. the chronic care condition covered by this set.
+                    tags:
+                      type: array
+                      description: A list of simple short dutch strings describing properties of this set.
+                    defaultShow:
+                      type: boolean
+                    favState:
+                      type: string
+                      description: Always "X".
+                      example: X
+                    'type':
+                      type: string
+                      description: Either "indicatorset" or "casefinding".
+                      example: indicatorset
+                    careprogram:
+                      $ref: '../schemas/CareProgram-enum.yaml'
+                      description: The kind of chronic care that this care program caters to. Can be omitted in cases where this care program doesn't cover a generally accepted protocolized chronic care condition. That is often the case with new research projects.
+                    future:
+                      type: boolean
+                      description: |-
+                        This set is a sneak peek; it is not (yet) the official guideline, and is still being evaluated.
+                    callup:
+                      type: boolean
+                      description: |-
+                        If this 'flavour' (as per `subName`) is intended to be used to call up patients and look to the future (this will be `true`) or if this set's intent is reporting and introspection, looking to the past (this will be `false`).
+                    url:
+                      type: string
+                      description: |-
+                        Only provided for type "casefinder". Casefinders are not available via the API; redirect the user to this URL.
+    '401':
+      $ref: '../zoo-api.yaml/#/components/responses/NoAuth'
+    '403':
+      $ref: '../zoo-api.yaml/#/components/responses/NoAccess'

schemas/CallUpStatus-enum.yaml

@@ -1,6 +0,0 @@
-type: string
-enum:
-  - open
-  - callUp
-  - dontCallUp
-  - scheduled

schemas/CallupPolicyFrequency.yaml

@@ -0,0 +1,12 @@
+description: |-
+  The stated patient should have the stated indicator checked with this frequency instead of the standard frequency as per the care protocol for this care program. The callup state is modified accordingly, except for the special value of `never` which means te callup state is reported as `-` ('not relevant for this patient').
+type: string
+enum:
+  - quarter
+  - sixMonths
+  - year
+  - twoYear
+  - threeYear
+  - fiveYear
+  - never
+example: never

schemas/CallupPolicyType-enum-full.yaml

@@ -0,0 +1,26 @@
+description: |-
+  Call-up policies type. Various types are supported:
+  
+  <dl>
+  <dt><code>PatientIndicator</code></dt>
+  <dd>A policy that applies to a specific patient for a specific indicator. For example, a policy might capture the notion "This patient is an amputee and therefore, the frequency of doing foot inspections for chronic diabetes care should be 'never', forever". Or "This patient is going to receive an eye operation next year, therefore funduscopy is not useful, and the specialist team managing their eye care is responsible for it until after the operation and its recovery. Frequency set to 'never', until 2026-08-01". Such policies always refer to a specific patient and a specific indicator, may or may not have an expiry date, and always have a custom frequency.
+  
+  The effect of this policy is to modify the 'callup state' for that patient/indicator combination. For example, the amputee would receive a `-` state for 'foot inspection' (indicating: Foot inspection is not relevant for this patient) instead of a `0` (indicating: Foot inspection must be done this quarter). Naturally, any policy that expires _before_ the `refDate` of a callup list you're asking for doesn't apply.</dd>
+  
+  <dt><code>PatientSnoozed</code></dt>
+  <dd>A policy that applies to a specific patient for a certain care program type (e.g. `COPD`), and indicates that providing chronic care at the GP level is not possible for a limited time. For longer 'snoozing' the advice is generally to set the GPIS based registration of chronic care participation (i.e. the value 'COKZ' (COPD chronic care participation) to 'No'), but when the situation is temporary and a medical operator knows when the situation ends, this policy can be used instead, which has the advantage of restoring the patient to chronic care reporting automatically when the policy is expires. `expiry` is mandatory for this type of policy.
+  
+  The effect of this policy is to default the patient's call up plan (the `chosenStatus` is `byPolicy`) to `doNotCallup` until the policy expires.</dd>
+  
+  <dt><code>UserIndicator</code><dt>
+  <dd>WARNING: Not current available (not implemented yet).
+  
+  This policy applies to a specific indicator, for all patients. Can be used to represent "our ECG machine is broken until 2025-10-01" for example, or "providing flu injections is done by a different team than DM chronic care therefore this indicator does not apply to me".
+  
+  The effect of this policy is to mark it as 'not relevant' for all patients. It is not possible to configure an alternate frequency; that would be a modification of the protocol itself which can be implemented by contacting Zorg op Orde to discuss a customised protocol.
+type: string
+enum:
+  - PatientIndicator
+  - PatientOnly
+  - IndicatorUser
+example: PatientIndicator

schemas/CallupPolicyType-enum-short.yaml

@@ -0,0 +1,6 @@
+type: string
+enum:
+  - PatientIndicator
+  - PatientOnly
+  - IndicatorUser
+example: PatientIndicator

schemas/CallupPolicyType-enum.yaml

@@ -0,0 +1,7 @@
+description: |-
+  Call-up policy to deviate from the default call-up schema used for patients and/or indicators. A `PatientIndicator` policy allows the practice to set a call-up policy on an indicator limited to a certain patient. `PatientOnly` is a policy for all indicators the patient is involved in. `IndicatorUser` is a policy for a specific indicator, but this policy applies only for a specific practice user (assistant, doctor, etc.).
+type: string
+enum:
+  - PatientIndicator
+  - PatientOnly
+  - IndicatorUser

schemas/CareProgram-enum.yaml

@@ -17,6 +17,7 @@ description: |-
   <dt>Dermatoscopie</dt><dd>Dermatoscopy / (risk of) skin cancer</dd>
   <dt>FractuurPreventie</dt><dd>Fracture prevention - often part of elderly care.</dd>
   <dt>GecMonitoring</dt><dd>An assortment of indicators useful for monitoring a GEC (Geïntegreerd Eerstelijns Centrum / integrated primary care).</dd>
+  <dt>Nierschade</dt><dd>(risk of) kidney failure</dd>
   </dl>
 type: string
 example: COPD

schemas/GPIS.yaml

@@ -1,11 +1,9 @@
 description: |-
-  The source of the medical data used to produce this report: which general practitioner information system was used, and when the data was provided. Omitted if no HIS database was imported (yet).
+  The source of the medical data used to produce this report: which general practitioner information system was used, and when the data was provided. Omitted if no GPIS database was imported (yet).
 type: object
 properties:
   gpisType:
-    description: The type of GP Information System
-    type: string
-    example: Tetrapod
+    $ref: gpisType.yaml
   timestamp:
     description: |-
       The report is based on dossier data as it was on this timestamp; due to inaccuracies by GP information systems that source the data,

schemas/Indicator.yaml

@@ -20,6 +20,20 @@ properties:
     description: Short, in dutch, plain text.
     type: string
     example: Prevalentie Diabetes
+  focus:
+    description: |-
+      Caregroups can choose key performance indicators; such indicators are considered 'focus' indicators.
+      Focus indicators tend to be temporary; most caregroups adjust them yearly or every other year.
+    type: boolean
+    example: false
+  htmlDescription:
+    description: In dutch, HTML formatted; if present, contains details on how this value is measured (in more readable, less technical terms than `htmlDetail`.
+    type: string
+    example: Patiënten met ≥ 1 voorschrift(en) long acting beta-2 agonists (LABA) of long acting muscarine antagonists (LAMA) in de afgelopen 12 maanden
+  htmlDetail:
+    description: In dutch, HTML formatted; if present, contains specific details on how this value is measured (for example, contains information about which NHG bepaling codes are used).
+    type: string
+    example: LAMA (<code>R03BB</code> (04, 05, 06 of 07)) of LABA (<code>R03AC</code> (12, 13, 18 of 19))
   type:
     description: |-
       What kind of indicator this is.
@@ -173,6 +187,9 @@ properties:
       required:
         - segments
       properties:
+        calculated:
+          description: The timestamp on which the bar was calculated. This can be different from the reference date. Mainly for debugging purposes.
+          $ref: ../schemas/dateTime.yaml
         legend:
           description: |-
             *OPTIONAL* A short *HTML* (dutch) description of the entity+measurement date represented by this bar.
@@ -180,6 +197,12 @@ properties:
           type: string
           example: Praktijk 2023Q3
           default: ''
+        pop:
+          description: |-
+            A number representing the total population that this indicator has calculated against; can have decimal values if this
+            indicatorset represents a group average.
+          type: number
+          example: 854.0
         segments:
           type: array
           items:

schemas/IndicatorDetail.yaml

@@ -15,12 +15,11 @@ properties:
   refDate:
     $ref: 'IndicatorSet.yaml#/properties/refDate'
   htmlDescription:
-    description: A more detailed description of what this indicator calculates. *HTML*
-    type: string
+    $ref: 'Indicator.yaml#/properties/htmlDescription'
   htmlDescriptionDetail:
-    description: |-
-      *OPTIONAL* A description of which exact formulas and codes are checked to calculate this indicator. *HTML*.
-    type: string
+    $ref: 'Indicator.yaml#/properties/htmlDetail'
+  focus:
+    $ref: 'Indicator.yaml#/properties/focus'
   blocks:
     description: |-
       A block describes one particular outcome (such as 'patients with conflicting registration').

schemas/IndicatorParticipants.yaml

@@ -18,6 +18,8 @@ properties:
     $ref: 'IndicatorDetail.yaml#/properties/htmlDescription'
   htmlDescriptionDetail:
     $ref: 'IndicatorDetail.yaml#/properties/htmlDescriptionDetail'
+  focus:
+    $ref: 'Indicator.yaml#/properties/focus'
   xMin:
     $ref: 'Indicator.yaml#/properties/xMin'
   xMax:
@@ -91,6 +93,11 @@ properties:
         - amplitude
         - population
         - values
+  cache:
+    type: boolean
+    description: |- 
+      If true, the indicator was retrieved from the API cache. The indicator is only retrieved from the cache if there is no recent calculation available in the database and if the indicator won't change anymore. This is the case when it was calculated with a reference date in the past and for which a certain period no new GPIS-data is provided. The cached indicator reflects the indicator definition on the reference date. A cached indicator is not updated when the definition changes.
+    example: true
 required:
   - group
   - key

schemas/IndicatorSet.yaml

@@ -1,5 +1,5 @@
 description: |-
-  A report about a care program based on showing a number of ratios, such as 'how many people in your practice have diabetes', or 'for all diabetes patients in your care with a recent blood pressure measurement, how do these blood pressure measurements split into "problematic" / "concern" / "okay" categories
+  A report about a care program based on showing a number of ratios, such as: "How many people in your practice have diabetes?", or: "For all diabetes patients in your care with a recent blood pressure measurement, how do these blood pressure measurements split into problematic / concern / okay categories?"
 type: object
 required:
   - key
@@ -20,7 +20,7 @@ properties:
   careprogram:
     $ref: '../schemas/CareProgram-enum.yaml'
   refDate:
-    description: 'All calculations are done based on this date (dutch: _peildatum_).'
+    description: Reference date for which the indicators are calculated on the population (peildatum).
     $ref: ./date.yaml
   calculating:
     description: |-
@@ -30,6 +30,45 @@ properties:
     format: number
     minimum: 0.0
     maximum: 1.0
+  bars:
+    description: Describes the bars in the indicators used in the indicatorGroups.
+    type: array
+    items:
+      type: object
+      properties:
+        calculated:
+          type: object
+          properties:
+            from:
+              description: Timestamp of the oldest indicator calculation in the set.
+              $ref: ../schemas/dateTime.yaml
+            to:
+              description: Timestamp of the newest indicator calculation in the set.
+              $ref: ../schemas/dateTime.yaml
+        population:
+          type: object
+          properties:
+            entity:
+              type: string
+              enum:
+                - gp
+                - tag
+            tag:
+              description: The name of a care group or other population, but never a practice.
+              type: string
+            unid:
+              description: For internal use by Zoo.
+              type: integer
+            snapshotId:
+              description: For internal use by Zoo.
+              type: integer
+        refDate:
+          description: |-
+            Reference date for which the indicators are calculated on the population.
+          $ref: '../schemas/dateTime.yaml'
+        title:
+          description: Title for use in the GUI as a legend for bar.
+          type: string
   chapters:
     description: |-
         Each chapter has a title and contains 1 or more indicators.
@@ -44,14 +83,6 @@ properties:
           description: In dutch, plain text formatted; should fit on one line.
           type: string
           example: Populatie
-        htmlDescription:
-          description: In dutch, HTML formatted; if present, contains details on how this value is measured (in more readable, less technical terms than `htmlDetail`.
-          type: string
-          example: Patiënten met ≥ 1 voorschrift(en) long acting beta-2 agonists (LABA) of long acting muscarine antagonists (LAMA) in de afgelopen 12 maanden
-        htmlDetail:
-          description: In dutch, HTML formatted; if present, contains specific details on how this value is measured (for example, contains information about which NHG bepaling codes are used).
-          type: string
-          example: LAMA (<code>R03BB</code> (04, 05, 06 of 07)) of LABA (<code>R03AC</code> (12, 13, 18 of 19))
         indicatorGroups:
           description: |-
             A chapter contains 1 or more indicator groups. An indicator group is an array of indicators which should
@@ -62,3 +93,6 @@ properties:
             type: array
             items:
               $ref: 'Indicator.yaml'
+  cache:
+    description: If true, the indicator set was retrieved from the API cache. The set is only retrieved from the cache if there is no recent calculation available in the database and if the set won't change anymore. This is the case for all indicator sets which were calculated with a reference date in the past and for which a certain period no new GPIS-data is provided. The cached indicator set reflects the indicator definitions of the reference date. Cached indicators are not updated with new definitions.
+    type: boolean

schemas/PatIdentity.yaml

@@ -110,6 +110,8 @@ insurance:
       $ref: 'insurer-Uzovi.yaml'
 patid:
   $ref: 'pat-patId.yaml'
+patPubId:
+  $ref: 'pat-patPubId.yaml'
 patUnid:
   $ref: 'pat-patUnid.yaml'
 startDate:

schemas/dateTimeZ.yaml

@@ -0,0 +1,4 @@
+description: Timestamp in complete basic representation of date and time according ISO 8601.
+type: string
+format: datetime
+example: "19700131T235901Z"

schemas/employee-string.yaml

@@ -0,0 +1,3 @@
+type: string
+description: A string that identifies the employee who is setting this policy.
+example: Mien Dobbelsteen

schemas/fundus-status.yaml

@@ -3,6 +3,7 @@ required:
   - agb
   - name
   - gpis
+  - refDate
   - patients
 properties:
   agb:
@@ -15,6 +16,14 @@ properties:
     type: string
   gpis:
     $ref: 'GPIS.yaml'
+  refDate:
+    $ref: ../schemas/date.yaml
+    description: |-
+      The date used for all calculations: Any time spans are relative to this date, any measurement requirements
+      as stated in the care group's policies such as 'must be registered every year or cannot be considered' are applied
+      to this date, anything that occured after this date is ignored. The date depends on the last time the EPD system provided
+      data; generally it will be quite recent.
+      example: '2024-04-01'
   patients:
     type: array
     items:
@@ -49,6 +58,8 @@ properties:
           $ref: 'PatIdentity.yaml#/insurance'
         patid:
           $ref: 'PatIdentity.yaml#/patid'
+        patPubId:
+          $ref: 'PatIdentity.yaml#/patPubId'
         patUnid:
           $ref: 'PatIdentity.yaml#/patUnid'
         startDate:

schemas/gpisType.yaml

@@ -0,0 +1,13 @@
+type: string
+description: |-
+  Type brand (or type) of the general practitioner information system (EDP). Query the `/customer/gpisType` end point for a list of all brands.
+enum:
+  - healthconnected
+  - medicom
+  - scipio
+  - microhis
+  - promedico
+  - tetra
+  - sanday
+  - microhis
+  - medikit

schemas/pat-DOB.yaml

@@ -2,6 +2,7 @@ description: |-
   Patient's date of birth.
   
   Note that by convention, patients whose birthdate is unknown (rare, but can happen in certain asylum seeker cases)
-  pick a date and tend to pick either `xxxx-01-01` or `xxxx-07-01`. Can, in rare cases, be unavailable - if birth date is not known.
+  pick a date and tend to pick either `xxxx-01-01` or `xxxx-07-01`.
+  Can, in rare cases, be unavailable - if birth date is not known; in that case, `null` is sent.
 $ref: ./date.yaml
 

schemas/pat-patId.yaml

@@ -1,4 +1,8 @@
 description: |-
+  _DEPRECATED_ this value will be removed in some future version and you should no longer
+  rely on it. Some GPIS use non-numeric public IDs. Use value `patPubId` instead which is like
+  this one, except a string instead of a number.
+  
   Patient's "public" ID, as used and shown on the GPIS patient page. Not necessarily unique,
   and not necessarily present; 0 indicates no patid is known or this GPIS does not use (numeric)
   public IDs.

schemas/pat-patPubId.yaml

@@ -0,0 +1,11 @@
+description: |-
+  Patient's "public" ID, as used and shown on the GPIS patient page. Not necessarily unique,
+  and not necessarily present; 0 indicates no patid is known or this GPIS does not use public IDs.
+  
+  The primary purpose of this field is to show it to medical professionals working at this practice
+  who can use it to search for this dossier and is a way to communicate without sharing privacy-sensitive
+  details.
+  
+  If this isn't present, the value in `patUnid` is the public ID (i.e. there is no difference).
+type: string
+example: P000123

schemas/pat-patUnid.yaml

@@ -1,6 +1,6 @@
 description: |-
-  Patient's unique and persistent ID in GPIS. Usually identical to `patid` but certain HISes may
+  Patient's unique and persistent ID in GPIS. Usually identical to `patPubId` but certain GPISes may
   use UUID, or has globally unique keys (e.g. very large numbers). Can be blank, but only
   if supplying GPIS does not send them.
 type: string
-example: 1234
+example: "1234"

zoo-api.yaml

@@ -41,14 +41,16 @@ tags:
 
       As well as a 'config' view where they see _all_ care programs that could possibly be relevant for that customer, where the customer can preview the report (essentially, run the report as normal), favourite something they don't get by default, or unfavourite something they get by default.
   - name: Customer management
-  - name: Exports
+  - name: GPIS exports
     description: |-
-      List and download exported parts of HIS dossiers.
+      List and download exported parts of GPIS dossiers.
 paths:
   /patient/dossier:
     $ref: 'paths/patient_dossier.yaml'
   /patient/base:
     $ref: 'paths/patient_base.yaml'
+  /patient/contactList:
+    $ref: 'paths/patient_contactList.yaml'
   /patient/fundusByGroup:
     $ref: 'paths/patient_fundusByGroup.yaml'
   /patient/fundusByPractice:
@@ -60,7 +62,7 @@ paths:
   /population/statistics/deprivedNeighborhood:
     $ref: 'paths/population_statistics_deprived.yaml'
   /population/statistics/deprivedNeighborhood/{neighborhood}:
-      $ref: 'paths/population_statistics_deprived_{neighborhood}.yaml'
+    $ref: 'paths/population_statistics_deprived_{neighborhood}.yaml'
   /population/statistics/employeeFeat:
     $ref: 'paths/population_statistics_employeeFeat.yaml'
   /population/frequentUser/count:
@@ -69,18 +71,22 @@ paths:
     $ref: 'paths/population_frequentUser_patients.yaml'
   /population/frequentUser/patient:
     $ref: 'paths/population_frequentUser_patient.yaml'
-  /qoc/careprogram:
-    $ref: 'paths/qoc_careprogram.yaml'
-  /qoc/checkupList/{setKey}:
-    $ref: 'paths/qoc_checkupList_{setKey}.yaml'
-  /qoc/checkupList/setStatus:
-    $ref: 'paths/qoc_checkupList_set_status.yaml'
+  /qoc/careprograms:
+    $ref: 'paths/qoc_careprograms.yaml'
+  /qoc/indicatorsets:
+    $ref: 'paths/qoc_indicatorsets.yaml'
   /qoc/indicatorset/{setKey}:
     $ref: 'paths/qoc_indicatorset_{setKey}.yaml'
   /qoc/indicator/{setKey}/{indicatorKey}/patients:
     $ref: 'paths/qoc_indicator_{setKey}_{indicatorKey}_patients.yaml'
   /qoc/indicator/{setKey}/{indicatorKey}/participants:
     $ref: 'paths/qoc_indicator_{setKey}_{indicatorKey}_participants.yaml'
+  /qoc/callupList/{setKey}:
+    $ref: 'paths/qoc_checkupList_{setKey}.yaml'
+  /qoc/callupList/setStatus:
+    $ref: 'paths/qoc_checkupList_set_status.yaml'
+  /qoc/callupPolicy:
+    $ref: 'paths/qoc_checkupPolicy.yaml'
   /qoc/list-groups:
     $ref: 'paths/qoc_list-groups.yaml'
   /qoc/participating-practices:
@@ -163,6 +169,9 @@ components:
         items: 
           $ref: schemas/med_dossier/Practitioner.yaml
   responses:
+    NotAcceptable:
+      description: |-
+        The Accept header as sent by the requestor and the types of content this endpoint can emit have no overlap and thus no response is possible.
     ReqFailure:
       description: The request isn't valid; for example, it is missing a required parameter.
       content:
@@ -245,5 +254,3 @@ components:
         <tr><td>exp</td><td>Expires at</td><td><i>OPTIONAL</i> If included, the request must not be received after this time. May be up to 10 minutes in the future. The difference between the exp claim and the iat must be 20 minutes or less and iat &lt; exp. </td></tr>
         <tr><td>nbf</td><td>Not before</td><td><i>OPTIONAL</i> If included, the request must not be received before this time. Should not be set in the future.</td></tr>
         </table>
-
-