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 R4ConceptMapEquivalence:equivalent,equal,wider,subsumes,narrower,specializes,inexactorrelatedto.unmatchedanddisjointare not allowed: a coding that does not represent the concept does not belong in theCodeableConcept.comment-- what the code cannot say. Required fornarrowerandinexact(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-mappingis 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 isequivalentorequal. - 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-purposeis 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.
equivalentdoes not mean the code is acceptable to a particular payer or interface; those rules live with the payer or the protocol.
See also¶
- Carrying the raw code -- keep the original when you convert
- Canonical URLs -- which addresses this specification governs