This page is part of the FHIR Specification (v3.0.2: STU 3). The current version which supercedes this version is 5.0.0. For a full list of available versions, see the Directory of published versions . Page versions: R5 R4B R4 R3

FHIR Infrastructure Work Group

Maturity Level: 5

Ballot Status: Trial Use

2.7.0 Version Management Policy

This page documents the way version change is handled in FHIR. FHIR is a standard, so the way version change is handled is a bit different from an application API. This page describes:

• The standards development process
• The FHIR Maturity Model
• How FHIR versions work
• The rules for inter-version change once an artifact is Normative
• Strategies for handling change during the development process
• Plans for future releases

2.7.0.1 The Standards Development Process

FHIR is a standard. In order to be useful, standards need to evolve. At the same time, the evolution of standards needs to be predictable and manageable for the implementation community. This section describes how HL7 develops a standard so that implementers know what to expect as the standard evolves.

HL7 has four descriptive terms that describe the level of stability and implementation readiness associated with different aspects of the specification. They are as follows:

Standard Level	Description
Draft	This portion of the specification is not considered to be complete enough or sufficiently reviewed to be safe for implementation. It may have known issues or still be in the "in development" stage. It is included in the publication as a place-holder, to solicit feedback from the implementation community and/or to give implementers some insight as to functionality likely to be included in future versions of the specification. Content at this level should only be implemented by the brave or desperate and is very much "use at your own risk". The content that is Draft that will usually be elevated to Trial Use once review and correction is complete after it has been subjected to ballot
Trial Use	This content has been well reviewed and is considered by the authors to be ready for use in production systems. It has been subjected to ballot and approved as an official standard. However, it has not yet seen widespread use in production across the full spectrum of environments it is intended to be used in. In some cases, there may be documented known issues that require implementation experience to determine appropriate resolutions for. Future versions of FHIR may make significant changes to Trial Use content that are not compatible with previously published content.
Normative	This content has been subject to review and production implementation in a wide variety of environments. The content is considered to be stable and has been 'locked', subjecting it to FHIR Inter-version Compatibility Rules. While changes are possible, they are expected to be infrequent and are tightly constrained.
Informative	This portion of the specification is provided for implementer assistance, and does not make rules that implementers are required to follow. Typical examples of this content in the FHIR specification are tables of contents, registries, examples, and implementer advice

This release (Release 3) is an Trial Use Specification, though a little of the content (where marked specifically at the top of the page) is Draft. For Release 4, some content is planned to be Normative.

Notes:

• The above statuses can apply to both the standard overall as well as to individual components of the FHIR specification
• Between FHIR release 2 and 3, HL7 changed from using "DSTU" (Draft Standard for Trial Use) to just simply "STU" (Standard for Trial Use) to reflect the maturity of the FHIR specification: Release 2 and particularly this Release 3 are far beyond "draft" specifications, and have been and will be widely implemented.
• Most pages in the specification identify their status explicitly. The few pages that don't are Table of contents pages, and are all Informative
• Some content is labeled with the status "External", which means that the content is maintained in another standard, and the status must be found by consulting that other standard. In this case, the Maturity Model does not apply

2.7.0.2 Maturity Levels

