[lint] Clean up some lint errors and move some common defs into separate schema files

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: |-

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: |-

schemas/PatIdentity.yaml

@@ -1,63 +1,7 @@
 bsn:
-  description: |-
+  $ref: 'pat-BSN.yaml'
-    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
 name:
-  description: All relevant info about the patient's name.
+  $ref: 'pat-Name.yaml'
-  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: ""
 gender:
   description: |-
     Patient's gender. `M` = male, `V` = female, `O` = other/unknown.
@@ -70,14 +14,7 @@ gender:
     - V
     - O
 dob:
-  description: |-
+  $ref: 'pat-DOB.yaml'
-    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
 category:
   description: |-
     The status of the patient's registration within this practice.
@@ -182,27 +119,9 @@ insurance:
       type: number
       example: 101
 patid:
-  description: |-
+  $ref: 'pat-patId.yaml'
-    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
 pat_unid:
-  description: |-
+  $ref: 'pat-patUnid.yaml'
-    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
 start_date:
   type: string
   format: date

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

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
+

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: ""

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
+

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
+