From 97f56e0545b5519bce466c21f795a84291219634 Mon Sep 17 00:00:00 2001 From: Reinier Zwitserloot Date: Sun, 31 Mar 2024 16:27:13 +0200 Subject: [PATCH] [qoc] endpoint /qoc/indicator/?/?/practices/? is now available --- ...Key}_{indicatorKey}_practices_{group}.yaml | 48 +++++++++ ...ticipating-practices_{group}_{setKey}.yaml | 2 +- schemas/IndicatorDetail.yaml | 17 ++- schemas/IndicatorParticipants.yaml | 100 ++++++++++++++++++ zoo-api.yaml | 2 + 5 files changed, 157 insertions(+), 12 deletions(-) create mode 100644 paths/qoc_indicator_{setKey}_{indicatorKey}_practices_{group}.yaml create mode 100644 schemas/IndicatorParticipants.yaml diff --git a/paths/qoc_indicator_{setKey}_{indicatorKey}_practices_{group}.yaml b/paths/qoc_indicator_{setKey}_{indicatorKey}_practices_{group}.yaml new file mode 100644 index 0000000..d3ac9d7 --- /dev/null +++ b/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. diff --git a/paths/qoc_participating-practices_{group}_{setKey}.yaml b/paths/qoc_participating-practices_{group}_{setKey}.yaml index 5e643dd..bfe4b0b 100644 --- a/paths/qoc_participating-practices_{group}_{setKey}.yaml +++ b/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: diff --git a/schemas/IndicatorDetail.yaml b/schemas/IndicatorDetail.yaml index bc68db8..e64994c 100644 --- a/schemas/IndicatorDetail.yaml +++ b/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. - 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 + $ref: 'Indicator.yaml#/properties/key' + title: + $ref: 'Indicator.yaml#/properties/title' + type: + $ref: 'Indicator.yaml#/properties/type' refDate: - description: 'All calculations are done on this date (dutch: _peildatum_).' - type: string - format: date - example: 2023-04-01 + $ref: 'IndicatorSet.yaml#/properties/refDate' description: description: A more detailed description of what this indicator calculates. *HTML* type: string diff --git a/schemas/IndicatorParticipants.yaml b/schemas/IndicatorParticipants.yaml new file mode 100644 index 0000000..d933925 --- /dev/null +++ b/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 diff --git a/zoo-api.yaml b/zoo-api.yaml index cbb4c3b..9515133 100644 --- a/zoo-api.yaml +++ b/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}: