Canonical URLs¶

Every conformance artifact this specification defines -- profile, extension, code system, value set, naming system, capability statement, operation definition -- is published on one base:

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

The structure of that URL is described under Canonical URL structure. This page is about the base itself: what it means that an artifact is published there, and what to do about the artifacts the software currently writes somewhere else.

The rule¶

An artifact this guide publishes is published on this base. The canonical shown on an artifact's own reference page is the address it is defined at, the address a writer emits, and the address a reader resolves. Every artifact the specification defines is listed on the artifacts index; an artifact not listed there is not part of this specification, whatever its URL looks like.

Published canonical URLs are forever. A rename is a breaking change even when the FSH still compiles, which is why the only free moment to move one is the moment before the first record is written against it.

The exception, and it is live today¶

Some artifacts this guide publishes are written by Nexus EMR today at a different address, on a host this specification does not govern. Those addresses were minted in application code before the guide declared the artifact, and when the guide declared it, the guide did not follow them there. A specification that adopts every address its implementation happens to have minted has no canonical base at all.

These are not alternative identifiers, and they are not a second namespace. Each one is a defect, each is tracked, and each is being migrated onto the canonical base. Where records are already filed under the pre-migration address the migration moves stored data as well as a constant, which is why it does not complete in a single release.

What to do¶

If you author data, write the canonical. It is the address this guide describes, it is the address the artifact's own page shows, and it is the address the migration ends at. A writer still emitting a pre-migration address is producing records this guide does not describe.

If you ingest data Nexus EMR writes today, expect the pre-migration address until the migration completes, alongside the canonical for anything written after the writer moves. The two are the same artifact under two names and nothing reconciles them automatically: a reader that resolves only the canonical silently misses every record filed before the writer moved, and silence is the failure mode here -- nothing errors, the data is simply absent.

Match both addresses exactly, as the table lists them, and derive neither from the other. The addresses a row gives are the whole contract for that artifact: resolve those, literally, and treat anything else as a different artifact. This is the only rule that holds across every row.

A shared final segment is a convenience that holds for some pairs and not others. Several pairs below do end in the same word, and where a pair does, matching that segment happens to read both -- but that is a property of those rows rather than something to build a reader on. Many do not share one: meta-updated-by is written as UpdatedBy, and the two PCR extensions as exists and replacedByInPcr, none of which has a segment in common with its canonical, so a suffix rule misses every pre-migration record of those. Others (task-code, graph, document-type) are written under a segment short enough that a suffix rule would have to match loosely enough to collide with unrelated URLs.

And one final segment is an active trap: letter-template ends two different addresses. http://services.well.com/fhir/tags/document-reference/letter-template is LIVE -- the Composition.meta.tag system saying which stored template a letter was composed from, listed below and migrating to CodeSystem/nexus-template. http://services.well.com/fhir/categories/letter-template is RETIRED -- a DocumentReference.category system carrying one fixed code that marked a resource as BEING a template, from when a template was a DocumentReference. They are different artifacts answering different questions -- "which template was this letter written from" and "is this resource a template" -- and only the first is migrating, so a reader matching on the final segment answers one question with the other. The retired code has its own home on this base if one turns out to be needed: nexus-letter-template in nexus-composition-type.

Do not adopt a pre-migration address in anything you author. Not in a profile, not in a value set binding, not in a stored system or url value of your own. Reading one is a transitional necessity; writing one extends a defect into a second system.

The affected artifacts¶

Each of these is published by this guide on the canonical base and written by Nexus EMR today at the address in the third column. One row qualifies that column by element, because for that artifact which address is written depends on where the value sits. Rows are grouped by the migration they belong to, because the artifacts in one group move together; within a group they are alphabetical.

