Dose syntax implementation guidance for FHIR STU3

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

STU3 Limitations

The following edge cases have been identified which are not sufficiently supported as coded structures within the STU3 Dosage structure. Until such a time when the CareConnect FHIR profiles are updated with either an extension or an internationally agreed change to the HL7 FHIR standard, a work-around is required.

1. STU3 Limitation - Combination pack instructions

Workaround: Use a free-text `Dosage.additionalInstruction`.

It is common practice to provide a dosage instruction for the combination pack “Migraleve tablets” with instructions for when to take the pink tablets and when to take the yellow tablets. With the current STU3 Dosage structure, these instructions would have to be conveyed in free-text using the Dosage.patientInstructions.

In secondary care the individual components of the pack should be prescribed as separate items.

In primary care the combination pack is prescribed and therefore the medication request must reference the medication resource for the dm+d code of the combination product. The medication request then links to 2 dosing instructions which describe how each tablet should be taken.

<MedicationRequest xmlns="http://hl7.org/fhir">
    <id value="859e5d8a-391a-4b2a-8f29-15e8c75180bb" />
    <contained>
        <Medication>
            <id value="internalMedicationIdentifer123abc" />
            <code>
                <coding>
                    <system value="http://snomed.info/sct" />
                    <code value="3363411000001108" />
                    <display value="Migraleve tablets (McNeil Products Ltd)" />
                </coding>
            </code>
        </Medication>
    </contained>
    <status value="active" />
    <intent value="order" />
    <medicationReference>
        <reference value="#internalMedicationIdentifer123abc" />
        <display value="Migraleve tablets (McNeil Products Ltd)" />
    </medicationReference>
    <subject>
        <identifier>
            <system value="https://fhir.nhs.uk/Id/nhs-number" />
            <value value="9999999999" />
        </identifier>
    </subject>
    <dosageInstruction>
        <sequence value="1" />
        <text value="2 tablets - take once - as required when migraine occurs - Max dose 2 tablets in 24 hours - Pink tablet" />
        <additionalInstruction>
            <text value="Pink tablets" />
        </additionalInstruction>
        <timing>
            <repeat>
                <count value="1" />
            </repeat>
        </timing>
        <asNeededCodeableConcept>
            <coding>
                <system value="http://snomed.info/sct" />
                <code value="37796009" />
                <display value="Migraine" />
            </coding>
        </asNeededCodeableConcept>
        <doseQuantity>
            <value value="2" />
            <unit value="tablet" />
            <system value="http://snomed.info/sct" />
            <code value="428673006" />
        </doseQuantity>
        <maxDosePerPeriod>
            <numerator>
                <value value="2" />
                <unit value="tablet" />
                <system value="http://snomed.info/sct" />
                <code value="428673006" />
            </numerator>
            <denominator>
                <value value="24" />
                <unit value="hour" />
                <system value="http://unitsofmeasure.org" />
                <code value="h" />
            </denominator>
        </maxDosePerPeriod>
    </dosageInstruction>
    <dosageInstruction>
        <sequence value="2" />
        <text value="2 tablets - every 4 hours - as required - max dose 6 tablets in 24 hours - Yellow tablets" />
        <additionalInstruction>
            <text value="Yellow tablets" />
        </additionalInstruction>
        <timing>
            <repeat>
                <frequency value="1" />
                <period value="4" />
                <periodUnit value="h" />
            </repeat>
        </timing>
        <asNeededBoolean value="true" />
        <doseQuantity>
            <value value="2" />
            <unit value="tablet" />
            <system value="http://snomed.info/sct" />
            <code value="428673006" />
        </doseQuantity>
        <maxDosePerPeriod>
            <numerator>
                <value value="6" />
                <unit value="tablet" />
                <system value="http://snomed.info/sct" />
                <code value="428673006" />
            </numerator>
            <denominator>
                <value value="24" />
                <unit value="hour" />
                <system value="http://unitsofmeasure.org" />
                <code value="h" />
            </denominator>
        </maxDosePerPeriod>
    </dosageInstruction>
</MedicationRequest>

