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.

Translation Logic: Dosage Structure

Element: method

No additional formatting required.

Element: doseQuantity

Express as:

{quantity} {units}

  • 50 milligram

  • 2 tablets

Element: doseRange

Express as:

{low_quantity} to {high_quantity} {high_units}

  • 20 to 40 millilitre

Element: rateRatio

When the denominator value is 1 (one) express a rateRatio as:

at a rate of {numerator_value} per {denominator_unit}

Otherwise express as:

at a rate of {numerator_value} every {denominator_value} {denominator_unit}

Express the time-based units in plural when required.

  • at a rate of 30 millitre per hour

  • at a rate of 30 millitre every 2 hours

Element: rateRange

Express as:

at a rate of {low_value} to {high_value} {high_units}

  • at a rate of 1 to 2 liter per minute

Element: rateQuantity

Express as:

at a rate of {value} {units}

  • at a rate of 1 microgram per kilogram per hour
Note: The above example uses the UCUM unit microgram per kilogram per hour.

Elements: duration / durationMax

Express a duration as:

over {value} {units}.

Express the time-based units in plural when required.

Where a durationMax is defined, append with

(maximum {max_value} {max_units}).

  • over 8 hours

  • over 4 hours (maximum 6 hours)

Elements: frequency / frequencyMax / period / periodMax

Note: Logic to produce human readable timing instructions is complex with both generic rules and a number of special cases.

Express the combination of frequency and period as:

