Implementation guide for interoperable medicines

This guidance is under active development by NHS England and content may be added or updated on a regular basis.

Element: text

IMPORTANT: This guidance differs from the international FHIR specification. The FHIR standard is ambiguous with contradictory statements for what may or may not be contained within the text element.
Recommendation: We recommend text is populated with a textual representation of the complete dosage instruction, in terms understood by a healthcare professional, excluding;
  • Name or description of the medication (Note 1)
  • Problem or condition to which the medicine relates (Note 2)
  • Any patientInstruction string (Note 3)

    • This approach allows the text to be safely used by clinical systems that cannot (yet) consume the complete FHIR Dosage structure. All dosing instructions within text should also be contained within the relevant structured elements of the FHIR Dosage to allow the clinical system to consume the FHIR Dosage without requiring the human user to interpret the contents of text.

    Note 1: The name or description of the medication is conveyed as a codeableConcept or referenced Medication resource in the resource that contains the Dosage structure.

    Note 2: The reason for medication is conveyed within the reasonCode or reasonReference within the MedicationRequest and MedicationStatement resources.

    Note 3: The patientInstruction element contains equivalent information to text but in terms that are understood by the patient or consumer so should not be repeated within text.

    Exception: EPS FHIR Facade Implementation
    An exception to note 2 above relates to the current implementation of the Electronic Prescription Service - FHIR API. The text may be appended with the reason for the medication (indication). The current implementation of the EPS converts the FHIR payload to HL7v3 for backwards compatibility. Wthin the HL7v3 data model, there is nowhere to hold the indication other than as an appendment to the free-text dosage instruction.

    The textual representation must align with what the clinical user selects or sees on-screen. A textual and clinical equivalent of every element within the Dosage structure, excluding text, must be contained within text, with the exception of any patientInstruction string.

    This approach allows clinically safe dosage interoperability between systems that do and do not support the full Dosage structure. A consumer system that can only handle a dosage text string will consume text and ignore all other elements of the Dosage structure. A provider system that can only handle a dosage text string will only populate the text element of the Dosage structure.

    The approach we recommend allows a fully FHIR-compliant consumer system to process all elements of Dosage excluding text. A system that only supports text-based dosage instructions will process only text for clinical users or patientInstruction for the patient user. Both implementations will consume an equivalent dosage instruction, albiet one as text and one that is machine readable.

    Implementation Example A

    A provider system allows the user to pick an order sentence, e.g. “Two tablet(s), two times a day, with food. Please do not chew the tablets”. This string goes into text and in the background, the provider system constructs the coded Dosage structure.

    <dosageInstruction>
     <text value="Two tablet(s), two times a day, with food. Please do not chew the tablets" />
     <timing>
          <repeat>
              <frequency value="2" />
              <period value="1" />
              <periodUnit value="d" />
              <when value="C"/>
          </repeat>
     </timing>
     <doseAndRate>
          <doseQuantity>
              <value value="2" />
              <unit value="tablet" />
              <system value="http://snomed.info/sct" />
              <code value="428673006" />
          </doseQuantity>
     </doseAndRate>
     <additionalInstruction>
         <text value=”Please do not chew the tablets” />
     </additionalInstruction>
</dosageInstruction>

    Implementation Example B

    A provider system allows the user to construct a dosage instruction using various user interface components. The system translatesAd the coded information into a text string for text. Refer to our translation algorithm for guidance for such a translation. In the background, the provider system constructs the coded Dosage structure.

    <dosageInstruction>
     <text value="2 tablets - twice a day – at a meal - Please do not chew the tablets" />
     <timing>
          <repeat>
              <frequency value="2" />
              <period value="1" />
              <periodUnit value="d" />
              <when value="C"/>
          </repeat>
     </timing>
     <doseAndRate>
          <doseQuantity>
              <value value="2" />
              <unit value="tablet" />
              <system value="http://snomed.info/sct" />
              <code value="428673006" />
          </doseQuantity>
     </doseAndRate>
     <additionalInstruction>
         <text value=”Please do not chew the tablets” />
     </additionalInstruction>
</dosageInstruction>
    back to top