The content of this release has been subject to significant review through ballot and other HL7 processes and many aspects of it have been implemented and subjected to interoperability testing through Connectathons and early adoption. However, the degree of testing has varied. Some resources have been well tested in a variety of environments. Others have received relatively little real-world exercise. In general, the infrastructure should be considered to be more stable than the resources themselves. In some cases, there are issues on which input is specifically requested during the Trial Use period (see the Outstanding Issue List, and known issues will arise after publication (refer to the FHIR Change Request tracker for details.) Guidance from early implementation will help address these areas.

All artifacts in this specification are assigned a "Maturity Level", known as FMM (after the well known CMM grades). The FMM level can be used by implementers to judge how advanced - and therefore stable - an artifact is. The following FMM levels are defined:

0. the resource or profile (artifact) has been published on the current build. This level is synonymous with Draft.
1. PLUS the artifact produces no warnings during the build process and the responsible WG has indicated that they consider the artifact substantially complete and ready for implementation
2. PLUS the artifact has been tested and successfully exchanged between at least three independently developed systems leveraging at least 80% of the core data elements using semi-realistic data and scenarios based on at least one of the declared scopes of the resource (e.g. at a connectathon). These interoperability results must have been reported to and accepted by the FMG
3. PLUS the artifact has been verified by the work group as meeting the Trial Use Quality Guidelines and has been subject to a round of formal balloting; has at least 10 implementer comments recorded in the tracker drawn from at least 3 organizations resulting in at least one substantive change
4. PLUS the artifact has been tested across its scope (see below), published in a formal publication (e.g. a FHIR Release), and implemented in multiple prototype projects. As well, the responsible work group agrees the resource is sufficiently stable to require implementer consultation for subsequent non-backward compatible changes.
5. PLUS the artifact has been published in two formal publication release cycles at FMM1+ (i.e. Trial Use level) and has been implemented in at least 5 independent production systems in more than one country
6. "Normative": the artifact is now considered stable

Tested across scope means:

• The FMG has signed off on the list of "example contexts" defined for the artifact
• For each example context, the artifact has either been: reviewed and approved by a domain expert for that scope area, mapped to an existing implemented scope-area-specific standard or tested in an implementation

The Maturity level is strongly related to stability; the higher the maturity level, the more controls are enforced to restrict breaking changes to the resource. For further information, and discussion, see the FHIR Wiki .

The maturity model is significantly influenced by the degree and type of implementation activity using an artifact. For this reason, we encourage implementers to register their implementations . A detailed analysis of the basis for the maturity metrics for FHIR artifacts can be found here .

2.7.0.3 FHIR Releases and Versioning

New versions of FHIR will be published on a release cycle of approximately 18-24 months. This frequency is based on the timelines necessary to consult with implementers, and develop, review new content as well undertake the formal balloting and reconciliation processes required for ANSI-approved standards. This release cycle also ensures an opportunity to incorporate implementer feedback from earlier versions of the specification into subsequent versions. Limited-scope releases on a shorter timeline may occur occasionally where necessary to meet implementer desires.

Each new release is assigned a unique version number. The FHIR version policy is based on Semantic versioning , but with some differences due to the fact that FHIR is a specification, not a software API.

There is a single development version of FHIR. This undergoes cycles of development as managed by HL7. Each major cycle of development is concluded by a formal ballot (or more than one), and then a new specification is published. In version control terms, each published specification is a branch off the development trunk, which may then itself undergo further change as HL7 maintains the published specification (though such changes are usually minimal, limited to necessary technical corrections or security alerts).

Each FHIR version is identified by a string composed from 4 parts: publication.major.minor.revision.

publication	Incremented when HL7 publishes FHIR as an updated specification, e.g. a Trial Use or Normative version of FHIR The first Trial Use was version 0 FHIR Release 2 (DSTU) was version 1 FHIR Release 3 (STU) is version 3 (skipped '2' to align the major numbers at implementer request)
major	Increments every time a breaking change is made (see below) When a new publication is made, this is reset to 0 in the publication, and 1 in the development branch Since HL7 does not make breaking changes as technical corrections to a published specification, these versions of FHIR always have a version number X.0.n.r Because the development version is the subject of ongoing analysis, debate, ballot and repeated alterations, breaking changes are to be expected in STU content
minor	Increments every time an official snapshot release is generated that contains one or more substantive changes Resets to 0 any time the major version changes Snapshot releases are produced approximately 6 weeks in advance of the 3 annual HL7 working group meetings (and their associated connectathons), though they can also be produced for other major connectathons or to meet implementer requirements.
revision	Incremented any time a change is made to the specification At present, this is the SVN version number (this allows anyone to reconstruct the source from which the version was built) Changes are made numerous times a day, generally driven by change requests submitted by the implementation community

Additional notes:

• Changes to a formally published specification (except for minor publishing corrections, such as correcting broken external links) are only made via announced technical corrections
• The reference implementations have 2 versions - the version of the specification that they implement and their own version. Consult the reference implementation documentation for policy regarding this version number
• The current build - published by the continuous integration service (http://build.fhir.org/ ) - does not conform to this version policy, in that the version is not updated as changes are made. To indicate this, the revision is always "cb" e.g. 3.1.cb immediately after the publication of Release 3
• The first DSTU was published prior to these rules being agreed as v0.80-2286. This has been updated to 0.0.81.2382 as a technical correction to align with this policy on 9-May 2014

2.7.0.4 Rules for Inter-version change

The following kinds of changes may be made to the specification:

• Breaking changes are changes that mean that previously conformant applications are no longer conformant to the updated specification
• Substantive changes are changes that introduce new functionality - changes to the specification that create new capabilities - but would not render unchanged existing applications non-conformant
• Non-substantive changes do not cause changes in any conformant application. For example, section renumbering, broken links, style corrections, typos, and clarifications that do not change the meaning of the specification. In addition, some other kinds corrections may be judged not to create any expectation of change to a conformant application

Note that the following are, by definition, considered non-breaking changes, even though some implementations (including the reference implementations) may not be able to handle some consequences of these changes without error:

• Creation of new resources
• Adding new optional elements in an existing resource
• Defining new data types
• Adding new API operations

The examples provided as part of this specification are never substantive. While very effort is made to ensure that FHIR examples are correct, changes to the examples in the specification are not considered substantive.

Content with a status of Draft or Trial Use can change - including Breaking Changes - from version to version, subject to the rules described by the Maturity Process. Once an artifact achieves Normative status, the Backward compatible behavior rules will apply. These rules ensure that implementations may exercise FHIR interfaces and process the content of FHIR resources safely while exchanging data between applications using different versions of FHIR.

2.7.0.4.1 Version identification

There is no explicit version marker in the content of FHIR resource instances. Instead, the version supported by a given system is declared using the conformance framework. The resources CapabilityStatement and StructureDefinition have properties for declaring the FHIR specification version, and these may be used to determine which version of FHIR an implementation is using to aid in validation and integration.

2.7.0.4.2 Forward compatible behavior

In a typical scenario, mixed versions may need to exist, so applications SHOULD ignore elements that they do not recognize unless they are modifierExtensions. However, in a healthcare context, many application vendors are unwilling to consider this approach because of concerns about clinical risk or technical limitations in their software (e.g. schema based processing). Applications are not required to ignore unknown elements, but SHALL declare whether they will do so in their Capability Statements.

Unrecognized search criteria SHOULD always be ignored - see Handling Search Errors for further information.

Attempts to perform HTTP operations on unexpected URLs SHOULD be responded to with an appropriate error code.

2.7.0.4.3 Backward compatible behavior

Category	Allowed changes
Elements	Once Normative, subsequent versions of this specification may introduce new elements and/or content (e.g. XML attributes, etc.) at any location in the bundle, resource and/or data type structures. However, the names, path and meaning of previously existing data elements will not be changed. This means there will be no change to resource names and no changes to names assigned to slices and other elements within profiles.
Cardinality	Minimum element cardinalities will not be changed. Upper cardinality may change from 1 to * only in circumstances where all elements except for the first repetition can be safely ignored. (This may mean that an order is assigned to the repeating items or that there is no preference as to which element is retained.) Systems should follow the rules above for unexpected elements.
Descriptions	Descriptive information about a resource - short labels, definitions, usage notes, aliases, examples, rationale, mappings, etc. may be updated or revised to provide additional clarity or guidance, but not in such a manner as to invalidate a reasonable interpretation of the previously documented use of an element. (This does not preclude fixing obvious errors.)
Value Sets	The definition of any value set that is marked as immutable will never change. The expansions for immutable value sets may still change if no "stable date" is declared and the value set does not restrict code system and/or value set references to specific versions and the codes in the referenced code system(s) or value set(s) change. For non-immutable value sets: Value sets with an enumerated list of codes and having a 'fixed' binding may have additional codes introduced but will never have codes removed, though they may be deprecated. Value sets making use of filters may have filters loosened or tightened to accommodate changes to underlying code systems. StableDates and referenced code system and value set versions may be adjusted to point to newer versions. Definitions and display values for codes may change, but only in a manner that would not change the reasonable interpretation of data captured using the previous definitions or names. Abstract codes may be made concrete. Concrete codes will not be made abstract. For both immutable and non-immutable value sets, additional designations may be declared.
Terminology Bindings	Fixed bindings will remain fixed and will continue to point to the same value set. If the reference is version-specific, it will not change. Extensible bindings will remain fixed and will continue to point to the same value set. If the reference is version-specific, it will not change. Example bindings and preferred bindings may change to point to different value sets. Example bindings may be replaced with preferred bindings.
Data Types	Data types will not be removed or changed except as allowed above for elements. New data types may be introduced. Types declared on existing elements will not be removed or changed. Additional data types may be added to elements which are already expressed as a choice of data types only if those elements are optional (minimum cardinality = 0).
Value Constraints	The allowed list of Data types will not be added, removed or changed. Invariants, regular expressions, fixed values and patterns will not be added, removed or changed.
Flags	The Is Modifier and Is Summary flags will not be changed.
Slicing	Slicing rules and aggregation characteristics will not be changed.
Search Criteria	Search criteria may be added but not removed or renamed. Existing criteria will not have their type or path changed or have their description altered in any way that would invalidate the reasonable behavior of existing systems (with the exception of correcting obvious errors).
Operations	New operations may be defined but operations may not be removed or renamed. Existing parameters will not be removed or renamed, nor may their type or lower cardinality be changed. Upper cardinality may be changed from 1 to *. (Systems should ignore unexpected repetitions.) Additional optional parameters may be introduced; e.g. Operation signatures cannot change; instead, additional operation variants will be defined.
Restful interface	Existing endpoints will not be renamed or removed, nor have their expected behavior changed in a manner that would cause reasonable systems designed against prior versions to be non-interoperable. Additional endpoints and interactions may be introduced.
Profiles and extension definitions	Profile structure, extension definitions and search criteria definitions will not be removed or have their URIs changed. New profile structures, extension definitions and search criteria definitions may be introduced. Profiles may have their statuses changed to "retired". Profiles referenced by data elements for structures or data types may be replaced with a reference to a distinct profile that is "compatible" with the previously referenced profile according to these forward and backward compatibility rules.

 

Additional discussion on inter-versioning issues can be found here: http://wiki.hl7.org/index.php?title=FHIR_interversion_compatibility .

2.7.0.5 Strategies for handling Changes to STU content

Regardless of the degree of prior implementation, all aspects of the FHIR specification are potentially subject to change while an artifact has a status of Draft or Trial Use. These changes may be minor (clarifications of definitions, etc.) or major (refactoring of resources, changes to serialization rules, eliminating or adding data types, etc.) There is no commitment to backward or forward compatibility during the STU process. Changes will not be made without cause, however the interests of long-term implementability will generally trump the impact on early adopters when determining what changes should be made. This balance will shift more towards early adopters as maturity levels increase. I.e. Impact on existing implementations will be weighted more highly for an FMM-level 5 artifact than they would for an FMM-level 1 artifact.

Implementers who are willing to accept the risk of change (perhaps for the benefit of early implementation experience, first mover advantage and the ability to leverage FHIR's intrinsic benefits) are encouraged to implement FHIR in real-world systems. However, those implementers should be aware that local adaptations may be necessary to meet real-world requirements. Furthermore, such implementers should architect their solutions to be tolerant of changes to the specification and, where necessary, to manage interoperability with systems that may be using different versions of the specification or different local adaptations.

The most common strategy for handling change between versions of FHIR is to use different end-points for different versions. e.g. http://acme.com/fhir/r2 and http://acme.com/fhir/r3, though other approaches are possible.

During the Trial Use period, requests for change may be submitted using the HL7 gForge tracker which can be found here . Where possible, updates to the "development" version of the specification will be made in a timely fashion. Implementers should be aware that the changes are not considered "official" until such time as they are balloted and approved as part of a subsequent Trial Use or Normative publication. Change requests might be fixes to allow implementation, clarifications or enhancements. In addition, HL7 will be developing and introducing additional resources and profiles as part of the FHIR specification.

SDOs and regulatory bodies that are interested in making use of the FHIR specification should feel free to do so, but should consider and plan for the possibility that the specification will evolve and change prior to becoming Normative.

A key objective of the Trial Use process is gaining feedback from implementers making use of the specification. As well, HL7 has a need to monitor which portions of FHIR are being implemented in what sorts of environments so as to make an informed decision on when the specification is ready to proceed to Normative status. For this reason, all FHIR implementers are encouraged to register their usage here .

This survey will capture contact and other information that will allow the FMG to perform appropriate monitoring of FHIR STU usage. Survey information will be kept confidential unless the participant authorizes inclusion of their project in an HL7-maintained wiki page of early implementers. Confidential submissions will be reported in aggregate only.

2.7.0.6 Plans for future releases

While implementation of this Trial Use release is occurring, development will be progressing on the next release. This next release will include additional resources, profiles and quality enhancements over the current release. It will also incorporate fixes for issues raised with the FHIR change tracker . It may be useful for implementers of the STU to review the development release to get a sense of what changes are likely coming and perhaps to find more robust definitions and guidance than are available in the first release. The FHIR development release can be found at build.fhir.org . Some implementers who are dependent on content that exists in a draft release may choose to implement based on a particular snapshot of the development release, though in doing so, they will limit their potential communication partners and would not be considered to be completely FHIR conformant.

The next major publication of FHIR will be Release 4. It is our hope that this release will include the transition of some of the content of the specification to Normative. This should include many of the core infrastructure resources (e.g. StructureDefinition, ValueSet as well key pages such as the XML and JSON syntaxes, RESTful protocol, etc. It should also include at least a few of the administrative resources such as Patient. Much content, including most if not all clinical and business resources, will remain at the Trial Use level as they are not expected to meet the criteria for Normative.

The anticipated timeline for Release 4 involves a finalization of scope by the end of 2017, balloting in April of 2018 and publication around October 2018. The specific timing may vary based on implementer feedback and the volume of contents received during the ballot process. More information on plans for Release 4 can be found on the HL7 product director's blog . (Subscribing to this blog is a good way to keep current on significant events in FHIR development, including ballot and publication timelines.)

There will be additional releases of FHIR with a frequency of between 18 and 24 months for the foreseeable future. These releases will include new content (e.g. in the public health, financial or clinical research spaces), revisions reflecting implementer feedback and increasing maturity on Trial Use artifacts and the migration of additional content to normative status. As well, HL7 will gradually shift focus to providing additional guidance through the publication of implementation guides and profiles where consensus can be found at the international level.