{
    "resourceType": "MedicationRequest",
    "id": "859e5d8a-391a-4b2a-8f29-15e8c75180bb",
    "contained":  [
        {
            "resourceType": "Medication",
            "id": "internalMedicationIdentifer123abc",
            "code": {
                "coding":  [
                    {
                        "system": "http://snomed.info/sct",
                        "code": "3363411000001108",
                        "display": "Migraleve tablets (McNeil Products Ltd)"
                    }
                ]
            }
        }
    ],
    "status": "active",
    "intent": "order",
    "medicationReference": {
        "reference": "#internalMedicationIdentifer123abc",
        "display": "Migraleve tablets (McNeil Products Ltd)"
    },
    "subject": {
        "identifier": {
            "system": "https://fhir.nhs.uk/Id/nhs-number",
            "value": "9999999999"
        }
    },
    "dosageInstruction":  [
        {
            "sequence": 1,
            "text": "2 tablets - take once - as required when migraine occurs - Max dose 2 tablets in 24 hours - Pink tablet",
            "additionalInstruction":  [
                {
                    "text": "Pink tablets"
                }
            ],
            "timing": {
                "repeat": {
                    "count": 1
                }
            },
            "asNeededCodeableConcept": {
                "coding":  [
                    {
                        "system": "http://snomed.info/sct",
                        "code": "37796009",
                        "display": "Migraine"
                    }
                ]
            },
            "doseQuantity": {
                "value": 2,
                "unit": "tablet",
                "system": "http://snomed.info/sct",
                "code": "428673006"
            },
            "maxDosePerPeriod": {
                "numerator": {
                    "value": 2,
                    "unit": "tablet",
                    "system": "http://snomed.info/sct",
                    "code": "428673006"
                },
                "denominator": {
                    "value": 24,
                    "unit": "hour",
                    "system": "http://unitsofmeasure.org",
                    "code": "h"
                }
            }
        },
        {
            "sequence": 2,
            "text": "2 tablets - every 4 hours - as required - max dose 6 tablets in 24 hours - Yellow tablets",
            "additionalInstruction":  [
                {
                    "text": "Yellow tablets"
                }
            ],
            "timing": {
                "repeat": {
                    "frequency": 1,
                    "period": 4,
                    "periodUnit": "h"
                }
            },
            "asNeededBoolean": true,
            "doseQuantity": {
                "value": 2,
                "unit": "tablet",
                "system": "http://snomed.info/sct",
                "code": "428673006"
            },
            "maxDosePerPeriod": {
                "numerator": {
                    "value": 6,
                    "unit": "tablet",
                    "system": "http://snomed.info/sct",
                    "code": "428673006"
                },
                "denominator": {
                    "value": 24,
                    "unit": "hour",
                    "system": "http://unitsofmeasure.org",
                    "code": "h"
                }
            }
        }
    ]
}
MedicationRequest.id[0]859e5d8a-391a-4b2a-8f29-15e8c75180bb
MedicationRequest.contained[0].id[0]internalMedicationIdentifer123abc
MedicationRequest.contained[0].code[0].coding[0].system[0]http://snomed.info/sct
MedicationRequest.contained[0].code[0].coding[0].code[0]3363411000001108
MedicationRequest.contained[0].code[0].coding[0].display[0]Migraleve tablets (McNeil Products Ltd)
MedicationRequest.status[0]active
MedicationRequest.intent[0]order
MedicationRequest.medication[0].reference[0]#internalMedicationIdentifer123abc
MedicationRequest.medication[0].display[0]Migraleve tablets (McNeil Products Ltd)
MedicationRequest.subject[0].identifier[0].system[0]https://fhir.nhs.uk/Id/nhs-number
MedicationRequest.subject[0].identifier[0].value[0]9999999999
MedicationRequest.dosageInstruction[0].sequence[0]1
MedicationRequest.dosageInstruction[0].text[0]2 tablets - take once - as required when migraine occurs - Max dose 2 tablets in 24 hours - Pink tablet
MedicationRequest.dosageInstruction[0].additionalInstruction[0].text[0]Pink tablets
MedicationRequest.dosageInstruction[0].timing[0].repeat[0].count[0]1
MedicationRequest.dosageInstruction[0].asNeeded[0].coding[0].system[0]http://snomed.info/sct
MedicationRequest.dosageInstruction[0].asNeeded[0].coding[0].code[0]37796009
MedicationRequest.dosageInstruction[0].asNeeded[0].coding[0].display[0]Migraine
MedicationRequest.dosageInstruction[0].dose[0].value[0]2
MedicationRequest.dosageInstruction[0].dose[0].unit[0]tablet
MedicationRequest.dosageInstruction[0].dose[0].system[0]http://snomed.info/sct
MedicationRequest.dosageInstruction[0].dose[0].code[0]428673006
MedicationRequest.dosageInstruction[0].maxDosePerPeriod[0].numerator[0].value[0]2
MedicationRequest.dosageInstruction[0].maxDosePerPeriod[0].numerator[0].unit[0]tablet
MedicationRequest.dosageInstruction[0].maxDosePerPeriod[0].numerator[0].system[0]http://snomed.info/sct
MedicationRequest.dosageInstruction[0].maxDosePerPeriod[0].numerator[0].code[0]428673006
MedicationRequest.dosageInstruction[0].maxDosePerPeriod[0].denominator[0].value[0]24
MedicationRequest.dosageInstruction[0].maxDosePerPeriod[0].denominator[0].unit[0]hour
MedicationRequest.dosageInstruction[0].maxDosePerPeriod[0].denominator[0].system[0]http://unitsofmeasure.org
MedicationRequest.dosageInstruction[0].maxDosePerPeriod[0].denominator[0].code[0]h
MedicationRequest.dosageInstruction[1].sequence[0]2
MedicationRequest.dosageInstruction[1].text[0]2 tablets - every 4 hours - as required - max dose 6 tablets in 24 hours - Yellow tablets
MedicationRequest.dosageInstruction[1].additionalInstruction[0].text[0]Yellow tablets
MedicationRequest.dosageInstruction[1].timing[0].repeat[0].frequency[0]1
MedicationRequest.dosageInstruction[1].timing[0].repeat[0].period[0]4
MedicationRequest.dosageInstruction[1].timing[0].repeat[0].periodUnit[0]h
MedicationRequest.dosageInstruction[1].asNeeded[0]True
MedicationRequest.dosageInstruction[1].dose[0].value[0]2
MedicationRequest.dosageInstruction[1].dose[0].unit[0]tablet
MedicationRequest.dosageInstruction[1].dose[0].system[0]http://snomed.info/sct
MedicationRequest.dosageInstruction[1].dose[0].code[0]428673006
MedicationRequest.dosageInstruction[1].maxDosePerPeriod[0].numerator[0].value[0]6
MedicationRequest.dosageInstruction[1].maxDosePerPeriod[0].numerator[0].unit[0]tablet
MedicationRequest.dosageInstruction[1].maxDosePerPeriod[0].numerator[0].system[0]http://snomed.info/sct
MedicationRequest.dosageInstruction[1].maxDosePerPeriod[0].numerator[0].code[0]428673006
MedicationRequest.dosageInstruction[1].maxDosePerPeriod[0].denominator[0].value[0]24
MedicationRequest.dosageInstruction[1].maxDosePerPeriod[0].denominator[0].unit[0]hour
MedicationRequest.dosageInstruction[1].maxDosePerPeriod[0].denominator[0].system[0]http://unitsofmeasure.org
MedicationRequest.dosageInstruction[1].maxDosePerPeriod[0].denominator[0].code[0]h
MedicationRequest

