Extension documentation is where teams pay the debt for the extensions they minted a year ago. The developer who introduced the extension is on a different team. The consumers who read it need to know what it means. The support engineer triaging a related incident needs to correlate it back. Documentation that survives that rotation is small work at emission time and a lot of savings at maintenance time. The site's Extension registry audit surfaces documented extensions from public IGs; custom ones benefit from the same treatment. For the wider FHIR framing, the healthcare interoperability hub has more.
What The Documentation Needs To Cover
- Canonical URL — the identifier
- Value type — what shape the value takes
- Cardinality — how many are allowed on the parent
- Semantic — what the extension means, in plain English
- Binding — value set if the value is coded, with strength
- Modifier or regular — which array it lives in
- Publisher — who owns the extension
- Version history — every version that has shipped
Eight fields. Two paragraphs of prose. Every extension in your API should have this level of coverage. For the design side, custom extensions in a public API: hidden costs covers the trade-offs.
The StructureDefinition Is The Primary Artefact
A StructureDefinition captures most of the fields above in a machine-readable form. Publishing one for every custom extension is not optional if you want your consumers to use tooling.
The right pattern: StructureDefinition lives at the canonical URL (or a documented alternative), gets versioned like any other artefact, and is the source of truth. Prose documentation references it, does not replicate it.
Include Examples
Extensions read from a spec alone are ambiguous. Examples clarify.
For every extension, publish at least:
- One example resource with the extension populated typically
- One example resource where the extension is absent (if optional)
- One example of a common misuse and what it should look like instead
Consumers new to the extension read the examples first and the prose second. Skipping examples doubles the onboarding time.
Note The Modifier Distinction Loudly
If the extension is a modifier extension, say so in the first paragraph of the prose. Consumers must know this before they process any resource that might carry it.
Hiding the modifier status three pages into the documentation produces consumers that miss the distinction and process resources unsafely. For the split, extensions vs modifier extensions: the modelling difference that matters is the entry.
Version The Documentation
- Every change to the extension changes the version
- The version lives in the URL suffix and in the StructureDefinition
- The version history documents what changed and why
- Old versions remain accessible; consumers may still be on them
Silent updates that change meaning without a version bump produce the "consumers process old and new payloads differently" incident.
Publish The Retire Path
Some extensions get retired. Document the retirement:
- Which version was the last active
- What replaces the extension, if anything
- When consumers are expected to migrate
- What happens if payloads still carry the retired extension
Retirement without documentation produces confusion and stuck consumers.
Include The Rationale
Why does this extension exist? Every custom extension has a story: a specific gap in the base spec, a specific consumer need, a specific workflow that could not be modelled otherwise.
Document the rationale. It is what tells the next team whether to keep the extension, deprecate it, or replace it. Without a rationale, every future team just carries the extension forward without evaluating it.
For US Core Extensions, Point At The Canonical Docs
Where US Core covers your extensions, do not re-document them. Link to the US Core StructureDefinition and note which version you support. For the specific extensions, finding US Core extensions your data has to carry is the entry.
The Short Version
StructureDefinition first, examples second, modifier flag loud, versioning explicit, retirement documented, rationale preserved. Documentation is a fifteen-minute investment per extension and a permanent savings when your team rotates.
Sources
- HL7 canonical FHIR extensibility chapter framing - HL7 canonical FHIR extensibility chapter framing documentation requirements