From a1ea93e40ac344a815ae59077dd3bde7d508e1ad Mon Sep 17 00:00:00 2001 From: Reinier Zwitserloot Date: Tue, 11 Apr 2023 08:01:48 +0200 Subject: [PATCH] [apidoc] Some minor changes /patient/base, also added examples --- examples/patient_base-examples.json | 102 ++++++++++++++++++++++++++++ zoo-api.yaml | 77 ++++++++++++--------- 2 files changed, 148 insertions(+), 31 deletions(-) create mode 100644 examples/patient_base-examples.json diff --git a/examples/patient_base-examples.json b/examples/patient_base-examples.json new file mode 100644 index 0000000..4347d4a --- /dev/null +++ b/examples/patient_base-examples.json @@ -0,0 +1,102 @@ +# A simple patient +{ + "bsn": 123451111, + "name": { + "firstname": "Marie Antoinette", + "initials": "MA", + "infix_own": "de", + "own_lastname": "Villepin", + "infix_partner": "van der", + "partner_lastname": "Dussen" + }, + "gender": "V", + "dob": "1970-07-01", + "category": "V", + "doctor": 1051234, + "address": { + "street": "Lange Geer", + "housenumber": 4, + "housenumber_suffix": "A", + "postcode": "2611PV", + "city": "Delft" + }, + "contact": { + "tel": [ + "+31612345678", + "+31701234567" + ], + "email": [ + "marie.de.villepin@example.tld" + ] + }, + "insurance": { + "policy_number": "123456789012345", + "uzovi": 3331 + }, + "patid": 1234, + "pat_unid": "1234", + "start_date": "1994-08-20" +} + +# Fairly minimal patient. Not insured, no contact info, no first name, no address info, etc. +{ + "bsn": 123451112, + "name": { + "firstname": "J.J.", + "initials": "JJ", + "own_lastname": "Jansen" + }, + "gender": "M", + "category": "V", + "doctor": 1051234, + "contact": { + "tel": [ + ], + "email": [ + ] + }, + "patid": 1235, + "pat_unid": "1235", + "start_date": "1900-01-01" +} + +# Patient that has passed away +{ + "bsn": 123451113, + "name": { + "firstname": "Abe", + "initials": "AGM", + "own_lastname": "Lincoln", + "infix_partner": "van", + "partner_lastname": "Dijk" + }, + "gender": "M", + "dob": "1990-12-20", + "category": "V", + "doctor": 1051234, + "address": { + "street": "Dorpsstraat", + "housenumber": 1, + "housenumber_suffix": "-15", + "postcode": "9999AA", + "city": "Duckstad" + }, + "contact": { + "tel": [ + "+31201234567" + ], + "email": [ + "stovepipe@example.tld" + ] + }, + "insurance": { + "policy_number": "123456789012345", + "uzovi": 101 + }, + "patid": 1236, + "pat_unid": "123e4567-e89b-12d3-a456-426614174000", + "start_date": "1997-01-01", + "end_date": "2023-01-05", + "end_reason": "O" +} + diff --git a/zoo-api.yaml b/zoo-api.yaml index bbe9780..5e33dcc 100644 --- a/zoo-api.yaml +++ b/zoo-api.yaml @@ -191,12 +191,22 @@ paths: application/json: schema: type: object + required: + - bsn + - name + - gender + - contact + - patid + - pat_unid + - category + - start_date properties: bsn: description: |- - Patient SSN (dutch: _BSN_). Always 9 digits, left-0-padded if necessary. - If unknown or left blank, will be 9 zeroes. - type: string + Patient SSN (dutch: _BSN_). If not known or patient has no BSN, this value will be `0`. + It is customary that BSNs are 9 digits; API caller 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 example: 123456789 name: description: All relevant info about the patient's name. @@ -251,25 +261,41 @@ paths: dob: description: |- Patient's date of birth. - Note that by convention, patients whose birthdate is unknown pick a date and tend to pick either `xxxx-01-01` or `xxxx-07-01`. Can, in rare cases, be blank - if birth date is not known. + Note that by convention, patients whose birthdate is unknown 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. type: string format: date example: 1970-07-01 + category: + description: |- + The status of the patient's registration within this practice. + As per [NHG-table-5](https://referentiemodel.nhg.org/sites/default/files/NHG-Tabel%205-Categorie%20pati%C3%ABnt-versie-5-Inkijkexemplaar_1.pdf): + - `V` = Standard patient, part of the GP's population (dutch: _vast_). + - `T` = Temporary patient (likely do _not_ treat as part of GP's population). + - `P` = Opportunity patient (dutch: _passant_ - patient is not signed up with this GP. For example: tourist). + type: string + example: V + doctor: + description: |- + If known, the AGB code of the primary care GP (dutch: _Inschrijf arts_). Value 0 indicates + this HIS or practice doesn't assign patients to individual GPs, or this information isn't + known. + type: number + example: 1051234 address: - description: Patient's address (where they live). + description: Patient's address (where they live). If not known, this property will not be in the response. type: object properties: street: - description: Full name of the street; can be blank if not known or not provided, and excludes house number. + description: Full name of the street, excluding house number. type: string example: Lange Geer - hn: + housenumber: description: |- Just the house number; 0 if unknown or in the exotic case where no house number exists. This does not include any addendums such as 'A' or 'room 15'. Guaranteed to be non-negative. type: integer example: 4 - hn_suffix: + housenumber_suffix: description: |- Often empty, the string that follows the numeric part of the address house number. For example, `"A"`, or `"k22"`. @@ -304,19 +330,23 @@ paths: type: string example: ["info@zorgoporde.nl"] insurance: + description: |- + Info about where the patient is insured. If patient is not insured, this field will not be present. + Only the main insurance used for reimbursement of GP costs will be returned, if any such insurance exists. + type: object properties: policy_number: description: |- - Patient's insurance registration number (dutch: _polisnummer_). If not known or not insured, a blank string. + Patient's insurance registration number (dutch: _polisnummer_). type: string example: 123456789012345 uzovi: description: |- Insurer's identity number in the dutch insurance system (dutch: _UZOVI nummer_). Always 4 digits exactly, 0-left-padded if needed. If unknown or not insured, 4 zeroes. - type: string - example: 3331 + type: number + example: 101 patid: description: |- Patient's "public" ID, as used and shown on the HIS patient page. Not necessarily unique, @@ -335,10 +365,11 @@ paths: type: string format: date description: |- - Date patient joined the practice (dutch: _inschrijf datum_). If blank, patient joined a - long time ago. By convention if programming a system that requires a value, a sentinel - value of `"1900-01-01"` is suggested for this case. (when reading from this API, map - the empty string onto that date if you prefer not having blank/NULL values). + Date patient joined the practice (dutch: _inschrijf datum_). + In rare cases, a patient joined so long ago, this date is no longer known. In this case, + a sentinel value of `"1900-01-01"` is sent which is presumed to result in the desired behaviour + (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: type: string @@ -360,22 +391,6 @@ paths: - `X` = Other type: string example: "" - doctor: - description: |- - If known, the AGB code of the primary care GP (dutch: _Inschrijf arts_). Value 0 indicates - this HIS or practice doesn't assign patients to individual GPs, or this information isn't - known. - type: number - example: 1051234 - category: - description: |- - The status of the patient's registration within this practice. - As per [NHG-table-5](https://referentiemodel.nhg.org/sites/default/files/NHG-Tabel%205-Categorie%20pati%C3%ABnt-versie-5-Inkijkexemplaar_1.pdf): - - `V` = Standard patient, part of the GP's population (dutch: _vast_). - - `T` = Temporary patient (likely do _not_ treat as part of GP's population). - - `P` = Opportunity patient (dutch: _passant_ - patient is not signed up with this GP. For example: tourist). - type: string - example: V '400': description: The request is invalid; for example, it doesn't contain the required `BSN` parameter. '401':