Additional Resources is a formal extensibility mechanism introduced in FHIR R6 that allows new resource types to be defined outside the core FHIR specification while still functioning as first-class FHIR resources. They are defined in Implementation Guides (called "Incubator IGs"), published on their own release cycles, and are expected to eventually migrate back into the core specification once stable.
The mechanism exists because R6 is the first fully normative FHIR release — once published, no breaking changes are allowed. Resources that are still immature (FMM 0-2) cannot be frozen normatively, so they need an alternative development pathway.
"Our market feedback is very strong that further change to the FHIR resources is getting very expensive, and one of the few incentives for the market to move to R6 is stability." — Grahame Grieve, FMG communication to committees (Aug 2025)
From build.fhir.org/resource.html#additional:
- Additional Resources SHALL be registered with HL7
- Unapproved resources SHALL NOT be used
- Registered resources are given an official name by HL7
- All approved resources SHALL have a publicly available definition using a StructureDefinition published as part of an ImplementationGuide at the canonical URL
- Definitions are reviewed for quality by HL7 prior to approval
- Proposals are submitted via the Zulip channel #Additional-Resource-Proposals
- HL7 maintains an approved list in the IG Registry with a functional listing at a GitHub endpoint containing
additional-resources.json
From build.fhir.org/structuredefinition.html (notes section):
| Field | Requirement |
|---|---|
| Canonical URL | Must be outside http://hl7.org/fhir namespace |
fhirVersion |
SHALL be 6.0.0 or a subsequent published version |
kind |
SHALL be resource |
abstract |
SHALL be false |
type |
SHALL match the canonical URL exactly |
baseDefinition |
SHALL reference Resource or DomainResource |
derivation |
SHALL be specialization |
| Root element path | SHALL be the tail of the canonical URL |
| Root element name | SHOULD be the HL7-assigned name |
Additional resources MAY use the structuredefinition-implements extension to declare adherence to CanonicalResource or MetadataResource interfaces.
Compartments are defined using the (yet to be published) extension http://hl7.org/fhir/StructureDefinition/additional-resource-compartment.
Additional resources carry an extra property resourceDefinition alongside resourceType:
{
"resourceType": "ViewDefinition",
"resourceDefinition": "http://hl7.org/fhir/uv/sql-on-fhir/StructureDefinition/ViewDefinition|2.0.0-pre",
"id": "a-valid-id"
}The resourceDefinition property:
- Is a versioned canonical reference to the StructureDefinition
- Is a format-level feature (like
resourceTypeitself — not in any structural definition) - SHALL NOT be present if the
resourceTypeis one defined in the core specification
Similarly represented in XML with namespace and definition references.
From the R6 spec:
CapabilityStatement.rest.resource.typecontains the resource type name from the HL7 registryCapabilityStatement.rest.resource.definitioncontains a version-specific reference to the definition- The
definitionelement SHALL NOT be present for core resources - Search parameters for additional resources are exposed through CapabilityStatement like any other resource
- When an additional resource migrates to core, search parameter canonical URLs do not change (versions might)
The process decided by FMG:
- Work groups decide which IG hosts their resources (existing or new)
- If new IG needed, file an IG proposal with HL7
- Work groups copy resource definitions into their incubator IG
- Grahame Grieve removes resources from the core build (to avoid git conflicts)
- References to moved resources in core become extensions
- Core spec text can link to additional resources as "work in progress" but comparison text should move to the incubator IG
"I will yank them because [of] the super high likelihood of git conflicts." — Grahame Grieve
"Your IG will behave like a normal IG that happens to contain additional resources." — Lloyd McKenzie
- The responsible WG/WGs request moving into core
- FMG approves (criteria TBD)
- Resource is added in the next FHIR ballot cycle
- Published with the next milestone release
- The original additional resource definition is deprecated and eventually removed
- Post-migration,
resourceDefinitionmay remain in instances but SHOULD NOT be added; if present, the version SHALL be correct
FMG performed a systematic analysis of resource maturity using:
- FMM (FHIR Maturity Model) levels
- Simplifier profiling/usage numbers (from Ewout Kramer / Ward Weistra)
- Git commit analysis across R2-R6
- Jira ticket activity
- Example/extension reference counts
Published at fhir.org/maturity/evaluation.html.
Category 1 — Recommended to move:
| Group | WG | Resources |
|---|---|---|
| Inventory | OO+PHX | FormularyItem, InventoryItem, InventoryReport |
| PA Development | PA | PersonalRelationship, EncounterHistory, InsuranceProduct |
| OO Development | OO | DeviceDispense, BiologicallyDerivedProductDispense, Transport, DeviceAssociation, DeviceUsage |
| PC Development #1 | PC | ConditionDefinition |
| Permission | SEC | Permission |
Category 2 — Committee should consider:
| Group | WG | Resources |
|---|---|---|
| Medication Definition | BRR | MedicinalProductDefinition, PackagedProductDefinition, AdministrableProductDefinition, ManufacturedItemDefinition, Ingredient, ClinicalUseDefinition, RegulatedAuthorization, SubstanceDefinition |
| Detailed Observation | CG+II | GenomicStudy, MolecularDefinition, MolecularSequence, ImagingSelection |
| Testing | FHIR-I | TestPlan, TestReport |
| Enrollment | FM | EnrollmentRequest, EnrollmentResponse |
| PC Development 2 | PC | ClinicalAssessment, Linkage |
| Evidence | CDS | ArtifactAssessment, Citation, Evidence, EvidenceVariable |
Category 3 — Stay in core: ResearchStudy, ResearchSubject, EventDefinition
Category 4 — FMM 3+ resources: Stay by default (includes CarePlan, MedicationRequest, etc.)
Removed entirely (not additional resources): SubstanceNucleicAcid, SubstancePolymer, SubstanceProtein, SubstanceReferenceInformation, SubstanceSourceMaterial (FMM 0, content moved into other resources or extensions by BRR WG decision)
| Repository | WG | Description | Key Resources |
|---|---|---|---|
| HL7/fhir-testing-ig | FHIR-I | First example IG; testing framework | TestScript, TestPlan, TestReport |
| HL7/api-incubator-ig | FHIR-I | API/infrastructure features | StructureMap/FML, others |
| HL7/admin-incubator | PA | Patient Admin resources | PersonalRelationship, EncounterHistory, InsuranceProduct |
| HL7/oo-incubator | OO | Supply, dispense, transport | DeviceDispense, BiologicallyDerivedProductDispense, Transport, InventoryItem, etc. |
| HL7/immunization-incubator | PHX | Immunization resources | ImmunizationEvaluation, ImmunizationRecommendation |
| HL7/ebm-incubator | CDS | Evidence-based medicine | Citation, Evidence, EvidenceVariable, ArtifactAssessment |
| HL7/cg-incubator | CG | Clinical Genomics | GenomicStudy, MolecularDefinition |
| HL7/data-access-policies | SEC | Access control policies | Permission |
| HL7/sample-incubator-ig | — | Template/skeleton for new incubator IGs | — |
The community debated whether "Additional Resources" implies second-class status:
"Additional Resources screams secondary and less important to me. Graham said this was an act of love, to enable resources to be nurtured and grow." — David Barwin
Alternative names proposed: "Maturing Resources", "Incubating Resources", "Changeable Resources", "Emerging Resources". The term "Incubator" was adopted for the IGs themselves (e.g., "OO FHIR Incubator"), while the formal spec term remains "Additional Resources".
A critical unsolved problem: when a resource moves from core to additional, core resources can no longer declare it as a reference target.
"Core resources can't declare additional resources as allowed targets — even if they might be legitimate targets — because core doesn't know the additional resources exist." — Lloyd McKenzie
Examples:
- Coverage (core) referenced InsurancePlan (now additional)
- DeviceDefinition (core) referenced ChargeItemDefinition (now additional)
- SubstanceDefinition.informationSource referenced Citation (now additional) — resolved by converting to an extension
Moving Permission to additional resources while keeping Consent in core raised GDPR-related concerns. In EU contexts, consent is only one of six legal bases for data processing (GDPR Article 6). The risk is implementers stretching Consent to cover all permission scenarios because Permission is "additional" and less visible.
Resolution approach: Consent resource description should explicitly point to Permission and clarify scope boundaries.
SUSHI limitations:
- SUSHI auto-lists resources in IG JSON incorrectly for additional resources
- Workaround:
resources: Bundle/id: omitin sushi-config.yaml - SUSHI requires snapshots for creating instances; additional resource StructureDefinitions from core don't include snapshots
- Workaround: use build output XML (which includes snapshot) as input
- FSH support for authoring additional resource definitions is limited but may work for simple cases
IG Publisher: Works when resources are placed in input/resources folder following the pattern established by fhir-testing-ig. Search parameter bundles need special handling.
Concern raised about additional resource IGs depending on each other (e.g., Citation referenced by other additional resources). FMG decision: no single mega-IG for all additional resources, to avoid lifecycle coupling. But a single registry/list will exist to help discoverability.
Some resources that moved out of core are temporarily unavailable until work groups get their incubator IG CI-builds running:
"Until the work group gets the CI-build of their 'work in progress' IG up and running, they may be temporarily unavailable." — Lloyd McKenzie (Jan 2026)
- Resources that moved to additional status disappear from the core spec
- References to those resources from core elements become extensions in the incubator IGs
- JSON/XML instances of additional resources need the
resourceDefinitionproperty - CapabilityStatements need
definitionreferences for additional resources - Search parameters move with the resources; canonical URLs stay the same
- Operations, value sets, and code systems move with their resources
- Additional resources are still FHIR resources — same REST API, same search, same profiling
- "The process of defining a resource isn't any different when it's an additional resource" (FMG)
- Profiling works the same: "Once defined, additional resources are profiled like any other resource" (spec)
- Base Resource Definitions — Additional Resources
- StructureDefinition Notes
- JSON Representation
- XML Representation
- Versions and Changes
- R6 Ballot Introduction
- Resource List
- #committers > Additional Resources — Migration process, WG responsibilities (45 messages)
- #fmg > Assessment of Resources for removal from R6 — Maturity scoring, FMG recommendations (67 messages)
- #fmg > Reference Breaking Changes for Additional Resources? — Cross-reference problems (4 messages)
- #Security and Privacy > Permission as additional resource — Consent/Permission scope, GDPR (97 messages)
- #shorthand > Sushi problem for additional resources — Tooling limitations (35 messages)
- #committers > Reference to resources that move out — Citation/SubstanceDefinition (12 messages)
- #implementers > Linking to Additional Resources — Core spec linking policy (3 messages)
- #OO WG > OO Additional Resource IG — Naming Discussion — IG naming (19 messages)
- ParadeDB database: 2939 canonical concepts, 5785 relationships, 226 spec pages (FHIR R6 + SMART App Launch)