2. STU3 Limitation - Defining a maximum dose per course

Workaround: Use a free-text `Dosage.additionalInstruction`.

A maximum dose for three scenarios is supported within the STU3 Dosage structure;

  • maxDosePerPeriod - define a maximum dose over a given period of time
  • maxDosePerAdministration - defines a maximum dose per administration
  • maxDosePerLifetime - defines the maximum dose during the lifetime of the patient

Not currently supported is how to define a maximum dose per course.

With the current STU3 Dosage structure, a maximum dose per course would have to be conveyed in free-text using the Dosage.additionalInstruction.

<!--  Defining a maximum dose per course  -->
<!--  Example: Colchicine 500microgram tablets, 500 micrograms, 2 to 4 times a day until symptoms relieved, maximum 6 mg per course, do not repeat course within 3 days  -->
<MedicationRequest xmlns="http://hl7.org/fhir">
    <id value="f27b260e-8bdf-11eb-8dcd-0242ac130003" />
    <contained>
        <Medication>
            <id value="med1" />
            <code>
                <coding>
                    <system value="http://snomed.info/sct" />
                    <code value="330079002" />
                    <display value="Colchicine 500microgram tablets" />
                </coding>
            </code>
        </Medication>
    </contained>
    <status value="active" />
    <intent value="order" />
    <medicationReference>
        <reference value="#med1" />
    </medicationReference>
    <subject>
        <identifier>
            <system value="https://fhir.nhs.uk/Id/nhs-number" />
            <value value="9999999999" />
        </identifier>
    </subject>
    <dosageInstruction>
        <additionalInstruction>
            <text value="Maximum dose per course 6 mg" />
        </additionalInstruction>
        <additionalInstruction>
            <text value="Do not repeat course for 3 days" />
        </additionalInstruction>
        <patientInstruction value="Until symptoms relieved" />
        <timing>
            <repeat>
                <frequency value="2" />
                <frequencyMax value="4" />
                <period value="1" />
                <periodUnit value="d" />
            </repeat>
        </timing>
        <doseQuantity>
            <value value="500" />
            <unit value="microgram" />
            <system value="http://unitsofmeasure.org" />
            <code value="ug" />
        </doseQuantity>
    </dosageInstruction>