Artifact	Canonical	Written today at	Migration group
`composition-billing`	`https://fhir.apps.health/StructureDefinition/composition-billing`	`http://services.well.com/fhir/StructureDefinition/composition-billing`	Group 1
`composition-ehr-share`	`https://fhir.apps.health/StructureDefinition/composition-ehr-share`	`http://services.well.com/fhir/StructureDefinition/composition-ehr-share`	Group 1
`composition-note-setup`	`https://fhir.apps.health/StructureDefinition/composition-note-setup`	`http://services.well.com/fhir/StructureDefinition/composition-note-setup`	Group 1
`nexus-note-draft-id`	`https://fhir.apps.health/NamingSystem/nexus-note-draft-id`	`https://fhir.apps.health/nexus-harness/business-id`	Group 1
`nexus-template`	`https://fhir.apps.health/CodeSystem/nexus-template`	`http://services.well.com/fhir/tags/document-reference/letter-template`	Group 1
`action-on-abnormal`	`https://fhir.apps.health/StructureDefinition/action-on-abnormal`	`http://services.well.com/fhir/ServiceRequest/action-on-abnormal`	Group 2
`diagnostic-report-acdr-sent`	`https://fhir.apps.health/CodeSystem/diagnostic-report-acdr-sent`	`http://services.well.com/fhir/tags/diagnostic-reports/acdr-sent`	Group 2
`diagnostic-report-category`	`https://fhir.apps.health/CodeSystem/diagnostic-report-category`	`http://well.company/diagnostic-report-category`	Group 2
`diagnostic-report-sent-downstream`	`https://fhir.apps.health/CodeSystem/diagnostic-report-sent-downstream`	`http://services.well.com/fhir/tags/diagnostic-reports/sent-downstream`	Group 2
`report-display-title`	`https://fhir.apps.health/StructureDefinition/report-display-title`	`http://services.well.com/fhir/report-display-title`	Group 2
`hrm-report-class`	`https://fhir.apps.health/CodeSystem/hrm-report-class`	`http://services.well.com/fhir/CodeSystem/hrm-report-class`	Group 3
`hrm-subclass`	`https://fhir.apps.health/CodeSystem/hrm-subclass`	`http://services.well.com/fhir/CodeSystem/hrm-subclass`	Group 3
`hrm-send-enabled`	`https://fhir.apps.health/CodeSystem/hrm-send-enabled`	`http://services.well.com/fhir/tags/location/hrm-send-enabled`	Group 3
`hrm-filler`	`https://fhir.apps.health/NamingSystem/hrm-filler`	`http://services.well.com/fhir/identifier/hrm-filler`	Group 3
`hrm-message-unique-id`	`https://fhir.apps.health/NamingSystem/hrm-message-unique-id`	`http://services.well.com/fhir/identifier/hrm-message-unique-id`	Group 3
`hrm-content-checksum`	`https://fhir.apps.health/NamingSystem/hrm-content-checksum`	`http://services.well.com/fhir/identifier/hrm-content-checksum`	Group 3
`hrm-file-version`	`https://fhir.apps.health/NamingSystem/hrm-file-version`	`http://services.well.com/fhir/identifier/hrm-file-version`	Group 3
`hrm-sending-facility`	`https://fhir.apps.health/NamingSystem/hrm-sending-facility`	`http://services.well.com/fhir/identifier/hrm-sending-facility`	Group 3
`hrm-accompanying-subclass`	`https://fhir.apps.health/StructureDefinition/hrm-accompanying-subclass`	`http://services.well.com/fhir/observation/hrm-accompanying-subclass`	Group 3
`hrm-accompanying-description`	`https://fhir.apps.health/StructureDefinition/hrm-accompanying-description`	`http://services.well.com/fhir/observation/hrm-accompanying-description`	Group 3
`hrm-accompanying-mnemonic`	`https://fhir.apps.health/StructureDefinition/hrm-accompanying-mnemonic`	`http://services.well.com/fhir/observation/hrm-accompanying-mnemonic`	Group 3
`nexus-task-code`	`https://fhir.apps.health/CodeSystem/nexus-task-code`	`http://well.company/task-code`	Group 4
`task-business-status`	`https://fhir.apps.health/CodeSystem/task-business-status`	`http://well.company/task-business-status`	Group 4
`valueset-secondary-coding`	`https://fhir.apps.health/StructureDefinition/valueset-secondary-coding`	`https://fhir.nexus.health/StructureDefinition/valueset-secondary-coding` `https://fhir.nexus.health/StructureDefinition/valueset-secondary-icd10`	Group 5
`meta-updated-by`	`https://fhir.apps.health/StructureDefinition/meta-updated-by`	`http://services.well.com/fhir/StructureDefinition/UpdatedBy`	Group 6
`contact-by-email`	`https://fhir.apps.health/CodeSystem/contact-by-email`	`http://services.well.com/fhir/CodeSystem/contact-by-email`	Group 7
`contact-by-fax`	`https://fhir.apps.health/CodeSystem/contact-by-fax`	`http://services.well.com/fhir/CodeSystem/contact-by-fax`	Group 7
`contact-by-hrm`	`https://fhir.apps.health/CodeSystem/contact-by-hrm`	`http://services.well.com/fhir/CodeSystem/contact-by-hrm`	Group 7
`contact-by-mail`	`https://fhir.apps.health/CodeSystem/contact-by-mail`	`http://services.well.com/fhir/CodeSystem/contact-by-mail`	Group 7
`contact-by-phone`	`https://fhir.apps.health/CodeSystem/contact-by-phone`	`http://services.well.com/fhir/CodeSystem/contact-by-phone`	Group 7
`nexus-harness-graph`	`https://fhir.apps.health/NamingSystem/nexus-harness-graph`	`https://nexus.awaremd.com/summary-id/graph` -- on `meta.tag` only; `Reference.identifier.system` already carries the canonical	Group 8
`nexus-harness-run`	`https://fhir.apps.health/NamingSystem/nexus-harness-run`	`https://nexus.awaremd.com/summary-id/run-id`	Group 8
`nexus-summary-payload`	`https://fhir.apps.health/StructureDefinition/nexus-summary-payload`	`https://nexus.awaremd.com/summary-id/StructureDefinition/summary-payload`	Group 8
`appointment-acdr-arrived`	`https://fhir.apps.health/CodeSystem/appointment-acdr-arrived`	`http://services.well.com/fhir/tags/appointment/acdr-arrived`	Group 9
`appointment-invoiced`	`https://fhir.apps.health/StructureDefinition/appointment-invoiced`	`http://services.well.com/fhir/StructureDefinition/appointment-invoiced`	Group 9
`appointment-ocean-sent`	`https://fhir.apps.health/CodeSystem/appointment-ocean-sent`	`http://services.well.com/fhir/tags/appointment/ocean-sent`	Group 9
`nexus-clinical-role-assignment`	`https://fhir.apps.health/NamingSystem/nexus-clinical-role-assignment`	`http://services.well.com/fhir/NamingSystem/user-clinical-role-assignment`	Group 10
`nexus-document-type`	`https://fhir.apps.health/CodeSystem/nexus-document-type`	`http://services.well.com/fhir/CodeSystem/document-type`	Group 11
`care-element-target`	`https://fhir.apps.health/NamingSystem/care-element-target`	`https://nexus.awaremd.com/care-element-target`	Group 12
`health-card-eligibility`	`https://fhir.apps.health/StructureDefinition/health-card-eligibility`	`http://services.well.com/fhir/identifier/eligibility`	Group 12
`observation-sub-id`	`https://fhir.apps.health/NamingSystem/observation-sub-id`	`http://services.well.com/fhir/observation-sub-id`	Group 12
`ocean-referral-tag`	`https://fhir.apps.health/CodeSystem/ocean-referral-tag`	`http://services.well.com/fhir/tags/integration-provider/ocean`	Group 12
`pcr-registered`	`https://fhir.apps.health/StructureDefinition/pcr-registered`	`http://services.well.com/fhir/pcr/exists`	Group 12
`pcr-replaced-by-propagated`	`https://fhir.apps.health/StructureDefinition/pcr-replaced-by-propagated`	`http://services.well.com/fhir/pcr/replacedByInPcr`	Group 12
`reporting-export-stamp`	`https://fhir.apps.health/StructureDefinition/reporting-export-stamp`	`https://well.company/reporting/export`	Group 12
`reporting-run`	`https://fhir.apps.health/NamingSystem/reporting-run`	`https://well.company/reporting/export`	Group 12
`resource-hidden`	`https://fhir.apps.health/CodeSystem/resource-hidden`	`http://services.well.com/fhir/tags/hidden`	Group 12

