Skip to content

Coding Mapping Extension

Canonicalhttps://fhir.apps.health/StructureDefinition/nexus-coding-mapping
Statusdraft · 1.33.0
BaseExtension (constraint)
ContextCodeableConcept.coding (element)
SourceFSH · JSON

How faithfully this coding represents the concept its CodeableConcept expresses, when the coding was added by translation rather than chosen.

FSH

The authored source of truth: extensions/CodingMappingExtension.fsh (edit on GitHub). One FSH file may define several related artifacts.

// CodingMappingExtension.fsh
// How faithfully a TRANSLATED coding represents the concept its CodeableConcept expresses.
//
// WHY. A CodeableConcept's codings are alternative representations of one concept, and a reader
// treats them as interchangeable. A coding added by translation -- a DIN beside the clinical drug a
// prescriber chose, a classification code beside a clinical diagnosis -- may not mean the same
// thing, and nothing in the instance says so. FHIR already has the vocabulary for that
// relationship, on ConceptMap: `ConceptMap.group.element.target.equivalence` and `.comment`. This
// extension carries the same two facts inline, on the coding they describe, for the case where no
// published ConceptMap exists or the instance must be understood without resolving one.
//
// DIRECTION, which is the thing to get right. The SOURCE is the concept the CodeableConcept
// expresses; the TARGET is the coding that carries this extension -- the direction of a ConceptMap
// target. The source is implicit: the one sibling coding marked `userSelected = true` where there is
// exactly one, and otherwise `CodeableConcept.text`. So `wider` says this coding means MORE than the
// intended concept, and `specializes` says it is a more specific kind of it.
//
// FOUR FACTS, KEPT APART. Who chose the code is `Coding.userSelected`. Why the coding is present is
// HL7's `coding-purpose` extension (`original | post-coded | translated | conformance`). How
// faithfully it represents the intended concept is this extension. Whether it is valid for a
// particular transaction is a protocol or billing rule and is not recorded here. A mapping can be
// deterministic and certain and still be `inexact`: this is a statement about meaning, not about
// confidence. See the Translated codes pattern.
//
// 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.
//
// VOCABULARY. R4 `ConceptMapEquivalence`, less `unmatched` and `disjoint`: a coding that does not
// represent the concept does not belong in the CodeableConcept at all.

Alias: $NexusCodingMapping = https://fhir.apps.health/StructureDefinition/nexus-coding-mapping

Invariant:   nexus-cm-1
Description: "A `narrower` or `inexact` mapping SHALL explain itself in `comment`, as ConceptMap's own rule (cmd-1) requires of the same relationships"
Severity:    #error
Expression:  "extension('equivalence').where(value.ofType(code) = 'narrower' or value.ofType(code) = 'inexact').exists() implies extension('comment').exists()"

Extension: NexusCodingMapping
Id: nexus-coding-mapping
Title: "Coding Mapping"
Description: """
How faithfully this coding represents the concept its CodeableConcept expresses, when the coding was
added by translation rather than chosen.

The containing CodeableConcept is the SOURCE and this coding the TARGET, with the meaning of R4
`ConceptMap.group.element.target.equivalence`. The source is implicit: the single sibling coding
with `userSelected = true` where there is exactly one, and otherwise `CodeableConcept.text`.
`comment` says what the structured relationship cannot, and is required for `narrower` and
`inexact`.

The relationship is a statement about meaning, not about confidence: a translation can be certain
and still `inexact`. It is copied from the mapping that produced the coding, never defaulted.

R5 carries the same relationship as `ConceptMap...target.relationship`: `equivalent` and `equal`
map to `equivalent`; `wider` to `source-is-narrower-than-target`; `narrower` to
`source-is-broader-than-target`; `subsumes`, `specializes`, `inexact` and `relatedto` to
`related-to`, which loses the distinction.
"""
* ^url = $NexusCodingMapping
* ^status = #draft
* ^experimental = false
* ^publisher = "WELLSTAR Technologies Corp."
* ^contact.name = "Nexus EMR FHIR Implementation Guide"
* ^contact.telecom.system = #url
* ^contact.telecom.value = "https://fhir.apps.health"
* ^jurisdiction = urn:iso:std:iso:3166#CA "Canada"
* ^context[0].type = #element
* ^context[0].expression = "CodeableConcept.coding"
* obeys nexus-cm-1
* . ^short = "How faithfully this translated coding represents the intended concept"

* extension contains
    equivalence 1..1 MS and
    comment 0..1 MS

* extension[equivalence].value[x] only code
* extension[equivalence].valueCode from NexusCodingMappingEquivalenceVS (required)
* extension[equivalence] ^short = "equivalent | equal | wider | subsumes | narrower | specializes | inexact | relatedto"
* extension[equivalence] ^definition = "The relationship of this coding (the target) to the concept the CodeableConcept expresses (the source), as R4 ConceptMap target equivalence defines it."
* extension[comment].value[x] only string
* extension[comment] ^short = "What the relationship code cannot say; required for narrower and inexact"