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.

Dose to Text Translation

This page is in Experimental status.

Overview

This section details the logic required for a system to generate a suitable, clinically safe, complete medication plus dosage string from the coded structures.

Research References

This guidance is aligned with;

Note: The Australian guidelines include the use of Tall-Man within medication names, which has been excluded from this guidance.

Common Principals

The following applies to the presentation of any component part of the dosage instruction;

  • Always express units of measure using the full description, e.g. milligram not mg.

  • Important: The above principal does not apply to units of measure as part of pre-coordinated dm+d concept descriptions, e.g. Ramipril 5mg capsules.

  • Always express a time-based unit of measure in the plural when applicable, e.g. 2 hour becomes 2 hours.

  • Do not express other units of measure in the plural as this introduces complications with units such as microgram per millilitre or microgram per kilogram per hour.

  • Where multiple statements are allowed, e.g. when or event structures, then separate each statement with a comma plus whitespace. Replace the last comma separating the final two statements with the word " and ", e.g. on Monday, Wednesday and Friday.

Component Part Separator

In most cases, each component part of the medication instruction is separated by space-dash-space, e.g. " - ".

  • Oxytetracycline 250mg tablets - 1 tablet - 4 times a day - oral

  • Oxytetracycline - 250 milligram - 4 times a day - oral

Exceptions are as follows:

  • Use a single whitespace after a method, e.g. Apply...

  • Use a single whitespace to separate between a dayOfWeek and timeOfDay, e.g. on Monday at 10:30

Logicial Display Order

The order in which the structures within a CareConnect profiled resouce should be listed.

  1. Medication Name
  2. Medication Form (if not implied within a VMP/AMP name)
  3. Trade Family Name (if not implied within an AMP name)

Then for each dosageInstruction;

  1. method
  2. doseQuantity / doseRange
  3. rateRatio / rateRange / rateQuantity
  4. duration, durationMax
  5. frequency, frequencyMax, period and periodMax
  6. offset, when(s)
  7. dayOfWeek(s)
  8. timeOfDay(s)
  9. route
  10. site
  11. asNeededCodeableConcept / asNeeded
  12. boundsDuration / boundsRange
  13. count, countMax
  14. event(s)
  15. maxDosePerPeriod / maxDosePerAdministration / maxDosePerLifetime
  16. additionalInstruction(s)
  17. patientInstruction

Translation Logic: Medication

Medication name

CUI recommends the medication name is formatted in bold. The text narrative supports XHTML mark-up therefore the medication name could be marked-up within <b> ... </b> HTML tags.

If using a VTM concept, the name will just be the name of the VTM.

  • Paracetamol

If using a VMP concept the name will include the strength and form. The unit of measure associated with the strength may use an abbreviated term as this is part of the dm+d standard.

  • Paracetamol 1g tablets

If using an AMP concept the name will be the AMP description which includes the supplier name. The unit of measure associated with the strength may use an abbreviated term as this is part of the dm+d standard.

  • Paracetamol 1g tablets (Dawa Ltd)

Medication form

If the form is not implied within a VMP or AMP name, then no additional formatting is required.

Trade family name

Although not supported yet within FHIR profiled resources, when available, format into UPPER case.

  • ZOMORPH

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