Five of these need reading with their own pages, because the shape of the exception differs:

meta-updated-by is the long tail. It rides meta on every version of every resource ever saved, so version history keeps the pre-migration address indefinitely even once new versions stop carrying it. Plan for a reader that sees both permanently rather than for a cutover.
composition-billing, composition-ehr-share and composition-note-setup have filed clinical notes behind them. The Clinical Documents handbook page carries the fuller treatment, including the two block extensions that made this same move successfully while it was still free.
valueset-secondary-coding has two pre-migration addresses, not one. The second is an older spelling from when the extension was scoped to a single classification; it is the same extension under a narrower name -- same value, same reading rule, and the classification named by valueCoding.system rather than by the URL -- so this guide declares one canonical for both rather than a second artifact for the special case. Match all three addresses: the older spelling shares no segment with the canonical.
nexus-harness-graph has moved on one element and not the other. As the graph's identity as an ACTOR -- Reference.identifier.system on Task.requester, Provenance.agent.who and Composition.author, always with Reference.type = "Device" -- Nexus EMR already writes the canonical, so a reader of the actor needs one address and not two. The same graph name also travels as run LINEAGE, as the system of a Coding in meta.tag beside the run tag, and that writer is still on the pre-migration address. Which address to expect therefore depends on which element you are reading: meta.tag needs both, a logical Device reference needs only the canonical.
reporting-export-stamp and reporting-run share one pre-migration address, and one of them changes shape as well as host. That single address is doing two jobs today: the system of the reporting extract's meta.tag codings, and the identifier authority for the run on Bundle.identifier. One address cannot honestly be both, so the guide separates them, and a reader tells them apart by where the value sits rather than by the address. The run half stays an identifier authority and only moves host. The stamp half becomes an EXTENSION on Bundle.meta rather than a vocabulary of tag keys: the stamp's fields carry values, and a Coding has no element that can hold one -- Coding.display is the label R4 fixes for a code, not a slot for a fact. So there is no address-for-address swap to make on that half; write the extension.

