From 204149a40d970823bd199ee31cc140ccf1e894f5 Mon Sep 17 00:00:00 2001 From: Reinier Zwitserloot Date: Tue, 21 May 2024 05:03:50 +0200 Subject: [PATCH] [fundus]: Added docs for fundus-by-practice endpoint --- paths/patient_fundusByGroup.yaml | 188 +--------------------------- paths/patient_fundusByPractice.yaml | 73 +++++++++++ schemas/fundus-status.yaml | 187 +++++++++++++++++++++++++++ zoo-api.yaml | 2 + 4 files changed, 263 insertions(+), 187 deletions(-) create mode 100644 paths/patient_fundusByPractice.yaml create mode 100644 schemas/fundus-status.yaml diff --git a/paths/patient_fundusByGroup.yaml b/paths/patient_fundusByGroup.yaml index 2048a30..84c03fc 100644 --- a/paths/patient_fundusByGroup.yaml +++ b/paths/patient_fundusByGroup.yaml @@ -89,193 +89,7 @@ get: 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 + $ref: "../schemas/fundus-status.yaml" '400': description: The request is invalid; for example, it doesn't contain the required `agb` parameter. '401': diff --git a/paths/patient_fundusByPractice.yaml b/paths/patient_fundusByPractice.yaml new file mode 100644 index 0000000..fa70785 --- /dev/null +++ b/paths/patient_fundusByPractice.yaml @@ -0,0 +1,73 @@ +get: + tags: + - Patient + summary: Get per-patient funduscopy status for one GP practice + description: |- + Returns patients that have an indication for requiring funduscopy, taking into account the medical dossier of each patient as well as the relevant care group's policies. + + For each patient, information about their funduscopy status as well as basic personal information is provided. + parameters: + - $ref: '../zoo-api.yaml#/components/parameters/AgbGP' + - 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/Authorization' + responses: + '200': + description: All patients where funduscopy status is relevant is returned. + content: + application/json: + schema: + type: object + required: + - refDate + - practice + properties: + dict: + $ref: '../schemas/TermsDictionary.yaml' + 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' + practice: + $ref: "../schemas/fundus-status.yaml" + '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/schemas/fundus-status.yaml b/schemas/fundus-status.yaml new file mode 100644 index 0000000..a388cdc --- /dev/null +++ b/schemas/fundus-status.yaml @@ -0,0 +1,187 @@ +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: '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: 'PatIdentity.yaml#/bsn' + name: + $ref: 'PatIdentity.yaml#/name' + gender: + $ref: 'PatIdentity.yaml#/gender' + dob: + $ref: 'PatIdentity.yaml#/dob' + category: + $ref: 'PatIdentity.yaml#/category' + doctor: + $ref: 'PatIdentity.yaml#/doctor' + address: + $ref: 'PatIdentity.yaml#/address' + contact: + $ref: 'PatIdentity.yaml#/contact' + insurance: + $ref: 'PatIdentity.yaml#/insurance' + patid: + $ref: 'PatIdentity.yaml#/patid' + patUnid: + $ref: 'PatIdentity.yaml#/patUnid' + startDate: + $ref: 'PatIdentity.yaml#/startDate' + endDate: + $ref: 'PatIdentity.yaml#/endDate' + endReason: + $ref: '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 \ No newline at end of file diff --git a/zoo-api.yaml b/zoo-api.yaml index bd23cf7..285bab0 100644 --- a/zoo-api.yaml +++ b/zoo-api.yaml @@ -50,6 +50,8 @@ paths: $ref: 'paths/patient_base.yaml' /patient/fundusByGroup: $ref: 'paths/patient_fundusByGroup.yaml' + /patient/fundusByPractice: + $ref: 'paths/patient_fundusByPractice.yaml' /population/statistics: $ref: 'paths/population_statistics.yaml' /population/statistics/deprivedNeighborhood: