A validator that refuses every extension URL it does not recognize is a validator that will reject nine out of ten real-world payloads. A validator that accepts every extension without checking is a validator that lets modifier-extension misuse slip through. The right middle is a validator that classifies URLs into known-required, known-optional, and unknown, and dispatches on the class rather than on the URL. The site's Extension registry audit does exactly that classification. For the wider FHIR framing, related FHIR explainers has more.
The Three Classes
- Known-required — the profile marks this extension as mustSupport
- Known-optional — the profile declares this extension but does not require it
- Unknown — the URL is not declared in any profile the validator knows about
Each class has a different disposition. Getting them right is the difference between useful validation and either over-strict or under-strict.
Known-Required: The Non-Negotiables
When a profile marks an extension as mustSupport and the extension is a modifier extension, the validator must fail on unrecognized URLs. When the extension is regular, the validator can accept or warn based on the profile's cardinality.
Missing a mustSupport regular extension where cardinality is 0..1 is a warning, not an error. Missing one where cardinality is 1..1 is an error.
For the profile-reading side, reading an IG for the extensions you actually need covers the mechanic.
Known-Optional: The Grey Zone
Extensions that the profile declares but does not require are usually safe to accept. The validator's job is to verify the value type and cardinality when the extension is present, not to require presence.
The catch: value-set bindings on optional extensions still apply. An optional US Core extension whose value violates a required binding is still an invalid payload.
Unknown: The Choice Point
The validator sees an extension URL it does not recognize. Options:
- Reject if the URL is in
modifierExtension[]— safe default per the spec - Accept if in
extension[]— safe default per the spec - Warn on all unknown URLs regardless — noisy but useful during onboarding
- Silent — accept everything, catch nothing (do not do this)
The spec-safe defaults are the middle two. The warn-on-all option is useful for a specific development window; production validators should not emit noise for optional extensions from known IGs.
Where Version Suffixes Matter
Extension URLs can carry version suffixes. http://hl7.org/fhir/StructureDefinition/us-core-race|3.1.1 is the versioned form. Validators that match on the exact URL miss the versioned form. Validators that match on prefix accept both.
Match on prefix. Allow the version suffix. Log any mismatch between server-configured version and payload-declared version for later review.
For the wider registry-problem context, the extension URL registry problem is the entry.
Cross-Version Behavior
R4 extensions and R5 extensions overlap but are not identical. A validator processing an R4 payload should use the R4 extension registry, not the R5 one. Servers that host both versions need to route accordingly.
Skipping the version dispatch produces validation failures on well-formed payloads that happen to target a different FHIR version than the validator was configured for.
The Nested-Extension Case
Complex extensions have sub-extensions with their own URLs and value types. Validating the top-level URL is not enough. The validator has to walk the nested structure.
us-core-race.ombCategory is required; us-core-race.detailed is optional. A validator that stops at the top level does not catch a missing ombCategory.
What The Audit Tool Reports
The audit tool at /lint-lab/audit-extension-urls/ classifies every extension URL and surfaces missing mustSupport extensions. That single readout is what most integrations need before shipping. For US Core specifically, finding US Core extensions your data has to carry is the entry.
The Short Version
Three classes: known-required, known-optional, unknown. Different dispositions per class. Match URLs by prefix to survive version suffixes. Validate nested complex extensions. Route by FHIR version. That is the validator that survives real traffic.
Sources
- HL7 canonical FHIR extensibility chapter covering - HL7 canonical FHIR extensibility chapter covering validation semantics