</MedicationRequest>

{
    "resourceType": "MedicationRequest",
    "id": "f27b260e-8bdf-11eb-8dcd-0242ac130003",
    "contained":  [
        {
            "resourceType": "Medication",
            "id": "med1",
            "code": {
                "coding":  [
                    {
                        "system": "http://snomed.info/sct",
                        "code": "330079002",
                        "display": "Colchicine 500microgram tablets"
                    }
                ]
            }
        }
    ],
    "status": "active",
    "intent": "order",
    "medicationReference": {
        "reference": "#med1"
    },
    "subject": {
        "identifier": {
            "system": "https://fhir.nhs.uk/Id/nhs-number",
            "value": "9999999999"
        }
    },
    "dosageInstruction":  [
        {
            "additionalInstruction":  [
                {
                    "text": "Maximum dose per course 6 mg"
                },
                {
                    "text": "Do not repeat course for 3 days"
                }
            ],
            "patientInstruction": "Until symptoms relieved",
            "timing": {
                "repeat": {
                    "frequency": 2,
                    "frequencyMax": 4,
                    "period": 1,
                    "periodUnit": "d"
                }
            },
            "doseQuantity": {
                "value": 500,
                "unit": "microgram",
                "system": "http://unitsofmeasure.org",
                "code": "ug"
            }
        }
    ]
}
MedicationRequest.id[0]f27b260e-8bdf-11eb-8dcd-0242ac130003
MedicationRequest.contained[0].id[0]med1
MedicationRequest.contained[0].code[0].coding[0].system[0]http://snomed.info/sct
MedicationRequest.contained[0].code[0].coding[0].code[0]330079002
MedicationRequest.contained[0].code[0].coding[0].display[0]Colchicine 500microgram tablets
MedicationRequest.status[0]active
MedicationRequest.intent[0]order
MedicationRequest.medication[0].reference[0]#med1
MedicationRequest.subject[0].identifier[0].system[0]https://fhir.nhs.uk/Id/nhs-number
MedicationRequest.subject[0].identifier[0].value[0]9999999999
MedicationRequest.dosageInstruction[0].additionalInstruction[0].text[0]Maximum dose per course 6 mg
MedicationRequest.dosageInstruction[0].additionalInstruction[1].text[0]Do not repeat course for 3 days
MedicationRequest.dosageInstruction[0].patientInstruction[0]Until symptoms relieved
MedicationRequest.dosageInstruction[0].timing[0].repeat[0].frequency[0]2
MedicationRequest.dosageInstruction[0].timing[0].repeat[0].frequencyMax[0]4
MedicationRequest.dosageInstruction[0].timing[0].repeat[0].period[0]1
MedicationRequest.dosageInstruction[0].timing[0].repeat[0].periodUnit[0]d
MedicationRequest.dosageInstruction[0].dose[0].value[0]500
MedicationRequest.dosageInstruction[0].dose[0].unit[0]microgram
MedicationRequest.dosageInstruction[0].dose[0].system[0]http://unitsofmeasure.org
MedicationRequest.dosageInstruction[0].dose[0].code[0]ug
MedicationRequest

