From 7dfcb5271d1c335f9ce8e4610246f33f28fff5d9 Mon Sep 17 00:00:00 2001 From: Reinier Zwitserloot Date: Mon, 25 Mar 2024 04:21:52 +0100 Subject: [PATCH] [lint] Clean up some lint errors and move some common defs into separate schema files --- paths/patient_base.yaml | 3 ++ paths/patient_dossier.yaml | 3 ++ schemas/PatIdentity.yaml | 91 +++----------------------------------- schemas/pat-BSN.yaml | 8 ++++ schemas/pat-DOB.yaml | 9 ++++ schemas/pat-Name.yaml | 50 +++++++++++++++++++++ schemas/pat-patId.yaml | 15 +++++++ schemas/pat-patUnid.yaml | 7 +++ 8 files changed, 100 insertions(+), 86 deletions(-) create mode 100644 schemas/pat-BSN.yaml create mode 100644 schemas/pat-DOB.yaml create mode 100644 schemas/pat-Name.yaml create mode 100644 schemas/pat-patId.yaml create mode 100644 schemas/pat-patUnid.yaml diff --git a/paths/patient_base.yaml b/paths/patient_base.yaml index b67c3a9..c73ffea 100644 --- a/paths/patient_base.yaml +++ b/paths/patient_base.yaml @@ -9,6 +9,9 @@ get: 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 - name: bsn in: query description: |- diff --git a/paths/patient_dossier.yaml b/paths/patient_dossier.yaml index 211a1a8..aa00d4b 100644 --- a/paths/patient_dossier.yaml +++ b/paths/patient_dossier.yaml @@ -19,6 +19,9 @@ get: 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 - name: bsn in: query description: |- diff --git a/schemas/PatIdentity.yaml b/schemas/PatIdentity.yaml index 62ef477..d63419d 100644 --- a/schemas/PatIdentity.yaml +++ b/schemas/PatIdentity.yaml @@ -1,63 +1,7 @@ bsn: - description: |- - 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; 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 - example: 123456789 + $ref: 'pat-BSN.yaml' name: - description: All relevant info about the patient's name. - type: object - properties: - firstname: - description: |- - Patient's first name(s), separated by spaces. - - It's possible that no first names are known and instead only initials are known; in that case, - the initials are provided with dots (`.`) in between the letters, e.g. `"J.M."`. - type: string - example: Marie Antoinnette - initials: - description: |- - Patient's initials, with no separators. - - Initials might be derived from a patient's first name if initials weren't explicitly provided by - the source. - type: string - example: MA - infix_own: - 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: - 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: - 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: - 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. - - This API does not provide an indication about how this person prefers to be addressed. Culturally it - is customary for this person to be addressed by their own first name followed by their partner's - infix and last name if present, and their own if not. - type: string - example: Dussen - default: "" + $ref: 'pat-Name.yaml' gender: description: |- Patient's gender. `M` = male, `V` = female, `O` = other/unknown. @@ -70,14 +14,7 @@ gender: - V - O dob: - description: |- - Patient's date of birth. - - Note that by convention, patients whose birthdate is unknown (rare, but can happen in certain asylum seeker cases) - 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 + $ref: 'pat-DOB.yaml' category: description: |- The status of the patient's registration within this practice. @@ -182,27 +119,9 @@ insurance: type: number example: 101 patid: - description: |- - Patient's "public" ID, as used and shown on the HIS patient page. Not necessarily unique, - and not necessarily present; 0 indicates no patid is known or this HIS does not use (numeric) - public IDs. - - The primary purpose of this field is to show it to medical professionals working at this practice - who can use it to search for this dossier and is a way to communicate without sharing privacy-sensitive - details. - - 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 - example: 1234 + $ref: 'pat-patId.yaml' pat_unid: - description: |- - Patient's unique and persistent ID in HIS. Usually identical to `patid` but certain HISes may - use UUID, or has globally unique keys (e.g. very large numbers). Can be blank, but only - if supplying HIS does not send them. - type: string - example: 1234 + $ref: 'pat-patUnid.yaml' start_date: type: string format: date diff --git a/schemas/pat-BSN.yaml b/schemas/pat-BSN.yaml new file mode 100644 index 0000000..c9c97d6 --- /dev/null +++ b/schemas/pat-BSN.yaml @@ -0,0 +1,8 @@ +description: |- + 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; 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 +example: 123456789 diff --git a/schemas/pat-DOB.yaml b/schemas/pat-DOB.yaml new file mode 100644 index 0000000..7c19823 --- /dev/null +++ b/schemas/pat-DOB.yaml @@ -0,0 +1,9 @@ +description: |- + Patient's date of birth. + + Note that by convention, patients whose birthdate is unknown (rare, but can happen in certain asylum seeker cases) + 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 + diff --git a/schemas/pat-Name.yaml b/schemas/pat-Name.yaml new file mode 100644 index 0000000..e22bc6b --- /dev/null +++ b/schemas/pat-Name.yaml @@ -0,0 +1,50 @@ +description: All relevant info about the patient's name. +type: object +properties: + firstname: + description: |- + Patient's first name(s), separated by spaces. + + It's possible that no first names are known and instead only initials are known; in that case, + the initials are provided with dots (`.`) in between the letters, e.g. `"J.M."`. + type: string + example: Marie Antoinnette + initials: + description: |- + Patient's initials, with no separators. + + Initials might be derived from a patient's first name if initials weren't explicitly provided by + the source. + type: string + example: MA + infix_own: + 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: + 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: + 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: + 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. + + This API does not provide an indication about how this person prefers to be addressed. Culturally it + is customary for this person to be addressed by their own first name followed by their partner's + infix and last name if present, and their own if not. + type: string + example: Dussen + default: "" diff --git a/schemas/pat-patId.yaml b/schemas/pat-patId.yaml new file mode 100644 index 0000000..a56af01 --- /dev/null +++ b/schemas/pat-patId.yaml @@ -0,0 +1,15 @@ +description: |- + Patient's "public" ID, as used and shown on the HIS patient page. Not necessarily unique, + and not necessarily present; 0 indicates no patid is known or this HIS does not use (numeric) + public IDs. + + The primary purpose of this field is to show it to medical professionals working at this practice + who can use it to search for this dossier and is a way to communicate without sharing privacy-sensitive + details. + + 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 +example: 1234 + diff --git a/schemas/pat-patUnid.yaml b/schemas/pat-patUnid.yaml new file mode 100644 index 0000000..befb2ef --- /dev/null +++ b/schemas/pat-patUnid.yaml @@ -0,0 +1,7 @@ +description: |- + Patient's unique and persistent ID in HIS. Usually identical to `patid` but certain HISes may + use UUID, or has globally unique keys (e.g. very large numbers). Can be blank, but only + if supplying HIS does not send them. +type: string +example: 1234 +