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.

Dose to Text Translation

This page is in Experimental status.

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 Principles

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

  1. In most cases, express numbers as numbers, e.g. 3 not three. There are suggested exceptions:
  • 1.1. Refer to the section below when dealing with frequency data for the case of once or twice.
  • 1.2. When a proceeding unit of measure starts with a number, e.g. 5ml spoonful separate the quantity from the unit of measure with a x symbol, e.g. 2 x 5ml spoolful. Alternatively when the quantity is 1 or 2 is may be preferrable to express the quantity in words, e.g. ONE or TWO, e.g. TWO 5ml spoonful. Both options prevent misreading as a 25ml spoonful.
  • 1.3. Where a decimal number, e.g. 0.5 AND the unit of measure is NOT an SI unit AND the quantity is N.25, N.5 or N.75, then express using the words quarter, half or three quarters, e.g. half tablet, otherwise express as a decimal number, e.g. 12.5 milligram.

  1. Always express units of measure using the full description, e.g. milligram not mg. An exception is when the unit of measure as part of a pre-coordinated dm+d concept descriptions, e.g. Ramipril 5mg capsules.

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

  3. 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.

  4. Separate multiple when statements with a comma plus whitespace. FHIR intreprets multiple when events as the union of these events so no extra textual expression is required. For example, if when=NORM and when=C then express as during the morning, at a meal.

  5. Separate multiple events statements with a comma plus whitespace. As these are separate events, for a more readable dosage instruction, consider replacing the last comma separating the final two statements with the word " and ", e.g. on 25/01/2019, 25/02/2019 and 25/03/2019.

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

Logical Display Order

The order in which the structures within the Resource 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. doseAndRate.doseQuantity / .doseRange
  3. doseAndRate.rateRatio / .rateQuantity / .rateRange
  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
UPDATE FEB 2025. The element patientInstruction has been removed from this guidance as it's contents would often duplicate what is contained within text. See patientInstruction for more info.

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

Element: method

No additional formatting required.

Element: doseAndRate.doseQuantity

Express as:

{quantity} {units}

  • 50 milligram

  • 2 tablet

Element: doseAndRate.doseRange

Express as:

{low} to {high} {high_units}

  • 20 to 40 millilitre

Where only a doseRange.high is defined, express as:

up to {high} {high_units}

  • up to 40 millilitre
Note: It would be clinically unsafe to express a doseRange with only a low value and an omitted high value.

Element: doseAndRate.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 millilitre per hour

  • at a rate of 30 millilitre every 2 hours

Element: doseAndRate.rateRange

Express as:

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

  • at a rate of 1 to 2 litre per minute

Element: doseAndRate.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.

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

  • during the morning, at a meal

  • 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 / boundsPeriod

Express the units in plural when required.

Express boundsDuration as:

for {value} {units}.

  • for 7 days

Express boundsRange as:

for {low} to {high} {high_units}

  • for 2 to 4 hours

Where only boundsRange.low is defined, express as:

for at least {low} {low_units}

  • for at least 2 hours

Where only boundsRange.high is defined, express as:

for up to {high} {high_units}

  • for up to 2 hours

Express boundsPeriod as:

from {start} to {end}

  • from 2025-06-13 to 2025-06-20

Where only boundsPeriod.start is defined, express as:

from {start}

  • from 2025-06-13

Where only boundsPeriod.end is defined, express as:

until {end}

  • until 2025-06-20

Elements: count / countMax

If count is 1 (one) then express as:

once

If count is 2 (two) then express as:

twice

Otherwise express count as:

{count} times

Where a countMax is defined, insert with:

to {countMax}

  • once

  • twice

  • 3 times

  • 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

Excluded from the algorithm.

No additional formatting required.

UPDATE FEB 2025. The element patientInstruction has been removed from this guidance as it's contents would often duplicate what is contained within text. See patientInstruction for more info.

Multi-Sequence Instructions

A complete dosing instruction may be described by multiple Dosage elements using the sequence attribute to identify the order of the instructions and if they are sequential or concurrent.

Each Dosage has it's own text element so this should only contain a text representation for that part (sequence) of the overall dosage instruction.

For example.

  "dosageInstruction": [
    {
      "sequence": 1,
      "text": "2 tablet - daily - at 08:00 - for 1 week",
      "timing": {
        "repeat": {
          "boundsDuration": {
            "value": 1,
            "unit": "week",
            "system": "http://unitsofmeasure.org",
            "code": "wk"
          },
          "period": 1,
          "periodUnit": "d",
          "timeOfDay": [
            "08:00:00"
          ]
        }
      },
      "doseAndRate": [
        {
          "doseQuantity": {
            "value": 2,
            "unit": "tablet",
            "system": "http://snomed.info/sct",
            "code": "428673006"
          }
        }
      ]
    },
    {
      "sequence": 1,
      "text": "1 tablet - daily - at 12:00 - for 1 week",
      "timing": {
        "repeat": {
          "boundsDuration": {
            "value": 1,
            "unit": "week",
            "system": "http://unitsofmeasure.org",
            "code": "wk"
          },
          "period": 1,
          "periodUnit": "d",
          "timeOfDay": [
            "12:00:00"
          ]
        }
      },
      "doseAndRate": [
        {
          "doseQuantity": {
            "value": 1,
            "unit": "tablet",
            "system": "http://snomed.info/sct",
            "code": "428673006"
          }
        }
      ]
    }
  ]

To present the overall dosage instruction in human readable text, for sequential instructions (where each sequence has an incremental value) concatinated with the term , then .

  • 2 tablet - daily - for 1 week, then 1 tablet - daily - for 1 week

For parallel instructions (where sequence has the same value) concatinated with the term , and .

  • 2 tablet - daily - at 08:00 - for 1 week, and 1 tablet - daily - at 12:00 - for 1 week

An implementation may also choose to share the entire complete concatinated dosage instruction as a text string within the text element of the overall Resource, for example, within the MedicationRequest.text element.

Open Source & Test Tool

Note: Published example code and test tools based on this guidance are currently not available.
back to top