FHIR extension URLs look like they should resolve to a canonical StructureDefinition on the web. Sometimes they do. Often they do not. And the difference between "identifier" and "network location" is where a real class of interoperability incidents hides. Understanding what the URL is — and is not — is the fastest way to design an extension strategy that survives. The site's Extension registry audit tests URLs against known registries. For the wider FHIR framing, deeper FHIR walkthroughs for US teams has more.
What The URL Is
An extension URL is a canonical identifier. It uniquely names the extension. It is what a consumer dispatches on. It is what a validator matches against.
That is all it is required to be.
What The URL Is Not
An extension URL is not required to resolve to anything on the network. It does not have to be a real HTTP endpoint. It does not have to serve the StructureDefinition when fetched. It is an identifier that happens to look like a URL.
Publishing the definition at the URL is a courtesy — a very valuable courtesy — but it is not a requirement of the spec.
The Registry Problem
Because URLs are just identifiers, there is no central registry that owns the extension URL namespace. Each publishing body maintains its own:
- HL7 maintains
http://hl7.org/fhir/StructureDefinition/URLs - US Core maintains
http://hl7.org/fhir/us/core/StructureDefinition/ - IPS maintains
http://hl7.org/fhir/uv/ips/StructureDefinition/ - SDC, VRDR, SMART, CARIN, Da Vinci — each has its own prefix
- Private organizations own their own domains
The naming is decentralized by design. That is a feature — new IGs can mint their own extensions without asking permission — and a hazard — no one enforces uniqueness across bodies.
What The Audit Tool Does
The audit at /lint-lab/audit-extension-urls/ walks a resource or Bundle, collects every extension URL, and matches each against major registries. It classifies each URL as:
- Known-public (one of the major IGs)
- Known-community (published community registries)
- Unknown (custom or unlisted)
That classification is what a new integrator needs before shipping. Consumers can then plan around the mix.
Version Suffixes On URLs
Some extension URLs carry version suffixes: http://hl7.org/fhir/StructureDefinition/us-core-race|3.1.1. That is FHIR canonical URL versioning. It lets consumers pin to a specific version of the extension.
Not every payload sends the version. Not every validator matches on it. The safe pattern: emit versions when you know them, match with prefix flexibility when consuming.
For the validation implications, extension validation that doesn't trip on optional URLs is the entry.
The Private-URL Problem
Private organizations that mint their own extension URLs face a choice: use a URL under their own domain (safe from collision, invisible to public consumers) or under a well-known FHIR domain (visible but coordination-required).
Most private extensions live under organization domains. That is the right pattern for private consumption. The audit tool flags them as unknown-custom, which is a signal to publish documentation elsewhere.
When Consumers See An Unknown URL
- Regular extension → ignore safely
- Modifier extension → refuse to process the resource
The unknown-URL case is one of the strongest reasons to avoid custom modifier extensions in a public API. For the design side, custom extensions in a public API: hidden costs covers the mechanics.
What Would A Central Registry Solve
- Discovery — find an extension by concept, not just URL
- Deduplication — avoid two extensions for the same meaning
- Version coordination — see all versions of an extension in one place
The Simplifier registry and community efforts approximate parts of this. None is authoritative. That is unlikely to change soon.
The Short Version
Extension URLs are identifiers, not addresses. Registries are federated. Audit tooling catches the unknown ones. Private organizations mint URLs under their own domains. For the specific US Core case, finding US Core extensions your data has to carry is the entry.
Sources
- HL7 canonical section on canonical URLs and identifier - HL7 canonical section on canonical URLs and identifier semantics