Artifacts moving onto the canonical base that this guide does not yet publish are not listed here: until an artifact appears on the artifacts index, there is nothing for a consumer to migrate to. Those are declared as they are modelled.

A second kind of exception: the right host, the wrong path¶

The table above is about a host this specification does not govern. There is a smaller family where the host is already fhir.apps.health and the path is what is wrong: the address is written under a /tags/... segment, and tags is not an artifact type. This base publishes an artifact at /[artifact-type]/[artifact-id] and nothing else.

These are not rows in the table above, because they are not the same defect. A foreign host reads as somebody else's mistake. An on-base address at a shape this guide's own rule forbids would read as a sanctioned second URL form on the canonical base, which is worse -- so the guide declines to ratify it, declares the artifact where the rule says, and records the written address here and on the artifact's own page.

Artifact	Canonical	Written today at
`document-reference-readonly`	`https://fhir.apps.health/CodeSystem/document-reference-readonly`	`https://fhir.apps.health/tags/document-reference/readonly`
`nexus-send-channel`	`https://fhir.apps.health/CodeSystem/nexus-send-channel`	`https://fhir.apps.health/tags/attachment-packet/send-channel`

Both are the system of a Coding in meta.tag, and the reading rule is the one every other row gets: match both addresses exactly, and derive neither from the other. Each is live in stored codings, so a reader resolving only the canonical misses every record written before the writer moves -- silently, because nothing errors and the data is simply absent.

Two addresses that are deliberately not part of this¶

Not every off-canonical address is a defect. Two are settled where they are, and neither is migrating.

Address	Why it stays
`http://services.well.com/fhir/auth/tenant-id` -- the tenant stamp	This guide adopted the extension at that exact URL in 1.17.0. The off-canonical host is the signal that it is platform infrastructure rather than spec surface, and that choice is documented on the artifact.
`http://services.well.com/fhir/NamingSystem/user-id` -- the EMR user-account link	Declared, not merely observed. `NamingSystem` has no `url` of its own: it states the identifiers a system is known by rather than defining a second artifact, so declaring a private authority at its own URI is safe. Moving it is a data migration across every stamped `Practitioner`, not a spec edit.

Both are described under Private infrastructure you will see on the wire. Do not build on either: neither URL is resolvable, both values are opaque, and neither carries a breaking-change guarantee.