FHIR defines a maturity model that can be applied to artifacts in an implementation guide, as well as to guides themselves. We also define an extension that allows artifacts to define their respective 'level' of maturity. The HL7 IG Publisher includes a configuration parameter that is turned on by default in the base IG template.

This page defines the expectations HL7 International has around declaring maturity levels for implementation guides and artifacts, the other machinery that exists to support managing and documenting maturity, as well as the options available to other organizations to define their own maturity model and/or leverage the FMG's model to document their own maturities.

Maturity Models

The FHIR core specification defines a maturity model that applies to all FHIR content published by HL7 international, including the artifacts in the core specification. This model defines a set of maturity 'levels', as well as the criteria that should be met for an artifact to be considered to meet that 'level' of maturity. The FHIR core specification has long declare maturity for resources and has started declaring maturity for other artifacts (value sets, operations, etc.) as well. However, the expectation to declare maturity is now being extended to FHIR implementation guides and artifacts published by HL7 international as well. Oversight of the maturity declaration process for these artifacts is managed by the HL7 FHIR Management Group.

While affiliates and other organizations are welcome to use the FHIR maturity model, it's possible that some organizations may want to use different criteria, or even a different numeric scale. This is permitted and supported by the extensions used to declare maturity. The base IG template for use with the IG publisher has an IG parameter called fmm-definition that allows the guide to link their FMM level declarations to whatever web-page they like. The maturity levels pointed to by the structuredefinition-fmm extension can be any range of integer values needed to reflect the granularity of maturities declared by their model.

Supporting maturity declarations

To allow appropriate governance over and implementer confidence in an authoring group's assertion of maturity, it's often helpful to capture supporting documentation that provide support for assertions about the level of testing, quality assurance, implementation, etc. associated with the resource. This might be connectathon participants, listing known implementations, dates and indivudals who have performed QA checks, etc. Historically, HL7 has managed the documentation of maturity of resources using a large Google sheet. However, this mechansism doesn't scale well to tracking all of the other artifacts in the FHIR core specification, let alone those in different implementation guides.

There is now a standard extension (structuredefinition-fmm-support) that allows authors to capture the supporting information for their maturity assertions. This information is available when a user hovers over the maturity level for that artifact. The extension isn't mandatory, though organizations can choose to require its use. Organizations can also set expectations for which artifacts require which types of supporting documentation.

Cascading Maturity Declarations

The FHIR core specification contains hundreds of resources and many hundreds more of value sets, code systems, operation definitions, search parameters, concept maps, and other types of artifacts. Implementation guides can similarly have hundreds or thousands of distinct artifacts. It can be costly to track and manage maturity information on every single one of those artifacts.

To help with this, the FHIR core specification uses a 'maturity propagation' process. Maturities must be declared on resources. However, the maturity of value sets, code systems, operations, etc. will default to the maturity of their associated resource (if any). This is done via a cascading process where value set maturity will default based on the maturity of the resources that bind to them, code system maturity will default based on the maturity of the value sets that reference them, etc.

This cascading process is also supported by the HL7 IG publisher. It is enabled by default in the base IG template and is controlled by the configuration parameter. If this is set to 'true', then maturity levels will automatically propagate from higher-level artifacts down to lower-level artifacts. (For HL7 international artifacts, 'standards status' such as 'normative', 'STU', 'draft' will also propagate as well.) The propagation will only occur to artifacts that haven't explicitly declared FMM (or standards status). I.e. Whatever status the author declares will trump any cascading that would otherwise occur.

The cascade hierarchy works as follows:

1. Maturity is only relevant for 'canonical' resources. It's not possible for a Patient, Observation, or CarePlan instance to have maturity. Maturity levels won't be displayed for non-canonical resources
2. Certain resources that are canonical are always considered 'informative' (non-implementable) and therefore also won't be subject to maturity declaration or propagation. These include: ChargeItemDefinition, Citation, ConditionDefinition, Evidence, EvidenceReport, EvidenceVariable, ExampleScenario, ObservationDefinition, and TestScript.
3. If an instance is explicitly marked as an example, it will also automatically be considered to be informative, non-implementable, and thus not subject to maturity.
4. Maturity propagates along certain resource relationships, but not all relationships. For example, if an implementation guide has a dependency on another implementation guide, it doesn't inherit the referenced guide's maturity. The specific sources of propagation are as follows:

   Source	Propagates to
   ActivityDefinition	library (Library); profile (StructureDefinition); transform (StructureMap)
   CapabilityStatement	rest.resource.profile & document.profile (StructureDefinition); rest.searchParam & rest.resource.searchParam (SearchParameter), rest.operation & rest.resource.operation (OperationDefinition); messaging.supportedMessage.definition (MessageDefinition)
   ConceptMap	group.unmapped.valueSet
   Implementation Guide	global.profile (StructureDefinition); definition.resource (everything)
   Measure	library (Library)
   MessageDefinition	base & parent (MessageDefinition); focus.profile (StructureDefinition); graph (GraphDefinition)
   OperationDefinition	base (OperationDefinition); inputProfile, outputProfile, & parameter.targetProfile (StructureDefinition); parameter.binding (ValueSet)
   PlanDefinition	library (Library); action & action.action (ActivityDefinition)
   Questionnaire	derivedFrom (Questionnaire); item.answerValueSet & extension[questionnaire-unitValueSet] (ValueSet); extension[questionnaire-referenceProfile] (StructureDefinition)
   SearchParameter	derivedFrom & component (SearchParameter)
   StructureDefinition	baseDefinition & baseDefinition (StructureDefinition); differential.element.binding.valueSet (ValueSet)
   StructureMap	import (StructureMap)
   ValueSet	extension[valueset-map] (ConceptMap); extension[valueset-supplement], compose.include.system & compose.exclude.system (CodeSystem); compose.include.valueSet, compose.exclude.valueSet (ValueSet)

   The following resources do not (currently) propagate maturity to any references: CodeSystem, EventDefinition, Library, NamingSystem, & TerminologyCapabilities

   NOTE: As the list of canonical resources and the data elements supported by them change, the code that supports maturity propagation will need to be updated. If you think a resource or element should support propagation that isn't listed above, please raise an issue on Zulip

5. In some cases, a resource may 'inherit' maturity from multiple sources having different values - for example, the same ValueSet may be referenced by one profile with maturity 4, and another with maturity 2. In this case the 'highest' maturity will be presumed to apply. I.e. if at least one of the profiles is at level 4, it's assumed that the value set it points to is also at least at level 4.
6. For the purpose of standards maturity, draft is consider less than STU, which is less than normative. 'informative' does not propagate.
7. Propagation only happens within the context of an IG. Statuses from artifacts in other IGs is not considered.

Authors should be aware that while these propagation rules will 'generally' produce the desired results and will signficantly save on maintenance effort, there will absolutely be times when they will want to override the default maturity. For example, a particular implementation guide or profile might have high maturity, but some of the artifacts it points to might be newer or not widely tested/implemented and thus should be explicitly marked as lower maturity.