Carrying the raw code¶
If you convert a code, carry the original. Every mapping loses something, and the record that keeps only the mapped code cannot say what it lost. This page says how to carry the original so a consumer can find it, and why the flag matters more than the address. When you keep the translation beside the original, Translated codes says how to state what the translation is.
This costs Nexus EMR nothing: it is FHIR-native, its codes are already the codes it stores, and there is nothing to convert. It matters enormously to anything reading records that came from somewhere else -- a legacy EMR, a converter, a migration -- because that is where a code was chosen by a human, translated by software, and then presented to the next reader as though the translation were the choice.
The two rules¶
A source identifier carried alongside a governed one is use = secondary.
"identifier": [
{ "system": "https://fhir.infoway-inforoute.ca/NamingSystem/ca-on-patient-hcn", "value": "1234567890" },
{ "use": "secondary", "system": "https://example.org/oscar/demographic", "value": "48213" }
]
A raw code carried alongside a mapped one is userSelected = true, when the raw code is the
one a person actually picked.
"code": {
"coding": [
{ "system": "http://snomed.info/sct", "code": "44054006", "display": "Diabetes mellitus type 2" },
{ "system": "https://example.org/oscar/dxcode", "code": "250.00", "userSelected": true }
],
"text": "Type 2 diabetes"
}
That is the whole convention. Both flags are base R4 with their base meanings; neither needs anything from this specification.
Source codes on a single code element¶
Some elements hold one code and have no room for a second coding: Patient.gender, the status
elements, Task.priority, Composition.confidentiality, AllergyIntolerance.category,
Attachment.contentType, Questionnaire.item.type. Where the source system's code is finer than
the bound code, carry it in the HL7 extension
alternate-codes on the
element itself. Its value is a CodeableConcept, it may repeat, and it applies to an element of type
code or Coding. The coding inside it follows the rules above: a system URI chosen the same way,
and userSelected = true when the source code is the one a person picked.
"gender": "other",
"_gender": {
"extension": [ {
"url": "http://hl7.org/fhir/StructureDefinition/alternate-codes",
"valueCodeableConcept": {
"coding": [ { "system": "https://example.org/oscar/sex", "code": "N", "userSelected": true } ]
}
} ]
}
The extension says the same thing as the element in different words, at the same or a finer level of detail. It does not carry a code that means something else: if the source code cannot be mapped to the bound value set without changing its meaning, that is a mapping question, not a raw-code one.
A reader that does not use the extension ignores it and reads the bound code. A writer that receives the extension back unchanged, on an element whose bound code still maps from the source code, writes the source code to the source system. If the bound code was changed, the source code no longer describes it: map from the bound code instead.
A boolean has no bound code to be finer than, and is out of scope.
Why the flag and not the system¶
The system URI is not the signal. Two installations converting the same legacy EMR will pick different system URIs for the same local vocabulary, and a consumer cannot tell from the URI alone whether it is looking at a governed code or a source one. The flag is unambiguous and travels with the element, so a reader can find every raw code in a resource without recognising a single system.
A URI is still required, because an identifier or a coding without a system is not identity -- it is a bare string that collides with every other bare string. Pick one and keep it stable. If the source system publishes a URI, use it. If it does not, invent one under a domain you control, or use the shape this specification suggests:
https://fhir.apps.health/NamingSystem/<instance-id>-<resource>-raw-code
<instance-id> names the installation the code came from, so that two deployments sending the same
local code do not collide. It must be stable over time: change it and previously written values stop
reconciling.
That shape is a suggestion, not a requirement. This specification does not declare those URIs as artifacts and does not validate them. Nothing prefers a code that uses the shape to one that does not. It exists so that an implementer with no better answer has an answer, and so that two teams inside one estate land in the same place by default.
What a consumer can rely on¶
use = secondarymeans "not the handle to file this record under." It does not mean unreliable or deprecated. It is often the most meaningful value in the resource to somebody operating the source system.userSelected = truemeans a person chose THIS coding, not that it is preferred, not that it is more correct. Where a mapped code carries no flag and a raw code carriestrue, the mapping was made by software.- Neither flag is required by this specification, so absence tells you nothing. A resource with
no
secondaryidentifier and nouserSelectedcoding may have had no raw code, or may have had one and dropped it. You cannot distinguish those, which is the reason to write the flag when you have the information.
Why there is no invariant¶
An invariant would have to fire on records that legitimately have no raw code -- everything Nexus EMR authors natively, which is most of what this specification describes. A rule that is violated by correct data teaches implementers to ignore it, and this specification has retired rules for exactly that reason before.
So this is guidance, and it binds the only party it can: if you are converting, you know you are converting, and you know what the original was. Nobody else can supply it later.
Where this applies¶
Anywhere a record crosses from a system with its own vocabulary into this one. Concretely: an identifier the source assigned, a diagnosis code, a service or appointment type, a reason code, a result code, a document type, a role. If your converter made a choice a human did not, the human's choice is the one worth keeping.
See also¶
- Translated codes -- how to say how faithfully a translation you keep represents what was meant
- Identifiers and references -- how identifiers and logical references are shaped
- Canonical URLs -- which addresses this specification governs, and which it does not