3. STU3 Limitation - Cyclical prescribing - Defining a period of time where medication should not be taken

Workaround: Use a free-text `Dosage.additionalInstruction`.

The example given for the current limitation for defining a maximum dose per course also includes an instruction for a period of time where medication should not be taken. This is not directly supported within the STU3 Dosage structure.

Another clinical example would be for a Lidocaine medicated plaster. A typical written dosage instruction would be;

Apply 2 patches once daily to the affected area for up to 12 hours, followed by a 12-hour plaster-free period; to be applied to intact, dry, non-hairy, non-irritated skin.

The FHIR STU3 Dosage structure can describe all the above except for the clause “followed by a 12-hour plaster-free period”.

In a dose-based instruction this would needs to be expressed as free-text within a Dosage.additionalInstruction.

An example of a sequencial instruction can be found below.

Microgynon 30 tablets (Bayer Plc), 1 tablet, ONCE a DAY, oral, for 21 days, subsequent courses repeated after 7-day tablet-free interval

Product-based AMP prescription using additional instructions to convery pill free interval. 
<MedicationRequest xmlns="http://hl7.org/fhir">
    <id value="d4b05cfb-d444-4490-824a-67c55596c610" />
    <contained>
        <Medication>
            <id value="med1" />
            <code>
                <coding>
                    <system value="http://snomed.info/sct" />
                    <code value="42111000001107" />
                    <display value="Microgynon 30 tablets (Bayer Plc)" />
                </coding>
            </code>
        </Medication>
    </contained>
    <status value="active" />
    <intent value="order" />
    <medicationReference>
        <reference value="#med1" />
    </medicationReference>
    <subject>
        <identifier>
            <system value="https://fhir.nhs.uk/Id/nhs-number" />
            <value value="9999999999" />
        </identifier>
    </subject>
    <dosageInstruction>
        <additionalInstruction>
            <text value="subsequent courses repeated after 7-day tablet-free interval" />
        </additionalInstruction>
        <timing>
            <repeat>
                <boundsDuration>
                    <value value="21" />
                    <unit value="day" />
                    <system value="http://unitsofmeasure.org" />
                    <code value="d" />
                </boundsDuration>
                <frequency value="1" />
                <period value="1" />
                <periodUnit value="d" />
            </repeat>
        </timing>
        <route>
            <coding>
                <system value="http://snomed.info/sct" />
                <code value="26643006" />
                <display value="oral" />
            </coding>
        </route>
        <doseQuantity>
            <value value="1" />
            <unit value="tablet" />
            <system value="http://snomed.info/sct" />
            <code value="428673006" />
        </doseQuantity>
    </dosageInstruction>
</MedicationRequest>

