[patient] Cleaned up API docs: Lessons learned whilst implementing the API endpoint

schemas/med_dossier/Correspondence.yaml

@@ -22,7 +22,7 @@ properties:
     type: string
     format: date
     example: "2023-03-31"
-  specialty_code:
+  speciality_code:
     description: |-
       A short memocode representing the speciality of `other`. For example, `"OOG"` (eye specialist), `"CHI"` (Surgery), etc. Often blank.
       
@@ -50,8 +50,8 @@ properties:
     example: "Naar: Plastische chirurgie HMC, Den Haag"
   practicioner:
     $ref: 'Practicioner.yaml'
-  zd:
+  zorgdomein:
     description: |-
-      If known and provided, The ZorgDomein message ID. ZD IDs are often used when referring a patient. Not all source systems provide these.
+      If known and provided, The ZorgDomein message ID. ZorgDomein IDs are often used when referring a patient. Not all source systems provide these.
     type: string
     example: "ZD1234"

schemas/med_dossier/Journal.yaml

@@ -30,31 +30,46 @@ properties:
     type: string
     format: date
     example: "2015-05-01"
-  text:
+  s:
     description: |-
-      The journal text as typed by the practicioner. Can, obviously, be quite long, and can contain newlines.
+      The journal text as typed by the practicioner for the 'S' field of SOAP (Subjective / Objective / Analysis / Plan). (Dutch: _S_ / _Subjectief_).
+      
+      A (transcription of the) description of the medical issue by the patient themselves.
+      
+      Can contain newlines, and can be quite long. For teleconsulting often contains everything the patient typed.
+    type: string
+  o:
+    description: |-
+      The journal text as typed by the practicioner for the 'O' field of SOAP (Subjective / Objective / Analysis / Plan). (Dutch: _O_ / _Objectief_).
+      
+      The description of the medical issue as observed by a trained medical practicioner.
+      
+      Can contain newlines, and can be quite long. For teleconsulting in particular, might be empty.
+    type: string
+  a:
+    description: |-
+      The journal text as typed by the practicioner for the 'A' field of SOAP (Subjective / Objective / Analysis / Plan). (Dutch: _E_ / _Evaluatie_).
+      
+      The diagnosis.
+      
+      Can contain newlines, and can be quite long.
+    type: string
+  p:
+    description: |-
+      The journal text as typed by the practicioner for the 'P' field of SOAP (Subjective / Objective / Analysis / Plan). (Dutch: _P_ / _Plan_).
+      
+      The course of action to take, or notes about next steps to deal with the issue raised in this journal entry.
+      
+      Can contain newlines, and can be quite long.
     type: string
-  soap:
+  x:
     description: |-
-      Most medical systems separate journal text using the SOAP system (dutch: _SOEP_):
-      * `S`: Subjective (dutch: _Subjectief_) - A (transcription of the) description of the medical issue by the patient themselves
-      * `O`: Objective (dutch: _Objectief_) - The description of the medical issue as observed by a trained medical practicioner
-      * `A`: Analysis (dutch: _Evaluatie_) - The diagnosis.
-      * `P`: Plan (dutch: _Plan_) - The course of action to take, or notes about next steps to deal with the issue raised in this journal entry.
-      * `X`: Unknown - this text does not fit any of the 4 SOAP categories, or this represents journal text not written using the SOAP system.
+      The journal text as typed by the practicioner for any non-SOAP field.
       
-      Any of these can be missing. For example, for tele-health various practices have internal policy to leave Objective blank, especially if
-      no video or pictures are made, because no medical professional is on hand to make an objective report about the stated issues.
+      Will be omitted if blank / not available. For source systems that do not work with the SOAP methodology, all journal text will be under this entry.
       
-      Often newlines appear in weird places, or newlines are not conveyed even if typed by the practicioner; these are limitations in the source system.
+      Can contain newlines, and can be quite long.
     type: string
-    enum:
-      - S
-      - O
-      - A
-      - P
-      - X
-    example: S
   practicioner:
     $ref: 'Practicioner.yaml'
   type:

schemas/med_dossier/Measurement.yaml

@@ -50,12 +50,6 @@ properties:
       of what the source has provided.
     type: string
     example: 48
-  source_value:
-    description: |-
-      *OPTIONAL* The value of the measurement as reported by the source, verbatim (no normalization is applied in any way).
-      Only provided if meaningfully different from the normalized value.
-    type: string
-    example: HUISARTS
   comment:
     description: |-
       *OPTIONAL* Some source systems allow adding a comment to any measurement; if one is present, it is provided here.