Skip to content

Translated codes

If a coding was added by translation, say how faithfully it represents what was meant. The codings in a CodeableConcept are read as alternative spellings of one concept. A coding a system added -- a DIN beside the clinical drug a prescriber chose, a classification code beside a diagnosis -- is often not the same concept, and nothing in base FHIR says so. This page says how to say so.

It is the companion of Carrying the raw code. That page says: when you convert a code, keep the original. This one says: when you keep a translation beside it, say what the translation is.

Four facts, kept apart

A translated coding carries up to four facts, and each has its own home. Conflating any two of them is the usual mistake.

The question Where it is answered
Did a person choose this code? Coding.userSelected (base FHIR)
Why is this coding here? HL7 coding-purpose: original, post-coded, translated or conformance
How faithfully does it represent the intended concept? nexus-coding-mapping
Is it valid for a particular transaction? The protocol's or payer's own rules -- not recorded on the coding

userSelected absent or false says only that a person did not pick this code. It does not say the code is approximate. And a relationship that is not exact does not mean the system was unsure which code to pick: a translation can be completely deterministic and still not mean the same thing.

The relationship

nexus-coding-mapping carries two parts, the same two FHIR already defines for a ConceptMap target:

  • equivalence -- the relationship, from R4 ConceptMapEquivalence: equivalent, equal, wider, subsumes, narrower, specializes, inexact or relatedto. unmatched and disjoint are not allowed: a coding that does not represent the concept does not belong in the CodeableConcept.
  • comment -- what the code cannot say. Required for narrower and inexact (nexus-cm-1), exactly as ConceptMap requires of the same two relationships.

Direction. The concept the CodeableConcept expresses is the source; the coding carrying the extension is the target. So wider says this coding means more than what was intended, and specializes says it is a more specific kind of it.

The source is implicit. It is the one sibling coding with userSelected = true, where there is exactly one, and otherwise CodeableConcept.text.

The relationship is copied, never defaulted. It comes from whatever mapping produced the coding. A producer with no mapping to copy it from has no translated coding to add.

R5. R5 renamed the vocabulary. equivalent and equal become equivalent; wider becomes source-is-narrower-than-target; narrower becomes source-is-broader-than-target; subsumes, specializes, inexact and relatedto all become related-to, which loses the distinction.

Worked example: a DIN beside the clinical drug

A prescriber chooses ramipril 5 mg oral capsule. An interface the EMR sends to requires a product code, so the EMR supplies the DIN of one marketed product. The two codings do not mean the same thing: a DIN names one manufacturer's product, and the prescriber did not choose a manufacturer.

"medicationCodeableConcept": {
  "text": "Ramipril 5 mg oral capsule",
  "coding": [
    { "system": "http://terminology.hl7.org/CodeSystem/hc-CCDD", "code": "9000723",
      "display": "ramipril 5 mg oral capsule", "userSelected": true },
    { "extension": [
        { "url": "https://fhir.apps.health/StructureDefinition/nexus-coding-mapping",
          "extension": [ { "url": "equivalence", "valueCode": "specializes" } ] },
        { "url": "http://hl7.org/fhir/StructureDefinition/coding-purpose",
          "valueCoding": { "system": "http://hl7.org/fhir/coding-purpose", "code": "conformance" } },
        { "url": "https://fhir.apps.health/StructureDefinition/nexus-representative-code",
          "valueBoolean": true } ],
      "system": "http://hl7.org/fhir/NamingSystem/ca-hc-din", "code": "02251574", "display": "APO-RAMIPRIL" }
  ]
}

The whole instance is the ramipril example.

Why specializes and not inexact. A marketed ramipril 5 mg capsule is a ramipril 5 mg capsule: the product is a more specific kind of the drug that was prescribed, and specializes says exactly that. inexact would claim the two overlap without either containing the other, which is not true here. What the DIN must NOT be read as -- "the prescriber chose this manufacturer" -- is answered by nexus-representative-code, not by weakening the relationship: it says the system chose this code to stand in for a more general choice, so a reader interprets only what the chosen concept states. userSelected being absent and coding-purpose being conformance are consistent with that, but neither says it.

PrescribeIT's representative DIN. PrescribeIT defines the same flag, http://prescribeit.ca/fhir/StructureDefinition/ext-medication-code-representative (valueBoolean = true), republished by CA Baseline, with its own interpretation rules: the EMR chose the DIN, and a pharmacy system reads only its ingredients. Its declared context is Medication.code.coding, so it cannot appear on a request's medicationCodeableConcept, which is why nexus-representative-code exists: the same meaning, on any coding. On a Medication exchanged under PrescribeIT, carry PrescribeIT's extension as well. Neither replaces nexus-coding-mapping, which says how the codes relate rather than how a reader treats the representative one.

OHIP diagnostic codes

An Ontario diagnostic code is billing content. In this specification it belongs on the claim, and it is not added as a translated coding to a clinical resource's code: a diagnosis is not translated into it. The set is ICD-derived but not a subset of any ICD revision, so a code computed by truncating an ICD code can be valid and wrong.

Where a claim carries the diagnostic code is not yet modelled: R4 Invoice.lineItem has no element for it and this specification publishes no extension for one. What would decide it is the first producer that has to send a diagnostic code on a claim in FHIR, and the shape it needs. When that is modelled, the code carries the edition date as version and the Ministry's descriptor as display, for the reasons given on the code system's page.

Prefer a published ConceptMap

When a reusable, curated mapping exists, publish it as a ConceptMap and let codings point at the map's result rather than restate it. The inline extension is for the case where no published map exists, the mapping is specific to this instance, or a reader must understand the coding without resolving another resource. The two say the same thing in the same vocabulary, so a coding annotated inline can later be backed by a map without changing meaning.

What a consumer can rely on

  • A coding with nexus-coding-mapping is a translation, and its relationship to the intended concept is the one stated. Do not treat it as interchangeable with the source unless the relationship is equivalent or equal.
  • The intended concept is the user-selected coding, or the text. Use it for anything clinical -- matching, decision support, display to a clinician.
  • Absence tells you nothing. Neither the extension nor coding-purpose is required, so a coding without them may be a translation that was not annotated. A producer that knows it translated should say so.
  • A relationship is not a validity claim. equivalent does not mean the code is acceptable to a particular payer or interface; those rules live with the payer or the protocol.

See also