Nexus EMR Identifiers and References¶

This guide covers how identifiers, references, and canonical URLs work in the Nexus EMR FHIR specification.

Identifiers¶

No Nexus EMR profile mandates a canonical identifier system. Every profile declares identifier as 0..* and says the same thing:

A business identifier is recommended but not required; no specific canonical system is mandated.

There is no invariant enforcing an identifier system on any resource, and the server does not validate one. A conformant resource may carry any identifier system, several, or none.

Carry the identifier the source system already assigns, under whichever system URI genuinely identifies it:

Where a governed system exists, use it. Provincial health numbers, a regulator's licence number, LOINC for observations. The OLIS Implementation Guide collects canonical URIs for provincially assigned identifiers.
Where the source system publishes its own identifier system, use that.
Where neither exists, see the raw-code fallback below.

Do not invent a system URI when a governed one is available. An identifier under the wrong system is worse than no identifier: it reconciles to nothing, and it looks authoritative while doing so.

Raw codes from source systems¶

Records arriving from a source EMR often carry a local code with no published system URI. Carry it anyway, and flag it: a source identifier alongside a governed one is use = secondary, and a raw coding alongside a mapped one is userSelected = true where a person picked it.

The flag is the signal, not the system URI -- two installations converting the same legacy EMR will choose different URIs for one vocabulary, and a consumer cannot tell from the URI alone what it is looking at. A URI is still required (identity needs one), and this specification suggests a shape for implementers with no better answer, but the shape is a suggestion and nothing validates it.

Four codings on Appointment (serviceCategory, serviceType, reasonCode, cancelationReason) are constrained by invariant: a coding using the suggested raw-code shape there MUST carry both code and display. That is the only place the shape is enforced, and it enforces completeness rather than the shape itself.

See Carrying the raw code for the full convention, worked examples, what a consumer may rely on, and why there is no invariant.

Identifier systems in the examples¶

Most identifier systems in this guide's examples are illustrative, and resolve to nothing by design. A reader tracing one and finding no definition has not found a broken link; they have found a placeholder. Three families appear, and only the first is governed here.

Declared namespaces. Where an identifier has a real assigning authority this guide publishes a NamingSystem for it — the provincial health number, a college licence, the platform's own MRN and user id, and forty-odd others. These resolve, carry their addresses as uniqueId entries, and are what a producer writes. If an example names one of these, match it literally.

Per-deployment raw codes. …/NamingSystem/<instance-id>-<resource>-raw-code is a documented convention, not an artifact this guide publishes: the namespace belongs to the deployment that minted it, so there is one per instance and none of them could be declared centrally. See Carrying the raw code.

Placeholder systems for a resource's own identifier. Where an example needs a resource to carry a business identifier and no authority governs one — a Location, an Encounter, a Task — the example uses a placeholder. These are not declared, are not resolvable, and must not be copied into a producer. Write the identifier your source system actually assigns, under whichever system URI genuinely identifies it, exactly as the top of this page says.

A reader will notice the examples spell placeholders two ways, …/identifier/<type> and …/NamingSystem/<type>-identifier. Neither is a contract and neither is preferred; the variation is a property of examples written at different times rather than a distinction being drawn. Do not infer a convention from it, and do not match on either.

References¶

Literal references are allowed, but resources generated by an EMR will often not know the literal FHIR ids. Those use logical references instead, carrying the same identifier described above:

"subject": {
    "identifier": {
        "system": "<the system that identifies the source identifier>",
        "value": "<the source-assigned identifier>"
    }
}

Technical IDs (the `id` field)¶

Every FHIR resource has an id. The server assigns it on create.

Do not generate or send one yourself, and do not derive meaning from it. It identifies a resource in this store and nowhere else.

Canonical URL structure¶

Canonical URLs for conformance artifacts follow:

https://fhir.apps.health/[artifact-type]/[artifact-id]

Base URL https://fhir.apps.health/ is the base for all Nexus EMR FHIR artifacts.
[artifact-type] is the artifact's resource type: StructureDefinition, CodeSystem, ValueSet, NamingSystem, and so on.
[artifact-id] is a unique, human-readable id for the artifact, using hyphens as separators.

Examples by artifact type:

StructureDefinition (profile) https://fhir.apps.health/StructureDefinition/nexus-emr-core-patient
StructureDefinition (extension) https://fhir.apps.health/StructureDefinition/nexus-emr-appointment-modality-extension
CodeSystem https://fhir.apps.health/CodeSystem/nexus-clinical-roles
ValueSet https://fhir.apps.health/ValueSet/all-atc
NamingSystem https://fhir.apps.health/NamingSystem/patient-mrn
CapabilityStatement https://fhir.apps.health/CapabilityStatement/nexus-emr-server

Every artifact this IG defines is listed on the artifacts index. An artifact not listed there is not part of this specification, whatever its URL looks like.

Private infrastructure you will see on the wire¶

Two artifacts in this estate are platform infrastructure that leaked into the FHIR surface. They are documented because you will meet them in real payloads and an undocumented field is worse than a declared one -- not because they are part of the contract. Both are deliberately kept on the internal services.well.com host rather than the governed fhir.apps.health one, which is the signal that they are not spec surface.

Do not build on either. Neither URL is resolvable, both values are opaque, and neither carries a breaking-change guarantee: they can change shape without a major version.

What	Where it appears	Who owns it
`Practitioner.identifier[userId]` — the login a clinical identity resolves to (e.g. an Auth0 user id)	`http://services.well.com/fhir/NamingSystem/user-id`	the auth layer
The tenant stamp — which tenant owns a stored resource	`http://services.well.com/fhir/auth/tenant-id`, an extension on any `DomainResource`	the FHIR Gateway

Practitioner is the stable clinical identity a user login maps to (PractitionerRole is the role binding at an organization, not the user), so the account id sits on Practitioner. It is 0..1: a Practitioner with no login is normal and conformant — an external referral target or a historical provider has no account. Do not treat absence as an error, and do not parse the value.

The tenant stamp¶

The gateway stamps the caller's tenant on every create and update, and strips any client-supplied tenant extension first — a value you send is discarded, not honoured. There is no way for a client to choose the tenant on a resource; tenancy follows the token. Reads are already tenant-scoped, so a resource belonging to another tenant is not found rather than filtered, which is why you will only ever see your own tenant's value.

Treat it as read-only provenance about storage. If you need to know which clinic a resource belongs to as clinical data, use Organization / Location references, which are modelled and resolvable — not this.