{frequency} times every {period_value} {period_unit}`

  • 3 times every 8 hours

Where a frequencyMax is defined, express as:

{frequency} to {frequencyMax} times every {period_value} {period_unit}

  • 2 to 3 times every 8 hours

Where a periodMax is defined, express as:

{frequency} times every {period_value} to {periodMax_value} {period_unit}

  • 3 times every 6 to 8 hours

Where both frequencyMax and periodMax are defined, express as:

{frequency} to {frequencyMax} times every {period_value} to {periodMax_value} {period_unit}

  • 2 to 3 times every 6 to 8 hours

Where a frequencyMax is defined without a frequency then express as:

up to {frequencyMax} times

  • up to 3 times a day

  • up to 4 times every 8 hours

  • up to 6 times every 3 to 4 weeks

Note: The omission of both a frequency and frequencyMax when either a period or periodMax is present is allowed as per cardinality rules but should be prevented in practice as does not result in a logical timing instruction.

Special Cases

When period is 1 (one) without a frequency, express as:

daily, weekly, monthly, or annually depending on the periodUnit.

In theory, the periodUnit could be s (seconds) or min (minutes); however, the use of these without an associated frequency is illogical.

When frequency is 1 (one) without a period, express as:

once

When frequency is 2 (two) defined without a period, express as:

twice

When frequency is greater than 2 (two) and defined without a period, express as:

{frequency} times

  • 3 times

When frequency and period are both 1 (one) express as:

once a {period_unit}.

  • once a week

When frequency is 1 (one) and period is greater than 1 (one) express as:

every {period_value} {period_unit}

or

every {period_value} to {periodMax_value} {period_unit}

  • every 8 hours

  • every 6 to 8 hours

When frequency is 2 (two) and period is 1 (one) express as:

twice a {unit}.

  • twice a day

When frequency is greater than 2 (two) and period is 1 (one) express as:

{frequency} times a {unit}.

  • 4 times a day

When frequency is 2 (two) and period is greater than 1 (one) express as:

twice every {period_value} {period_unit}

or

twice every {period_value} to {periodMax_value} {period_unit}

  • twice every 8 hours

  • twice every 6 to 8 hours

Elements: offset / when

Any offset will be defined as a number of minutes. If this equates to a whole number of hours or days then express as the number of hours (=60 minutes) or days (=1440 minutes). Use the singular or plural expression of time when required. Separate multiple statements with a comma and use the word "and" to separate the final two statements.

The FHIR event timing value-set used for when should have descriptions modified to make them more human readable.

Remove the text "event occurs [offset]" and "(from the Latin...)" from the descriptions.

Simplify the following value-set definitions;

  • Display: "After Sleep" - Use definition "once asleep"
  • Display: "HS" - Use definition "before sleep"
  • Display: "WAKE" - Use definition "upon waking"
  • Display: "C" - Use Definition "at a meal"
  • Display: "CM" - Use Definition "at breakfast"
  • Display: "CD" - Use Definition "at lunch"
  • Display: "CV" - Use Definition "at dinner"

Express as:

{offset_value} minute(s) / hour(s) / day(s) {modified_when_value-set}

  • at breakfast

  • 30 minutes before a meal

  • 1 hour before sleep

  • 2 hours after breakfast

  • in the morning and in the evening

  • at night

Note: The valueset for event.timing suggests using the during preposition, which differs to the examples above.
Prepositions are interchangeble in the English language (e.g. during, in or at), and care should be taken to ensure that the appropriate preposition is used in the dosage instruction, for the person administering the medication.

Element: dayOfWeek

Express as:

on {dayOfWeek}

using the full description from the FHIR value-set, i.e. mon = "Monday".

Separate multiple statements with a comma and use the word "and" to separate the final two statements.

  • on Monday

  • on Monday, Wednesday and Friday

Element: timeOfDay

Express as:

at {timeOfDay}

Separate multiple statements with a comma and use the word "and" to separate the final two statements. If a time is expressed with :00 seconds then express just in terms of hours and minutes. Sending systems should always provide times using the 24 hour clock.

Receiving systems may apply local preferences for display, i.e. 15:00 or 3:00pm.

  • at 10:00

  • at 10:00 and 15:00

Element: route

No additional formatting required.

Element site

No additional formatting required.

Elements: asNeededCodeableConcept / asNeeded

Express the asNeededBoolean statement as:

as required

Express the asNeededCodeableConcept as:

as required for {coded_value_description}

  • as required for Migraine

Elements: boundsDuration / boundsRange

Express boundsDuration as:

for {value} {units}.

Express the units in plural when required.

  • for 7 days

Express boundRange as:

for {low_value} to {high_value} {high_units}

Express the units in plural when required.

  • for 2 to 4 hours

Elements: count / countMax

Note: The most appropriate use of English to express a count may vary between use cases. This guidance suggests the phrasing take X times but a phrasing of take x doses or use X times may be preferrable for some use cases.

If count is 1 (one) then express as:

take once

If count is 2 (two) then express as:

take twice

Otherwise express count as:

take {count} times

Where a countMax is defined, insert with:

to {countMax}

  • take once

  • take twice

  • take 3 times

  • take 3 to 5 times

Element: event

Express event statements as:

on {event_value}

Separate multiple statements with a comma and use the word " and " to separate the final two statements.

Local preferences can be used to display the date in dd/mm/yyyy or dd-mmm-yyyy format.

  • on 25/01/2019

  • on 25-Jan-2019

  • on 25/01/2019, 25/02/2019 and 25/03/2019

Elements: maxDosePerPeriod / maxDosePerAdministration / maxDosePerLifetime

Express a maxDosePerPeriod statement as:

up to a maximum of {numerator_value} {numerator_unit} in {denominator_value} {denominator_unit} Express the time-based units in plural when required.

  • up to a maximum of 1000 milligram in 24 hours

Express a maxDosePerAdministration statement as:

up to a maximum of {value} {unit} per dose

  • up to a maximum of 2 milligram per dose

Express a maxDosePerLifetime statement as:

up to a maximum of {value} {unit} for the lifetime of patient

  • up to a maximum of 60 milligram for the lifetime of patient

Element: additionalInstruction

Separate multiple statements with a comma and use the word "and" to separate the final two statements.

  • Do not stop taking this medicine except on your doctor's advice

  • Dissolve or mix with water before taking and Contains aspirin

Element: patientInstruction

No additional formatting required.

Multi-Sequence Instructions

When a complete dosing instruction is described across multiple sequences, the complete string is concatinated with each sequence. The original medication information is not repeated.

Sequential Instructions

Separate sequential instructions (where each <sequence> has an incremental value) with , then .

  • Anydrug - 50 milligram - once a day - oral - for 1 week, then 100 milligram - once a day - oral - for 3 weeks

Concurrent Instructions

Separate parallel instructions (where <sequence> has the same value) with , and .

  • Anydrug - 50 milligram - once a day - in the morning - oral, and 100 milligram - once a day - in the evening
back to top