[minor]

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/qoc_careprogram.yaml

@@ -37,8 +37,10 @@ get:
                       type: string
                     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:

paths/qoc_indicatorset_{setKey}.yaml

@@ -3,7 +3,9 @@ get:
   tags:
     - Quality of Care
   summary: Indicator set
-  description: Provides the data to generate an report showing 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 based on the same database. The authorisation for the care group to access care program data is taken in account.
+  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
@@ -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