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.

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.

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 = secondary means "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 = true means 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 carries true, the mapping was made by software.
Neither flag is required by this specification, so absence tells you nothing. A resource with no secondary identifier and no userSelected coding 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.