From 4c5817084a488b39a16da3e7c36203232ae0e243 Mon Sep 17 00:00:00 2001 From: Reinier Zwitserloot Date: Wed, 17 Apr 2024 05:30:05 +0200 Subject: [PATCH] [breaking] [large] big update: * Make stuff consistent * camelCase everything * re-use elements * add checkupList and fundusByGroup * add Terms Dictionary --- paths/patient_base.yaml | 37 +-- paths/patient_dossier.yaml | 45 +-- paths/patient_fundusByGroup.yaml | 284 ++++++++++++++++++ paths/population_statistics.yaml | 76 +++-- paths/population_statistics_deprived.yaml | 69 +++-- paths/qoc_careprogram.yaml | 13 +- ...qoc_careprogram_{careprogramKey}_fave.yaml | 6 +- paths/qoc_checkupList_{setKey}.yaml | 180 +++++++++++ ..._{setKey}_{indicatorKey}_participants.yaml | 9 +- ...ator_{setKey}_{indicatorKey}_patients.yaml | 1 + paths/qoc_indicatorset_{setKey}.yaml | 11 +- schemas/CareProgram.yaml | 8 +- schemas/Indicator.yaml | 35 ++- schemas/IndicatorDetail.yaml | 8 +- schemas/IndicatorParticipants.yaml | 3 + schemas/IndicatorSet.yaml | 20 +- schemas/PatIdentity.yaml | 26 +- schemas/TermsDictionary.yaml | 58 ++++ schemas/insurer-Uzovi.yaml | 5 +- schemas/pat-BSN.yaml | 5 +- schemas/pat-Name.yaml | 12 +- schemas/pat-patId.yaml | 3 +- schemas/pat-patUnid.yaml | 1 - zoo-api.yaml | 79 ++++- 24 files changed, 806 insertions(+), 188 deletions(-) create mode 100644 paths/patient_fundusByGroup.yaml create mode 100644 paths/qoc_checkupList_{setKey}.yaml create mode 100644 schemas/TermsDictionary.yaml diff --git a/paths/patient_base.yaml b/paths/patient_base.yaml index 356ce93..642e07a 100644 --- a/paths/patient_base.yaml +++ b/paths/patient_base.yaml @@ -1,24 +1,19 @@ get: tags: - Patient - summary: Get basic personal info not directly related to their medical dossier + summary: Get basic personal patient info not directly related to their medical dossier parameters: - - name: agb - in: query - description: |- - The AGB code (dutch: _Algemeen Gegevens Beheer_ - unique identifier for medical professionals and GP practices) of the GP practice - whose patient population should be searched. - required: true - schema: - type: number - example: 1012345 + - $ref: '../zoo-api.yaml#/components/parameters/AgbGP' - name: bsn in: query description: |- The SSN (dutch: _BSN_) of a patient to look up. May only contain digits, cannot contain more than 9 digits, and cannot be 0. required: true schema: - type: string + type: integer + format: int32 + minimum: 1 + maximum: 999999999 example: 123456789 - $ref: '../zoo-api.yaml#/components/parameters/Authorization' responses: @@ -33,9 +28,9 @@ get: - name - gender - patid - - pat_unid + - patUnid - category - - start_date + - startDate properties: bsn: $ref: '../schemas/PatIdentity.yaml#/bsn' @@ -57,14 +52,14 @@ get: $ref: '../schemas/PatIdentity.yaml#/insurance' patid: $ref: '../schemas/PatIdentity.yaml#/patid' - pat_unid: - $ref: '../schemas/PatIdentity.yaml#/pat_unid' - start_date: - $ref: '../schemas/PatIdentity.yaml#/start_date' - end_date: - $ref: '../schemas/PatIdentity.yaml#/end_date' - end_reason: - $ref: '../schemas/PatIdentity.yaml#/end_reason' + patUnid: + $ref: '../schemas/PatIdentity.yaml#/patUnid' + startDate: + $ref: '../schemas/PatIdentity.yaml#/startDate' + endDate: + $ref: '../schemas/PatIdentity.yaml#/endDate' + endReason: + $ref: '../schemas/PatIdentity.yaml#/endReason' careprograms: $ref: '../schemas/PatIdentity.yaml#/careprograms' '400': diff --git a/paths/patient_dossier.yaml b/paths/patient_dossier.yaml index 33c8839..390ee40 100644 --- a/paths/patient_dossier.yaml +++ b/paths/patient_dossier.yaml @@ -13,35 +13,32 @@ get: - q - edit it a bit, can be for example 'dm' or even 'dm/dietetiek'. Send all relevant parts in one response. - required response categories: Journaal, Bepalingen, Medicatie, episodes. parameters: - - name: agb - in: query - description: |- - The AGB code (dutch: _Algemeen Gegevens Beheer_ - unique identifier for medical professionals and GP practices) of the GP practice - whose patient population should be searched. - required: true - schema: - type: number - example: 1012345 + - $ref: '../zoo-api.yaml#/components/parameters/AgbGP' - name: bsn in: query description: |- The SSN (dutch: _BSN_) of a patient to look up. May only contain digits, cannot contain more than 9 digits, and cannot be 0. Either `bsn` or `pu` must be present. schema: - type: string + type: integer + format: int32 + minimum: 1 + maximum: 999999999 example: 123456789 - name: pu in: query + required: false description: |- - The Patient unique ID, as e.g. reported by `/patient/base`'s `pat_unid` response. + The Patient unique ID, as e.g. reported by `/patient/base`'s `patUnid` response. Either `bsn` or `pu` must be present. We do not recommend including both; if this is done, _both_ filters are applied, and - patient info is only returned if a patient exists with both + patient info is only returned if a patient exists matching both. schema: type: string example: "" - name: q in: query + required: false description: |- A comma-separated list of dossier aspects to query. If omitted, everything is returned. The keys match the keys in the JSON structure that is returned on a success, such as `medication` or `measurements`. @@ -57,8 +54,11 @@ get: - contraindications - journals schema: - type: string - example: "medication,measurements" + type: array + items: + type: string + minItems: 1 + example: "q=medication,measurements" - name: purpose in: query description: |- @@ -71,6 +71,7 @@ get: schema: type: string example: diet-dm2 + - $ref: '../zoo-api.yaml#/components/parameters/Authorization' responses: '400': $ref: '../zoo-api.yaml#/components/responses/ReqFailure' @@ -119,14 +120,14 @@ get: $ref: '../schemas/PatIdentity.yaml#/insurance' patid: $ref: '../schemas/PatIdentity.yaml#/patid' - pat_unid: - $ref: '../schemas/PatIdentity.yaml#/pat_unid' - start_date: - $ref: '../schemas/PatIdentity.yaml#/start_date' - end_date: - $ref: '../schemas/PatIdentity.yaml#/end_date' - end_reason: - $ref: '../schemas/PatIdentity.yaml#/end_reason' + patUnid: + $ref: '../schemas/PatIdentity.yaml#/patUnid' + startDate: + $ref: '../schemas/PatIdentity.yaml#/startDate' + endDate: + $ref: '../schemas/PatIdentity.yaml#/endDate' + endReason: + $ref: '../schemas/PatIdentity.yaml#/endReason' episodes: type: array description: |- diff --git a/paths/patient_fundusByGroup.yaml b/paths/patient_fundusByGroup.yaml new file mode 100644 index 0000000..2048a30 --- /dev/null +++ b/paths/patient_fundusByGroup.yaml @@ -0,0 +1,284 @@ +get: + tags: + - Patient + summary: Get per-patient funduscopy status for one care group + description: |- + Returns patients that have an indication for requiring funduscopy across all practices of a care group, taking into account + the medical dossier of each patient as well as the care group's policies. + + For each patient, information about their funduscopy status as well as basic personal information is provided. + + This endpoint may take quite a while to respond (may take more than 5 minutes) which can cause issues with timeouts; configure your + endpoint call function appropriately and ensure intermediate proxies don't time out either. + + Due to the potentially large amount of data, this endpoint rejects requests that don't support compression. A header of at least + `Accept-Encoding: gzip` is therefore required. + parameters: + - $ref: '../zoo-api.yaml#/components/parameters/AgbCareGroup' + - name: purpose + in: query + required: true + description: |- + A key describing the purpose of requesting funduscopy status of many patients. + + Affects what data is supplied (for example, whether personally identifying information is provided), and whether certain + filters are applied. + + * `fundus-broker` – An entity that takes care of arranging appointments between patients and funduscopy professionals. + * `gp` – Medical personnel reviewing their funduscopy-relevant patient population. + * `reporting` – Reporting on the status of the funduscopy-relevant patient population as a whole. + + The `reporting` purpose limits PII, the `fundus-broker` purpose applies filtering as per the preferences of the care group's policies. + schema: + type: string + enum: ['fundus-broker', 'gp', 'reporting'] + - name: director + in: query + required: false + description: |- + If present, filter the returned population on the registered director for funduscopy. + + * `gp` – Returns only those patients whose most recent registration of responsible-for-funduscopy is 'The GP'. + * `specialist` – Returns only those patients whose most recent registration of responsible-for-funduscopy is 'The specialist'. + * `unknown` – Returns only those patients whose most recent registration of responsible-for-funduscopy is not present, registered as 'Unknown', or has an invalid registration. + + If not present, no filtering is applied. + schema: + type: string + enum: ['gp', 'specialist', 'unknown', ''] + - $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: + '200': + description: All patients where funduscopy status is relevant is returned. + content: + application/json: + schema: + type: object + required: + - agb + - regionName + - refDate + - practices + properties: + dict: + $ref: '../schemas/TermsDictionary.yaml' + 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 + regionName: + description: |- + A human readable name describing the care group being queried (The entity whose AGB code is sent as `agb`). + type: string + refDate: + 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. + type: string + format: date + example: '2024-04-01' + practices: + description: |- + One entry for each practice that is part of this care group and participates in at least one funduscopy-related care program. + type: array + items: + type: object + required: + - agb + - name + - gpis + - patients + properties: + agb: + description: |- + The AGB code of the GP practice whose patients are provided in this object. + type: integer + format: int32 + minimum: 1 + maximum: 99999999 + 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' + patients: + type: array + items: + type: object + description: |- + Which patients are returned, and which Personal Identifying Information properties are sent + depends on the chosen `purpose` when making this API call. + required: + - patid + - patUnid + - doctor + - category + - fundus + properties: + bsn: + $ref: '../schemas/PatIdentity.yaml#/bsn' + name: + $ref: '../schemas/PatIdentity.yaml#/name' + gender: + $ref: '../schemas/PatIdentity.yaml#/gender' + dob: + $ref: '../schemas/PatIdentity.yaml#/dob' + category: + $ref: '../schemas/PatIdentity.yaml#/category' + doctor: + $ref: '../schemas/PatIdentity.yaml#/doctor' + address: + $ref: '../schemas/PatIdentity.yaml#/address' + contact: + $ref: '../schemas/PatIdentity.yaml#/contact' + insurance: + $ref: '../schemas/PatIdentity.yaml#/insurance' + patid: + $ref: '../schemas/PatIdentity.yaml#/patid' + patUnid: + $ref: '../schemas/PatIdentity.yaml#/patUnid' + startDate: + $ref: '../schemas/PatIdentity.yaml#/startDate' + endDate: + $ref: '../schemas/PatIdentity.yaml#/endDate' + endReason: + $ref: '../schemas/PatIdentity.yaml#/endReason' + fundus: + type: object + required: + - careprogram + - director + - lastEval + - retinoVal + - left + - right + properties: + careprogram: + description: |- + The care program that is the primary reason Funduscopy status is applicable to this patient. + type: string + example: Ouderenzorg + director: + type: object + description: |- + Contains info about the funduscopy director: Who is responsible for this patient's funduscopy care and followup? + required: + - source + - nhgResult + properties: + source: + description: |- + The aspect of the medical dossier used to determine who is director. Usually one of: + * `DMRFTZ` – indicates that NHG-standard lab/measurement registration 'Regie funduscopie' is used. + * `implied` – Nothing explicit is available in the medical dossier, and the default as per the policies of this care group is provided. + type: string + example: DMRFTZ + timestamp: + type: string + format: date + description: |- + If present, the medical dossier entry used to conclude the funduscopy director was measured/entered on this date. + For example, if `DMRFTZ` registration is used, the date of that measurement as per the dossier. + nhgResult: + description: |- + The director, in NHG answercode for `DMRFTZ` form, regardless of what `source` actually provided this result: + * `48` - The GP is responsible for managing funduscopy + * `49` - The specialist is responsible + * `212` - Unknown + type: integer + format: int32 + enum: [48, 49, 212] + lastEval: + description: |- + The date of the last time the patient has received Funduscopy; will be `null` if no funduscopy is registered. + + The most recent measurement date is provided, even if only one eye was measured on that date. + type: string + format: date + retinoVal: + description: |- + The normalized retinopathy category for the worst eye, in terms of the 2017 Retinopathy level standard (richtlijn Diabetische Retinopathie 2017). + + * `-1` – retinopathy level is unknown or cannot be determined. + * `0` – Retinopathy level R0: No visible retinopathy. + * `1` - Retinopathy level R1: Mild background retinopathy. + * `2` - Retinopathy level R2: Pre-proliferative retinopathy. + * `3` - Retinopathy level R3: Proliferative retinopathy. + type: integer + format: int32 + minimum: -1 + maximum: 3 + left: + description: |- + Details about specifically the left eye. + type: object + required: + - lastEval + - retinoVal + properties: + lastEval: + description: Same as previous level, specifically for left eye. + type: string + format: date + retinoVal: + description: Same as previous level, specifically for left eye. + type: integer + format: int32 + minimum: -1 + maximum: 3 + note: + description: |- + If present, describes why this measurement is missing, unclear, or suboptimal. + + For example, might mention that the result from the lab is likely available, but has not + been properly registered in the medical dossier, or that a result is available but only after + the provided `refDate`. In dutch, and human readable. + type: string + nhgCode: + description: |- + If present, the NHG memocode used to register the retinopathy level. Will be in the terms dictionary. + type: string + example: DMR7FALI + nhgResult: + description: |- + If present, the NHG result value describing the retinopathy level. Will be in the terms dictionary. + type: integer + format: int32 + example: 562 + right: + type: object + description: |- + Like the left eye. + required: + - lastEval + - retinoVal + properties: + lastEval: + type: string + format: date + retinoVal: + type: integer + format: int32 + minimum: -1 + maximum: 3 + note: + type: string + nhgCode: + type: string + nhgResult: + type: integer + format: int32 + '400': + description: The request is invalid; for example, it doesn't contain the required `agb` parameter. + '401': + $ref: '../zoo-api.yaml#/components/responses/JwtFailure' + '403': + description: Indicated group is known but has not authorized ZOO to share this information with signer. diff --git a/paths/population_statistics.yaml b/paths/population_statistics.yaml index 6ff4a9e..a5b5553 100644 --- a/paths/population_statistics.yaml +++ b/paths/population_statistics.yaml @@ -1,51 +1,49 @@ get: tags: - Population statistics - operationId: "populationStatistics" - summary: "Get a population count" + operationId: populationStatistics + summary: Get a population count description: |- - Groups the patient population by any combination of age, preferred doctor, etc. and calculates the count of each category. + Groups the patient population by any combination of age, preferred doctor, etc. and calculates the count of each category. parameters: - - name: referenceDate - in: query - required: true - schema: - type: "string" - pattern: "\\d\\d\\d\\d-\\d\\d-\\d\\d" - format: "date" - description: ISO formatted date - example: 2015-12-15 + - $ref: '../zoo-api.yaml#/components/parameters/RefDateDefaultToday' - name: groupByItems in: query required: true - style: form - explode: false schema: - type: string - enum: - - age - - preferredDoctor - - insurer - - gender - description: "Several items can be added to the group by using a comma separated list, e.g. `groupByItems=gender,age`. If an item is twice or more repeated the first occurrence is used." + type: array + minItems: 1 + items: + type: string + enum: + - age + - preferredDoctor + - insurer + - gender + description: |- + Several items can be added to the group by using a comma separated list, e.g. `groupByItems=gender,age`. + If an item is twice or more repeated the first occurrence is used. - name: insurer in: query - style: form - explode: false required: false schema: - $ref: ../schemas/insurer-Uzovi.yaml - description: "Supply zero, one or more Uzovi's to limit the responses to certain insurer. Use 0 to select all patients without insurer registered. Supply the Uzovi code as an integer in a comma separated list, e.g. `insurer=101,211,3344`." + type: array + items: + $ref: '../schemas/insurer-Uzovi.yaml' + description: |- + Supply zero, one or more Uzovis to limit the responses to certain insurer. Use 0 to select all patients without insurer registered. Supply the Uzovi code as an integer in a comma separated list, e.g. `insurer=101,211,3344`. - name: passerBy in: query required: false schema: type: boolean - description: "True to include passer-by patients. This also includes Medicom's noni patients. (Noni = niet op naam ingeschreven.) By default passer-by patients are excluded from the response." + description: |- + `true` to include passer-by patients. This also includes Medicom's noni patients. (Noni = niet op naam ingeschreven.) By default passer-by patients are excluded from the response. - $ref: '../zoo-api.yaml#/components/parameters/Authorization' responses: 200: - description: "The response body is a JSON-array with for each group, defined by a sequence of `groupByItem` query parameters, an object with a count `n`. Only patients with an active registration on the reference date are included. When age is chosen as a category, only patients with a birthdate are included and only known ages are included in the response. The insurer is outputted as an Uzovi (with name and concern). The most recent Uzovi table is used to convert codes to names and concerns. If an Uzovi is missing in that table it is still added to the response, but without name and/or concern. The sequence of the items in the URL is the same as the sequence in the grouping of the output." + description: |- + The response body is a JSON-array with for each group, defined by a sequence of `groupByItem` query parameters, an object with a count `n`. Only patients with an active registration on the reference date are included. When age is chosen as a category, only patients with a birthdate are included and only known ages are included in the response. The insurer is outputted as an Uzovi (with name and concern). The most recent Uzovi table is used to convert codes to names and concerns. If an Uzovi is missing in that table it is still added to the response, but without name and/or concern. The sequence of the items in the URL is the same as the sequence in the grouping of the output. content: application/json: schema: @@ -54,16 +52,34 @@ get: type: object properties: age: - type: number + type: integer + minimum: 0 + format: int32 example: 42 preferredDoctor: $ref: '../schemas/PatIdentity.yaml#/doctor' insurer: - $ref: '../schemas/PatIdentity.yaml#/insurer' + type: object + properties: + uzovi: + $ref: '../schemas/insurer-Uzovi.yaml' + name: + type: string + description: |- + The name of the insurer according the [Vektis register](https://www.vektis.nl/uzovi-register). If the Uzovi is unknown, the Uzovi code is used as the name. The latest register is used to lookup the name for the code. + example: FBTO Zorgverzekeringen N.V. + concern: + type: string + description: The concern name, if any, otherwise the empty string. + example: ACHMEA + valid: + type: boolean + description: True if the insurer can be validated using the Uzovi table on the reference date. gender: $ref: '../schemas/PatIdentity.yaml#/gender' n: - type: number + type: integer + format: int32 description: "The number of unique patients in the group." example: 7 400: diff --git a/paths/population_statistics_deprived.yaml b/paths/population_statistics_deprived.yaml index b74f341..9feee68 100644 --- a/paths/population_statistics_deprived.yaml +++ b/paths/population_statistics_deprived.yaml @@ -1,45 +1,50 @@ get: tags: - Population statistics - operationId: "populationStatisticsDeprivedNeighborhood" - summary: "Patients in a deprived neighborhood" - description: "A simple report with a count of all patients living in a deprived neighborhood or regular one based on the well-known postcode table." + operationId: populationStatisticsDeprivedNeighborhood + summary: Patients in a deprived neighborhood + description: A simple report with a count of all patients living in a deprived neighborhood or regular one based on the well-known postcode table. parameters: - - name: referenceDate - in: query - required: true - schema: - type: "string" - pattern: "\\d\\d\\d\\d-\\d\\d-\\d\\d" - format: "date" - description: ISO formatted date - example: 2015-12-15 + - $ref: '../zoo-api.yaml#/components/parameters/RefDateDefaultToday' - $ref: '../zoo-api.yaml#/components/parameters/Authorization' responses: 200: - description: "The response body is a JSON-array with exactly three objects. Patients who are no longer registered are excluded from the response, so only patients with an active registration are included. Passer-by and NONI-patients are excluded." + description: |- + Returns the counts of all patients divided into 3 categories: + * Known to live in a deprived neighborhood + * known to live in a regular neighborhood + * Status of neighborhood unknown (for example, because living address of patient is not known or deprived status of that location is not known). + content: application/json: schema: - type: array - items: - oneOf: - - type: object - properties: - deprivedNeighborhood: - type: number - example: 42 - - type: object - properties: - regularNeighborhood: - type: number - example: 256 - - type: object - description: "When an irregular postcode is used for a patient it can't be used for determining the neighborhood. These patients are added to unknown." - properties: - unknown: - type: number - example: 3 + type: object + required: + - deprived + - regular + - unknown + properties: + deprived: + description: Number of patients living in a deprived neighborhood + schema: + type: integer + format: int32 + minimum: 0 + example: 42 + regular: + description: Number of patients living in a regular neighborhood + schema: + type: integer + format: int32 + minimum: 0 + example: 256 + unknown: + description: Number of patients either living in an unknown location or a known location with unknown depraved status + schema: + type: integer + format: int32 + minimum: 0 + example: 0 400: description: "Common HTTP semantics, see the response body." 401: diff --git a/paths/qoc_careprogram.yaml b/paths/qoc_careprogram.yaml index d8cb156..a7173a3 100644 --- a/paths/qoc_careprogram.yaml +++ b/paths/qoc_careprogram.yaml @@ -2,16 +2,19 @@ get: tags: - Quality of Care summary: List all available care programs - description: Includes all care programs that the user is allowed to enable or preview, i.e. even ones that shouldn't be shown by default.e + description: |- + 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: + Examples: + * Example complete response + * Example UI render (Somewhat outdated) + content: application/json: schema: diff --git a/paths/qoc_careprogram_{careprogramKey}_fave.yaml b/paths/qoc_careprogram_{careprogramKey}_fave.yaml index 358393c..eb64692 100644 --- a/paths/qoc_careprogram_{careprogramKey}_fave.yaml +++ b/paths/qoc_careprogram_{careprogramKey}_fave.yaml @@ -9,13 +9,17 @@ put: required: true schema: type: string + - $ref: '../zoo-api.yaml#/components/parameters/Authorization' requestBody: content: application/x-www-form-urlencoded: schema: type: string description: |- - The value `T`/`F`/`X`, respectively: "favourited", "unfavourited", "no favourite status" + One of: + * `T` – favourited (show it) + * `F` - unfavourited (do not show it) + * `X` - No favourite status (show it if this entity has this program in its default set, otherwise don't). example: T enum: - T diff --git a/paths/qoc_checkupList_{setKey}.yaml b/paths/qoc_checkupList_{setKey}.yaml new file mode 100644 index 0000000..2c3a8bd --- /dev/null +++ b/paths/qoc_checkupList_{setKey}.yaml @@ -0,0 +1,180 @@ +get: + tags: + - Quality of Care + summary: Load call-up status for patients in a care program + description: |- + Returns each patient in a care program along with the progress on required or suggested measurements indicated for this care program. + parameters: + - name: setKey + in: path + description: The key as listed in the `CareProgram` schema. + required: true + schema: + type: string + example: ZEL-dm + - name: refDate + in: query + description: |- + The date in `2023-04-01` format; defaults to the first day in the next quarter, e.g. on april 5th 2023, defaults to `2023-07-01`. + required: false + schema: + type: string + format: date + example: 2023-04-01 + - name: addr + in: query + required: false + description: Request inclusion of address information + schema: + type: boolean + - name: bsn + in: query + required: false + description: Request inclusion of BSN information (dutch social security number) + schema: + type: boolean + - name: email + in: query + required: false + description: Request inclusion of email addresses + schema: + type: boolean + - $ref: '../zoo-api.yaml#/components/parameters/Authorization' + responses: + '200': + description: |- + list of patients + content: + application/json: + schema: + type: object + properties: + gpis: + $ref: '../schemas/IndicatorSet.yaml#/properties/gpis' + key: + $ref: '../schemas/IndicatorSet.yaml#/properties/key' + name: + $ref: '../schemas/IndicatorSet.yaml#/properties/name' + refDate: + $ref: '../schemas/IndicatorSet.yaml#/properties/refDate' + calculating: + $ref: '../schemas/IndicatorSet.yaml#/properties/calculating' + doctors: + description: |- + Lists all relevant doctors. A doctor is relevant if they are responsible + for at least 1 patient in the list. + type: array + items: + type: object + properties: + name: + description: |- + The name (or possibly memocode; something an employee of the practice will recognize) of the general practitioner. + type: string + agb: + description: If known, the AGB code of this general practitioner. + type: integer + format: int32 + minimum: 1 + maximum: 99999999 + required: + - name + indicators: + type: array + description: |- + One entry for each kind of measurement that (may) require call-up. + items: + type: object + properties: + title: + description: |- + The title of this indicator + type: string + example: Bloeddruk + 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. + required: + - title + patients: + type: array + items: + type: object + properties: + patid: + $ref: '../schemas/PatIdentity.yaml#/patid + doctor: + type: integer + format: int32 + description: |- + An index (0-based) into the `doctors` entry: This is the GP responsible for this patient. + status: + type: string + example: open + enum: + - open + description: |- + A key indicating the appointment status for this patient: + + * `open` – An appointment still needs to be made. + + (Work in progress) + address1: + type: string + description: |- + The first line of this patient's postal address (Street name and number, generally). + city: + type: string + description: Patient lives in this city or township. + postcode: + type: string + description: Postcode of the patient. + bsn: + type: integer + minimum: 1 + maximum: 999999999 + format: int32 + description: The BSN (dutch social security number) of the patient. + dob: + type: string + format: date + description: Date of birth of the patient. + email: + type: string + format: email + description: Email address of the patient. + state: + type: string + description: |- + A string containing 1 character for each indicator as listed in `indicators`. + + This character represents the patient's call-up state for that indicator: + + * `-` – This indicator is not relevant for this patient; no call-up needed. + * `R` – This is an optional indicator, but, the patient doesn't have this measurement. + * `0` – This is a required indicator and the patient doesn't have it. + * `1` – The patient has this measurement; but unless it is measured again, next quarter it'll be too long ago and no longer counts. + * `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). + required: + - patid + - doctor + - status + - dob + - state + required: + - gpis + - key + - name + - refDate + - calculating + '401': + $ref: '../zoo-api.yaml/#/components/responses/NoAuth' + '403': + $ref: '../zoo-api.yaml#/components/responses/NoAccess' + '404': + description: The provided `setKey` doesn't refer to a valid program. + diff --git a/paths/qoc_indicator_{setKey}_{indicatorKey}_participants.yaml b/paths/qoc_indicator_{setKey}_{indicatorKey}_participants.yaml index b427c52..2cc055b 100644 --- a/paths/qoc_indicator_{setKey}_{indicatorKey}_participants.yaml +++ b/paths/qoc_indicator_{setKey}_{indicatorKey}_participants.yaml @@ -17,13 +17,6 @@ get: schema: type: string example: ZOO-dm2-hb-3 - - name: group - in: query - description: The key as listed in the `list-groups` endpoint. Defaults to the only allowed group if the authentication party only has one; otherwise required. - required: false - schema: - type: string - example: hwf - name: refDate in: query description: |- @@ -33,6 +26,8 @@ get: type: string format: date example: 2023-04-01 + - $ref: '../zoo-api.yaml#/components/parameters/CareGroup' + - $ref: '../zoo-api.yaml#/components/parameters/Authorization' responses: '200': description: >- diff --git a/paths/qoc_indicator_{setKey}_{indicatorKey}_patients.yaml b/paths/qoc_indicator_{setKey}_{indicatorKey}_patients.yaml index 3cea0c0..54e62c0 100644 --- a/paths/qoc_indicator_{setKey}_{indicatorKey}_patients.yaml +++ b/paths/qoc_indicator_{setKey}_{indicatorKey}_patients.yaml @@ -25,6 +25,7 @@ get: type: string format: date example: 2023-04-01 + - $ref: '../zoo-api.yaml#/components/parameters/Authorization' responses: '200': description: >- diff --git a/paths/qoc_indicatorset_{setKey}.yaml b/paths/qoc_indicatorset_{setKey}.yaml index cf2a267..48a19ae 100644 --- a/paths/qoc_indicatorset_{setKey}.yaml +++ b/paths/qoc_indicatorset_{setKey}.yaml @@ -19,15 +19,16 @@ get: type: string format: date example: 2023-04-01 + - $ref: '../zoo-api.yaml#/components/parameters/Authorization' responses: '200': - description: >- + description: |- all data required to render an indicatorset is returned. - Examples: + Examples: + * Example complete response + * Example UI render + content: application/json: schema: diff --git a/schemas/CareProgram.yaml b/schemas/CareProgram.yaml index 908842f..7ce6c96 100644 --- a/schemas/CareProgram.yaml +++ b/schemas/CareProgram.yaml @@ -14,7 +14,7 @@ properties: description: |- *OPTIONAL* in dutch and in *HTML*, can consist of multiple paragraphs, but won't be more than ~5 lines or so. type: string - example: Ketenzorg DM2 volgens de standaard werkwijze van zorgggroep ZEL. + example: Ketenzorg DM2 volgens de standaard werkwijze van zorggroep ZEL. tags: description: |- A list of very short dutch strings categorizing the care program. @@ -66,9 +66,9 @@ properties: 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). - WARNING: HVZ and VVR are being debated; this really is a single care program (probably called `CVRM`). This may change soon. + _WARNING_: HVZ and VVR are being debated; this really is a single care program (probably called `CVRM`). This may change soon. - NOTE: This list is expanded any time new care programs are introduced. API callers are encouraged not to hardcode the list + _NOTE_: This list is expanded any time new care programs are introduced. API callers are encouraged not to hardcode the list of enumerated values, or at least be prepared to accept other values.
@@ -87,6 +87,6 @@ properties: type: string url: description: |- - Only for `type: "link"` (Work in progress: For now also for `type: "casefinder"`). + Only for `type: "link"` (_Work in progress_: For now also for `type: "casefinder"`). type: string example: '/indicators/casefinder?t=dm' diff --git a/schemas/Indicator.yaml b/schemas/Indicator.yaml index 4745ea1..136da06 100644 --- a/schemas/Indicator.yaml +++ b/schemas/Indicator.yaml @@ -1,4 +1,10 @@ type: object +required: + - key + - title + - type + - style + - bars properties: key: description: Unique identifier, not to be shown to the user, for referring to this indicator in other API calls @@ -11,7 +17,7 @@ properties: type: string example: ZEL-dm2-bp title: - description: Short, in dutch, *HTML* (but rarely includes formatting; at most, sup/superscript). + description: Short, in dutch, plain text. type: string example: Prevalentie Diabetes type: @@ -40,7 +46,9 @@ properties: ordered list (like html `
    `), and it is convenient for indicators to copy this numbering scheme. For most UI applications, simply prefix this to the title, e.g. render as `1. Title Here`. If missing, do not show an index in the title. - type: number + type: integer + format: int32 + minimum: 1 example: 1 xMin: description: |- @@ -154,14 +162,16 @@ properties: items: description: >- Each bar describes the calculated result for one entity at one measurement date. For example, an indicator box could contain 3 such entries: -
      -
    • The practice, this quarter.
      • -
    • The practice, previous quarter (to put this quarter into context).
      • -
    • GP group (zorg groep)'s results this quarter.
      • -
    + + * The practice, this quarter. + * The practice, previous quarter (to put this quarter into context). + * GP group (zorg groep)'s results this quarter. + There is always at least one. The first one is the main bar, that is, what this report is reporting on; all further bars exist solely to provide context. type: object + required: + - segments properties: legend: description: |- @@ -181,11 +191,14 @@ properties: Place each segment in sequence in the bar. They are guaranteed to fit. The values for each part are relative to `xMin`/`xMax`, e.g. a percentage. They may not add up to 100 - in that case, leave the remainder blank. - For example:
      -
    • 3 segments for 'blood pressure results': 40-Good, 35-Concern, 25-Problematic.
      • -
    • 1 segment for 'blood pressure has been measured': 85-Measured
      • -
    + For example: + + * 3 segments for 'blood pressure results': 40-Good, 35-Concern, 25-Problematic. + * 1 segment for 'blood pressure has been measured': 85-Measured type: object + required: + - style + - value properties: style: description: |- diff --git a/schemas/IndicatorDetail.yaml b/schemas/IndicatorDetail.yaml index e64994c..ea8e016 100644 --- a/schemas/IndicatorDetail.yaml +++ b/schemas/IndicatorDetail.yaml @@ -2,6 +2,8 @@ description: |- A report about a specific aspect of a care program, listing how each patient is categorized. type: object properties: + dict: + $ref: 'TermsDictionary.yaml' gpis: $ref: 'GPIS.yaml' key: @@ -48,7 +50,7 @@ properties: items: type: object properties: - pat_unid: + patUnid: $ref: 'pat-patUnid.yaml' bsn: $ref: 'pat-BSN.yaml' @@ -63,7 +65,7 @@ properties: example: |- [NHG DMHB TZ] = [NHGA 49] op [DATE 20220223]. required: - - pat_unid + - patUnid - bsn - name - dob @@ -74,4 +76,4 @@ required: - name - refDate - description - - chapters + - blocks diff --git a/schemas/IndicatorParticipants.yaml b/schemas/IndicatorParticipants.yaml index 8729fe8..31513c2 100644 --- a/schemas/IndicatorParticipants.yaml +++ b/schemas/IndicatorParticipants.yaml @@ -40,6 +40,9 @@ properties: agb: description: AGB of the GP practice, if known. type: integer + format: int32 + minimum: 1 + maximum: 99999999 skipReason: description: Human readable string describing why this GP practice is excluded (in dutch, *HTML*). type: string diff --git a/schemas/IndicatorSet.yaml b/schemas/IndicatorSet.yaml index 3c7c6c7..29fa5ce 100644 --- a/schemas/IndicatorSet.yaml +++ b/schemas/IndicatorSet.yaml @@ -1,6 +1,11 @@ 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 type: object +required: + - key + - name + - refDate + - calculating properties: gpis: $ref: 'GPIS.yaml' @@ -13,19 +18,30 @@ properties: type: string example: Diabetes Mellitus type 2 – per InEen 2023 accreditatie refDate: - description: 'All calculations are done on this date (dutch: _peildatum_).' + description: 'All calculations are done based on this date (dutch: _peildatum_).' type: string format: date example: 2023-04-01 + calculating: + description: |- + Calculating an indicator set report takes some time; this API responds with a `calculating` value of less than 1.0 and + no `chapters` section (thus, no data). Call this endpoint a few times to get status updates. Once calculation is complete, + `1.0` will be returned and `chapters` will be provided. + format: number + minimum: 0.0 + maximum: 1.0 chapters: description: |- Each chapter has a title and contains 1 or more indicators. type: array items: type: object + required: + - title + - indicatorGroups properties: title: - description: In dutch, *HTML* formatted; should fit on one line. + description: In dutch, plain text formatted; should fit on one line. type: string example: Populatie indicatorGroups: diff --git a/schemas/PatIdentity.yaml b/schemas/PatIdentity.yaml index e9e5be8..6fc3ff2 100644 --- a/schemas/PatIdentity.yaml +++ b/schemas/PatIdentity.yaml @@ -112,27 +112,11 @@ insurance: example: 123456789012345 uzovi: $ref: 'insurer-Uzovi.yaml' -insurer: - type: object - properties: - uzovi: - $ref: 'insurer-Uzovi.yaml' - name: - type: string - description: "The name of the insurer according the [Vektis register](https://www.vektis.nl/uzovi-register). If the Uzovi is unknown, the Uzovi code is used as the name. The latest register is used to lookup the name for the code." - example: "FBTO Zorgverzekeringen N.V." - concern: - type: string - description: "The concern name, if any, otherwise the empty string." - example: "ACHMEA" - valid: - type: boolean - description: "True if the insurer can be validated using the Uzovi table on the reference date." patid: $ref: 'pat-patId.yaml' -pat_unid: +patUnid: $ref: 'pat-patUnid.yaml' -start_date: +startDate: type: string format: date description: |- @@ -143,17 +127,17 @@ start_date: (which is to consider this patient as part of this practice's population regardless of how far back you want to go). example: 1994-08-20 -end_date: +endDate: type: string format: date description: |- If present, patient has exited the practice on this date. (dutch: _uitschrijf datum_). default: "" -end_reason: +endReason: description: |- Reason patient left the practice (dutch: _reden vertrek_). - This property is never present if `end_date` isn't present. Otherwise, this value _might_ contain + This property is never present if `endDate` isn't present. Otherwise, this value _might_ contain a non-blank letter as per [NHG-table-9](https://referentiemodel.nhg.org/sites/default/files/NHG-Tabel%209-Reden%20vertrek-versie-5-Inkijkexemplaar_1.pdf): * `A` = To other practice diff --git a/schemas/TermsDictionary.yaml b/schemas/TermsDictionary.yaml new file mode 100644 index 0000000..2c6aca7 --- /dev/null +++ b/schemas/TermsDictionary.yaml @@ -0,0 +1,58 @@ +description: |- + Provides definitions of codes used in the rest of this response. + + Always sent first. +type: object +properties: + bepalingen: + description: |- + Represents measurements (such as bloodpressure) and snapshot determinations (such as 'who is responsible for Type 2 diabetes chronic care'), + based on NHG memocodes. Each key in this object is a full NHG memocode (with no spaces), and each value is an object. That object + contains a key/value pair `"wcia"` containing the NHG numeric code for that memocode, a k/v pair `"text"` containing a dutch human + readable description. If the valid values for this measurement are enumerated, a k/v pair `"nhgVal": true` is present, as well as + key `"nhg-antwoorden"` mapping to an object containing simple k/v pairs where the key contains a number and the value is a dutch human + readable description of that means, such as `"48": "Huisarts"`. + type: object + additionalProperties: true + example: |- + { + "DMHBTZ": { + "wcia": 2206, + "text": "hoofdbehandelaar diabetes", + "nhgVal": true, + "nhgAnswers": { + "48": "Huisarts", + "49": "Specialist" + } + } + } + icpc: + description: |- + Represents diagnoses and medical conditions, based on the ICPC1.1-NL standard. Keys in this object represent ICPC codes, always + formatted as a capital letter, followed by 2 digits, a dot, and 2 more digits. These map to value objects that contain 2 + k/v pairs: `"text"` which contains dutch human readable text explaining what this ICPC code represents, and a `"classText"` k/v pair + containing the dutch human readable name of the class (the letter). + type: object + additionalProperties: true + example: |- + { + "T90.02": { + "text": "Diabetes mellitus type 2", + "classText": "Endocriene klieren/metabol./voeding" + } + } + atcs: + description: |- + Represents medications, mapping ATC codes to value objects containing one k/v pair: `"text"` to a dutch human readable + description of the medication. The ATC codes may represent groups of medications (less than 7 characters). + type: object + additionalProperties: true + example: |- + { + "A02AB": { + "text": "Aluminiumverbindingen" + }, + "A11GA01": { + "text": "Ascorbinezuur" + } + } \ No newline at end of file diff --git a/schemas/insurer-Uzovi.yaml b/schemas/insurer-Uzovi.yaml index c9b4741..f7d0b29 100644 --- a/schemas/insurer-Uzovi.yaml +++ b/schemas/insurer-Uzovi.yaml @@ -3,4 +3,7 @@ description: |- A value between 0 (no insurance) and 9999; these numbers are customary rendered as 4 digits. When rendering, we suggest callers to left-pad with zeroes. type: number -example: 0211 +format: int32 +minimum: 0 +maximum: 9999 +example: 211 diff --git a/schemas/pat-BSN.yaml b/schemas/pat-BSN.yaml index c9c97d6..8ede034 100644 --- a/schemas/pat-BSN.yaml +++ b/schemas/pat-BSN.yaml @@ -4,5 +4,8 @@ description: |- It is customary that BSNs are 9 digits; this API returns a number, i.e., no leading zeroes. API callers may want to transform this value into a string by explicitly left-padding `0` characters to the front to make the bsn value 9 digits. -type: number +type: integer +format: int32 +minimum: 0 +maximum: 999999999 example: 123456789 diff --git a/schemas/pat-Name.yaml b/schemas/pat-Name.yaml index 55d6b0e..271461f 100644 --- a/schemas/pat-Name.yaml +++ b/schemas/pat-Name.yaml @@ -1,12 +1,12 @@ description: All relevant info about the patient's name. type: object properties: - display_name: + displayName: description: |- The full name as commonly displayed in dutch custom: initials, partner name, followed by own name. type: string example: M.A. van der Dussen-de Villepin - firstname: + firstName: description: |- Patient's first name(s), separated by spaces. @@ -22,27 +22,27 @@ properties: the source. type: string example: MA - infix_own: + infixOwn: description: |- The prefix of the patient's own last name (what they were born with; not the name inherited from a spouse): `van`, `de`, `van der` - a mostly uniquely dutch aspect to last names. type: string example: de default: "" - own_lastname: + ownLastName: description: |- The patient's own last name without a prefix (what they were born with; not the name inherited from a spouse). type: string example: Villepin - infix_partner: + infixPartner: description: |- The prefix of the patient's (ex-)spouse's last name; not all patients that are married go by their spouse's last name and often, if they don't, this field will be blank (i.e. not sent). type: string example: van der default: "" - partner_lastname: + partnerLastName: description: |- The the patient's (ex-)spouse's last name without prefix; not all patients that are married go by their spouse's last name and often, if they don't, this field will be blank. diff --git a/schemas/pat-patId.yaml b/schemas/pat-patId.yaml index a56af01..9328d22 100644 --- a/schemas/pat-patId.yaml +++ b/schemas/pat-patId.yaml @@ -10,6 +10,7 @@ description: |- The number is guaranteed to be positive, and have at most 14 digits. We suggest using a 64-bit numeric type to store the number; transferring this number via IEEE-double math (common, in JSON) is safe, as the number will not exceed the range within which all whole integers are perfectly representable (~`2^52`). -type: number +type: integer +format: int64 example: 1234 diff --git a/schemas/pat-patUnid.yaml b/schemas/pat-patUnid.yaml index befb2ef..c80ee5a 100644 --- a/schemas/pat-patUnid.yaml +++ b/schemas/pat-patUnid.yaml @@ -4,4 +4,3 @@ description: |- if supplying HIS does not send them. type: string example: 1234 - diff --git a/zoo-api.yaml b/zoo-api.yaml index 2cf4ad1..11389c6 100644 --- a/zoo-api.yaml +++ b/zoo-api.yaml @@ -12,7 +12,7 @@ info: #servers: # - url: https://tools.zorgoporde.nl/api1 # description: Production -# - url: https://test.zorgoporde.nl/api1 +# - url: https://acc.zorgoporde.nl/api1 # description: Testing security: - @@ -41,22 +41,22 @@ 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. paths: - /springboard/apps: - $ref: 'paths/springboard_apps.yaml' /patient/dossier: $ref: 'paths/patient_dossier.yaml' /patient/base: $ref: 'paths/patient_base.yaml' + /patient/fundusByGroup: + $ref: 'paths/patient_fundusByGroup.yaml' /population/statistics: $ref: 'paths/population_statistics.yaml' /population/statistics/deprivedNeighborhood: $ref: 'paths/population_statistics_deprived.yaml' /qoc/careprogram: $ref: 'paths/qoc_careprogram.yaml' - /qoc/careprogram/{careprogramKey}/fave: - $ref: 'paths/qoc_careprogram_{careprogramKey}_fave.yaml' /qoc/indicatorset/{setKey}: $ref: 'paths/qoc_indicatorset_{setKey}.yaml' + /qoc/checkupList/{setKey}: + $ref: 'paths/qoc_checkupList_{setKey}.yaml' /qoc/indicator/{setKey}/{indicatorKey}/patients: $ref: 'paths/qoc_indicator_{setKey}_{indicatorKey}_patients.yaml' /qoc/indicator/{setKey}/{indicatorKey}/participants: @@ -72,20 +72,71 @@ components: in: header description: |- The string `"Bearer "` followed by a single-use signed JWT token with the following mandatory claims: -
      -
    • kid – key id: A string identifying a trusted signer; agreed upon between user and Zorg op Orde beforehand.
      • -
    • iat – Issued at: Time when this JWT was created and signed. Must be no more than 1 hour ago. -
    • jti – JWT ID: A unique string used to prevent replay: Any given ID can not be used more than once. -
    • agb – GP AGB: AGB code (Medical entity identifier); the lookup will be done on the medical dossier data of this practice or entity. -
    • exp – OPTIONAL Expires at: If included, the request must not be received after this time. -
    • nbf – OPTIONAL Not before: If included, the request must not be received before this time. -
    - The JWT must be signed, preferably with HS256. + * `kid` – **key id**: A string identifying a trusted signer; agreed upon between user and Zorg op Orde beforehand. + * `iat` – **Issued at**: Time when this JWT was created and signed. Must be no more than 1 hour ago. + * `jti` – **JWT ID**: A unique string used to prevent replay: Any given ID can not be used more than once. + * `agb` – **GP AGB**: AGB code (Medical entity identifier); the lookup will be done on the medical dossier data of this practice or entity. + * `exp` – _OPTIONAL_ **Expires at**: If included, the request must not be received after this time. + * `nbf` – _OPTIONAL_ **Not before**: If included, the request must not be received before this time. + + The JWT must be signed, preferably with `HS256`. required: true schema: type: string example: >- Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJraWQiOiJaT08tQVBJLVBLSS1JRCIsImFnYiI6IjAxMDEyMzQ1IiwiaWF0IjoxNTE2MjM5MDIyLCJqdGkiOiJ0MTIzNC01Njc4LUFCQ0QifQ.wTesCfFTq1Mz8z7hUWU6zzKSc3dopWnpeETR7eDzFtc + AgbGP: + name: agb + in: query + description: |- + The AGB code (dutch: _Algemeen Gegevens Beheer_ - unique identifier for medical professionals and GP practices) of the GP practice. + This value can be a claim in the JWT (preferred), or, if no `agb` claim exists in the authenticating JWT token, it must be a query parameter. + The JWT token must be authorized for this entity. + required: false + schema: + type: integer + minimum: 1 + maximum: 99999999 + AgbCareGroup: + name: agb + in: query + description: |- + The AGB code (dutch: _Algemeen Gegevens Beheer_ - unique identifier for medical professionals and GP practices) of the entity + that represents multiple GP practices. This value can be a claim in the JWT (preferred), or, if no `agb` claim exists in the + authenticating JWT token, it must be a query parameter. The JWT token must be authorized for this entity. + required: false + schema: + type: integer + minimum: 1 + maximum: 99999999 + Pretty: + name: pretty + in: query + description: If `true` the emitted JSON is pretty-printed. Use only for debugging purposes. + schema: + type: boolean + default: false + RefDateDefaultToday: + name: refDate + in: query + description: |- + If present, the date used as context (any measurements available done afterwards aren't taken into account, any expiry calculations + use this date as reference, and so forth). + Defaults to today. + schema: + type: string + format: date + example: '2024-04-01' + CareGroup: + name: group + in: query + description: |- + The 'key' for the care group you want to retrieve data for. Providing this parameter is pointless unless the AGB code supplied + via the `agb` parameter is responsible for more than one care group which is rare. A list of valid groups can be obtained via + the `list-groups` endpoint. + required: false + schema: + type: string responses: ReqFailure: description: |-