{
    "resourceType": "MedicationRequest",
    "id": "d4b05cfb-d444-4490-824a-67c55596c610",
    "contained":  [
        {
            "resourceType": "Medication",
            "id": "med1",
            "code": {
                "coding":  [
                    {
                        "system": "http://snomed.info/sct",
                        "code": "42111000001107",
                        "display": "Microgynon 30 tablets (Bayer Plc)"
                    }
                ]
            }
        }
    ],
    "status": "active",
    "intent": "order",
    "medicationReference": {
        "reference": "#med1"
    },
    "subject": {
        "identifier": {
            "system": "https://fhir.nhs.uk/Id/nhs-number",
            "value": "9999999999"
        }
    },
    "dosageInstruction":  [
        {
            "additionalInstruction":  [
                {
                    "text": "subsequent courses repeated after 7-day tablet-free interval"
                }
            ],
            "timing": {
                "repeat": {
                    "boundsDuration": {
                        "value": 21,
                        "unit": "day",
                        "system": "http://unitsofmeasure.org",
                        "code": "d"
                    },
                    "frequency": 1,
                    "period": 1,
                    "periodUnit": "d"
                }
            },
            "route": {
                "coding":  [
                    {
                        "system": "http://snomed.info/sct",
                        "code": "26643006",
                        "display": "oral"
                    }
                ]
            },
            "doseQuantity": {
                "value": 1,
                "unit": "tablet",
                "system": "http://snomed.info/sct",
                "code": "428673006"
            }
        }
    ]
}
MedicationRequest.id[0]d4b05cfb-d444-4490-824a-67c55596c610
MedicationRequest.contained[0].id[0]med1
MedicationRequest.contained[0].code[0].coding[0].system[0]http://snomed.info/sct
MedicationRequest.contained[0].code[0].coding[0].code[0]42111000001107
MedicationRequest.contained[0].code[0].coding[0].display[0]Microgynon 30 tablets (Bayer Plc)
MedicationRequest.status[0]active
MedicationRequest.intent[0]order
MedicationRequest.medication[0].reference[0]#med1
MedicationRequest.subject[0].identifier[0].system[0]https://fhir.nhs.uk/Id/nhs-number
MedicationRequest.subject[0].identifier[0].value[0]9999999999
MedicationRequest.dosageInstruction[0].additionalInstruction[0].text[0]subsequent courses repeated after 7-day tablet-free interval
MedicationRequest.dosageInstruction[0].timing[0].repeat[0].bounds[0].value[0]21
MedicationRequest.dosageInstruction[0].timing[0].repeat[0].bounds[0].unit[0]day
MedicationRequest.dosageInstruction[0].timing[0].repeat[0].bounds[0].system[0]http://unitsofmeasure.org
MedicationRequest.dosageInstruction[0].timing[0].repeat[0].bounds[0].code[0]d
MedicationRequest.dosageInstruction[0].timing[0].repeat[0].frequency[0]1
MedicationRequest.dosageInstruction[0].timing[0].repeat[0].period[0]1
MedicationRequest.dosageInstruction[0].timing[0].repeat[0].periodUnit[0]d
MedicationRequest.dosageInstruction[0].route[0].coding[0].system[0]http://snomed.info/sct
MedicationRequest.dosageInstruction[0].route[0].coding[0].code[0]26643006
MedicationRequest.dosageInstruction[0].route[0].coding[0].display[0]oral
MedicationRequest.dosageInstruction[0].dose[0].value[0]1
MedicationRequest.dosageInstruction[0].dose[0].unit[0]tablet
MedicationRequest.dosageInstruction[0].dose[0].system[0]http://snomed.info/sct
MedicationRequest.dosageInstruction[0].dose[0].code[0]428673006
MedicationRequest

4. STU3 Limitation - Instructions for a specific device

Workaround: Use a Virtual Medicinal Product (VMP) or Actual Medicinal Product (AMP) concept, or express within a free-text `Dosage.additionalInstruction`.

In some cases, with a dose-based instruction, the type of device to use for the administration of the medication needs to be specified.

For example, Salbutamol medication may be inhaled using one of four types of device;

  • Nebuliser
  • Metered dose inhaler
  • Breath actuated inhaler
  • Dry powder inhaler

Whilst each of these devices is a coded term within SNOMED-CT, it would be potentially confusing to add a coded device as an additional instruction. None of the CareConnect profiled resources referenced within this guidance contain a structure where a coded device can be specified as part of the medication request.

Until supported via another means, where a specific type of device needs to be specified, either prescribe using a product-based dm+d concept (e.g. VMP or AMP) or specify the request for any type of device to be used as free-text within Dosage.additionalInstruction.

5. STU3 Limitation - Specifying a Trade Family / Brand

Workaround: Trade Family coded concept as the medication within FHIR profiles.

The use of a coded Trade Family (TF) as the medication item with or without identifying a dose form is supported within FHIR STU3.

It is also possible to specify a brand as the medication using an Actual Medicinal Product (AMP) concept. The use of an AMP would not only define the brand, but also the strength and form, as it is a product-based concept.

The use of a Virtual Therapeutic Moiety with Trade Family in a medication request may be required when a prescriber wishes to describe a dose-based prescription using a specific brand of medication without further specifying the product required.

FHIR STU3 does not support the use of two or more codes (e.g. VTM and TF) within a Medication resource.

back to top