[#61] Review dosage text and instruction fields to align with what wa…

…s agreed with implementers

input/fsh/instance/medication_dispense.fsh

@@ -32,6 +32,7 @@ Usage: #example
 * dosageInstruction[baseEntry].doseAndRate.doseRange.low = 0.5 http://snomed.info/sct#732936001 "Tablet (unit of presentation)"
 * dosageInstruction[baseEntry].doseAndRate.doseRange.high = 1 http://snomed.info/sct#732936001 "Tablet (unit of presentation)"
 * dosageInstruction[baseEntry].timing.repeat.boundsPeriod.start = "2023-04-11"
+* dosageInstruction[baseEntry].text = "Un demi comprimé ou un comprimé entier à avaler et prendre avec de l'eau tous les midis dès le 2023-04-11."
 
 Instance: MedicationDispenseTriatecPml
 InstanceOf: CHEMEDEPRMedicationDispenseList
@@ -67,3 +68,4 @@ Usage: #example
 * dosageInstruction[baseEntry].doseAndRate.doseRange.low = 0.5 http://snomed.info/sct#732936001 "Tablet (unit of presentation)"
 * dosageInstruction[baseEntry].doseAndRate.doseRange.high = 1 http://snomed.info/sct#732936001 "Tablet (unit of presentation)"
 * dosageInstruction[baseEntry].timing.repeat.boundsPeriod.start = "2023-04-11"
+* dosageInstruction[baseEntry].text = "Un demi comprimé ou un comprimé entier à avaler et prendre avec de l'eau tous les midis dès le 2023-04-11."

input/fsh/instance/medication_request.fsh

@@ -26,6 +26,7 @@ Usage: #example
 * dosageInstruction[baseEntry].doseAndRate.doseRange.low = 0.5 http://snomed.info/sct#732936001 "Tablet (unit of presentation)"
 * dosageInstruction[baseEntry].doseAndRate.doseRange.high = 1 http://snomed.info/sct#732936001 "Tablet (unit of presentation)"
 * dosageInstruction[baseEntry].timing.repeat.boundsPeriod.start = "2023-04-11"
+* dosageInstruction[baseEntry].text = "Un demi comprimé ou un comprimé entier à avaler avec de l'eau le soir dès le 2023-04-11."
 
 Instance: MedicationRequestTriatecPml
 InstanceOf: CHEMEDEPRMedicationRequestList
@@ -62,6 +63,7 @@ Usage: #example
 * dosageInstruction[baseEntry].doseAndRate.doseRange.low = 0.5 http://snomed.info/sct#732936001 "Tablet (unit of presentation)"
 * dosageInstruction[baseEntry].doseAndRate.doseRange.high = 1 http://snomed.info/sct#732936001 "Tablet (unit of presentation)"
 * dosageInstruction[baseEntry].timing.repeat.boundsPeriod.start = "2023-04-11"
+* dosageInstruction[baseEntry].text = "Un demi comprimé ou un comprimé entier à avaler avec de l'eau le soir dès le 2023-04-11."
 
 Instance: MedicationRequestParacetamolAxapharmPre
 InstanceOf: CHEMEDEPRMedicationRequest
@@ -96,6 +98,7 @@ Usage: #example
 * dosageInstruction[baseEntry].route = $edqm#20053000 "Oral use"
 * dosageInstruction[baseEntry].route.text = "À avaler"
 * dosageInstruction[baseEntry].doseAndRate.doseQuantity = 1 $sct#732936001 "comprimé"
+* dosageInstruction[baseEntry].text = "Un comprimé à avaler et prendre pendant les repas avec de l'eau le matin, le midi et le soir du 2023-10-01 au 2024-01-05."
 
 Instance: MedicationRequestDafalganEffPre
 InstanceOf: CHEMEDEPRMedicationRequest
@@ -126,4 +129,5 @@ Usage: #example
 * dosageInstruction[baseEntry].route = $edqm#20053000 "Oral use"
 * dosageInstruction[baseEntry].route.text = "À avaler"
 * dosageInstruction[baseEntry].doseAndRate.doseQuantity = 2 $sct#732936001 "comprimé"
+* dosageInstruction[baseEntry].text = "À avaler: 2 comprimés le matin et 2 comprimés le soir du 2024-10-04 au 2024-02-10."
 * note.text = "Difficulté à prendre le comprimé pelliculé, substitution par un comprimé effervescent."

input/fsh/instance/medication_statement.fsh

@@ -15,6 +15,7 @@ Usage: #example
 * dosage[baseEntry].route.text = "À avaler"
 * dosage[baseEntry].doseAndRate.doseQuantity = 0.5 http://snomed.info/sct#732936001 "Tablet (unit of presentation)"
 * dosage[baseEntry].timing.repeat.boundsPeriod.start = "2023-04-11"
+* dosage[baseEntry].text = "Un demi comprimé à avaler et prendre avec de l'eau tous les midis dès le 2023-04-11."
 * dateAsserted = "2023-04-11"
 * informationSource = Reference(urn:uuid:213d609a-1164-459a-bb10-727516ae3d0c)
 
@@ -43,6 +44,7 @@ Usage: #example
 * dosage[baseEntry].route = $edqm#20053000 "Oral use"
 * dosage[baseEntry].route.text = "À avaler"
 * dosage[baseEntry].doseAndRate.doseQuantity = 1 $sct#732936001 "comprimé"
+* dosage[baseEntry].text = "Un comprimé à avaler pendant les repas avec de l'eau le matin, le midi et le soir du 2023-10-01 au 2024-01-05."
 
 Instance: MedicationStatementParacetamolAxapharmPmlc
 InstanceOf: CHEMEDEPRMedicationStatementCard
@@ -85,6 +87,7 @@ Usage: #example
 * dosage[baseEntry].route = $edqm#20053000 "Oral use"
 * dosage[baseEntry].route.text = "À avaler"
 * dosage[baseEntry].doseAndRate.doseQuantity = 1 $sct#732936001 "comprimé"
+* dosage[baseEntry].text = "Un comprimé à avaler pendant les repas avec de l'eau le matin, le midi et le soir du 2023-10-01 au 2024-01-05."
 
 Instance: MedicationStatementParacetamolDafalganEffMtp
 InstanceOf: CHEMEDEPRMedicationStatement
@@ -108,6 +111,7 @@ Usage: #example
 * dosage[baseEntry].route = $edqm#20053000 "Oral use"
 * dosage[baseEntry].route.text = "À avaler"
 * dosage[baseEntry].doseAndRate.doseQuantity = 2 $sct#732936001 "comprimé"
+* dosage[baseEntry].text = "2 comprimés à avaler le matin et 2 comprimés le soir, du 2023-10-04 au 2024-02-10."
 
 Instance: MedicationStatementParacetamolDafalganEffPmlc
 InstanceOf: CHEMEDEPRMedicationStatementCard
@@ -147,6 +151,7 @@ Usage: #example
 * dosage[baseEntry].route = $edqm#20053000 "Oral use"
 * dosage[baseEntry].route.text = "À avaler"
 * dosage[baseEntry].doseAndRate.doseQuantity = 2 $sct#732936001 "comprimé"
+* dosage[baseEntry].text = "2 comprimés à avaler le matin et 2 comprimés le soir, du 2023-10-04 au 2024-02-10."
 
 Instance: MedicationStatementDafalganEffSplitDose
 // this entry is not part of any document / use case
@@ -175,7 +180,7 @@ Usage: #example
 * dosage[baseEntry].route = $edqm#20053000 "Oral use"
 * dosage[baseEntry].route.text = "À avaler"
 * dosage[baseEntry].doseAndRate.doseQuantity = 2 $sct#732936001 "comprimé"
-* dosage[baseEntry].text = "Dafalgan: 2 comprimés à avaler le matin et 1 comprimé à avaler le soir."
+* dosage[baseEntry].text = "2 comprimés à avaler le matin et 1 comprimé à avaler le soir."
 * dosage[baseEntry].sequence = 1
 * dosage[additionalEntry].sequence = 2
 * dosage[additionalEntry].timing.repeat.when[+] = #EVE

input/fsh/instance/medication_statement_changed.fsh

@@ -19,3 +19,4 @@ Usage: #example
 * dosage[baseEntry].doseAndRate.doseRange.low = 0.5 http://snomed.info/sct#732936001 "Tablet (unit of presentation)"
 * dosage[baseEntry].doseAndRate.doseRange.high = 1 http://snomed.info/sct#732936001 "Tablet (unit of presentation)"
 * dosage[baseEntry].timing.repeat.boundsPeriod.start = "2023-04-11"
+* dosage[baseEntry].text = "Un demi comprimé ou un comprimé entier à avaler avec de l'eau le soir dès le 2023-04-11."

input/fsh/instance/padv2.fsh

@@ -76,3 +76,4 @@ Usage: #inline
 * dosageInstruction[baseEntry].doseAndRate.doseRange.low = 0.5 http://snomed.info/sct#732936001 "Tablet (unit of presentation)"
 * dosageInstruction[baseEntry].doseAndRate.doseRange.high = 1 http://snomed.info/sct#732936001 "Tablet (unit of presentation)"
 * dosageInstruction[baseEntry].timing.repeat.boundsPeriod.start = "2023-04-20"
+* dosageInstruction[baseEntry].text = "Un demi comprimé ou un comprimé entier à avaler avec de l'eau le midi dès le 2023-04-20."

input/fsh/instance/pml1.fsh

@@ -154,4 +154,5 @@ Usage: #inline
 * informationSource.reference = "#practitioner-role-1"
 * dosage[baseEntry].id = "#dosage-1"
 * dosage[baseEntry].patientInstruction = "À prendre avec de l'eau"
+* dosage[baseEntry].text = "À prendre avec de l'eau"
 * dateAsserted = "2023-04-11"

input/fsh/instance/pmlc1.fsh

@@ -163,6 +163,7 @@ Usage: #inline
 * informationSource.reference = "#practitioner-role-1"
 * dosage[baseEntry].id = "#dosage-1"
 * dosage[baseEntry].patientInstruction = "À prendre avec de l'eau"
+* dosage[baseEntry].text = "À prendre avec de l'eau"
 * dateAsserted = "2023-04-11"
 
 Instance: Inline-Instance-for-pmlc1-6

input/fsh/structuredefinition/dosage.fsh

@@ -33,6 +33,14 @@ RuleSet: main-dosage-ruleset
 * method insert codeableconcept-with-text-ruleset
 * route.text 1..1 // TODO #16
 * site.text 1..1 // TODO #16
+* text MS
+* text ^short = "Narrative representation of the full dosage (including split dosage elements if they exist) information. SHOULD be provided."
+* text ^definition = "Narrative representation of the full dosage information, including any split dosage elements if they exist. The aim is to provide the whole content of the dosage (whether structured or not) in a human readable fashion."
+* text ^comment = "This field is expected to be always populated."
+* obeys base-dosage-text
+* patientInstruction ^definition = "Dosage information as free text in terms that are understood by the patient or consumer. Any information that cannot be provided in a structured way, other than in Dosage.additionalInstruction, SHALL be provided here and, OPTIONALLY, coded in additionalInstruction."
+* patientInstruction ^comment = "Any information provided in patientInstruction SHALL be present in Dosage.text and, optionally, in Dosage.additionalInstruction."
+* additionalInstruction ^comment = "Any information provided in additionalInstruction SHALL be present in both Dosage.text and Dosage.patientInstruction."
 
 
 RuleSet: split-dosage-ruleset
@@ -55,6 +63,11 @@ RuleSet: common-dosage-ruleset
 * doseAndRate.rateRatio only CHEMEDEPRRatioAmountPerTime
 * timing.repeat.bounds[x] only Period
 
+Invariant: base-dosage-text
+Description: "It is a strong recommendation that the base dosage should contain the whole dosage information as narrative, including the information from split dosage elements."
+Expression: "text.exists() and text.trim().length() > 0"
+Severity: #warning
+
 
 Invariant: only-standard-event-timings
 Description: "The timing event shall only be 'MORN', 'NOON', 'EVE' or 'NIGHT'."

input/pagecontent/changelog.md

@@ -13,6 +13,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Replace `{Piece}` unit code with SCT `246205007` (`Quantity`) in `CHEMEDEPRAmountQuantityUnitCode` and in the `MedicationWithTwoIngredients` example.
 - Fixed cardinality of PMLC medication statement (`CHEMEDEPRMedicationStatementCard`) extension `lastConsideredDocument`, added with CH EMED 5.0.0, to `1..1` and added it to the IG examples.
 - Added _nanomole_ and _Application_ units to the `CHEMEDEPRAmountQuantityUnitCode` value set.
+- Added `base-dosage-text` invariant to base `main-dosage-ruleset`, hence to `CHEMEDEPRDosage` and `CHEMEDEPRDosageMedicationRequest` profiles. This invariant produces a warning if the `Dosage.text` is missing or blank. Updated all affected dosage examples to include `.text`.
+- Updated the descriptions of `CHEMEDEPRDosage` and `CHEMEDEPRDosageMedicationRequest` `.text`, `.additionalInstruction`, and `.patientInstruction` fields to reflect the changes proposed in https://github.com/CARA-ch/ch-emed-epr/issues/61.
 - Updated dependencies to:
   - CH EMED 5.0.0
   - CH Core 5.0.0