Every custom extension in a public API is a promise to consumers, and the promise has costs the API author does not always see up front. Versioning, documentation, terminology drift, consumer inertia, and support burden all follow every extension URL that appears in a published payload. Choosing to add one is not free. The site's Extension registry audit flags custom URLs so consumers can plan around them. For the wider FHIR framing, our FHIR coverage has more.
The Documentation Cost
Every custom extension needs a StructureDefinition, a canonical URL, a human-readable description, a value type, cardinality, and prose that says what it means. Every consumer needs to be told about it. Every version of the extension needs the same package.
Skipping any of that produces payloads consumers cannot interpret and support tickets that cannot be triaged.
For the specific pattern of doing this well, documenting extensions so the next team can maintain them is the deep dive.
The Versioning Cost
An extension URL is a canonical identifier. If the meaning of the extension changes — the value type, the cardinality, the semantic — the URL should change too. That is versioning by URL, and it works but it means every version of the extension is a permanent commitment.
Silent semantic changes on an unchanged URL produce consumers that read old payloads correctly and new payloads incorrectly. That is where the "silent broken" incidents come from.
The Consumer-Inertia Cost
Consumers that adopt a custom extension will not remove it easily. If the extension is retired, versioned, or renamed, every consumer has to update. That coordination cost lives with the API author, not with the consumer.
The right rule: adopt a custom extension only when the alternative — a public extension, a related resource, a profile rule — is genuinely worse. For the base decision, when a FHIR extension is the right answer, and when it isn't covers the framing.
The Modifier Cost
Custom modifier extensions are the highest-cost category. Consumers that do not recognize them must reject the resource. That means every consumer needs to know about the modifier extension before they can process any resource that might carry it.
That is a coordination problem, not a design problem. Custom modifier extensions in a public API should be exceedingly rare. For the mechanic, extensions vs modifier extensions: the modelling difference that matters covers the split.
The Terminology-Drift Cost
Extensions with coded values carry bindings to value sets. If the value set drifts — codes get added, retired, or renamed — the extension's meaning drifts too. That is invisible to consumers reading the URL alone.
Publish the binding along with the extension. When the value set changes, publish a new version. Keep the URLs stable when meaning is stable; change them when meaning changes.
The Cross-Version Cost
Extensions defined on R4 do not automatically apply to R5. Custom extensions have to be reviewed and re-published per FHIR version. Consumers moving between versions need explicit guidance on which extensions still apply.
Skipping the cross-version review produces custom extensions that work on old servers and fail on new ones.
The Support Cost
Every custom extension is a support surface. Consumers ask what it means, how it interacts with related fields, why it fires or does not. That support load lives with the API author.
Public extensions are supported by their publishing bodies — HL7, US Core, IPS, and so on. Custom extensions are supported by you.
When Custom Is Worth It
- The gap is real
- No public extension covers it
- The data belongs on this resource type
- Consumers are clearly identifiable and can be coordinated
- Long-term maintenance is planned
If all five are true, custom is worth it. Otherwise, look for an alternative.
The Short Version
Custom extensions are not free. Documentation, versioning, consumer inertia, modifier cost, terminology drift, cross-version work, and support all follow every URL you publish. Adopt them deliberately, publish them well, and version them carefully.
Sources
- HL7 canonical FHIR extensibility chapter - HL7 canonical FHIR extensibility chapter