Version Management

FHIR Assets Versioning

FHIR Assets Versioning

The versioning for published assets will use the Semantic Versioning Standard. The major and minor versions will be visible, and the patch version MAY also be exposed. Version numbers held in profiles and resource instances SHALL therefore be in the following form:-

• MAJOR.MINOR.PATCH – e.g. 1.0.2 or
• MAJOR.MINOR - e.g. 1.0

Definitions of Change Types

There is no real way to determine whether a UK Core change is breaking or not unless you can get agreement with every implementer of the UK Core. This is practically impossible to do, so the following sections are to give a brief overview of the sort of changes that might be seen as breaking changes and should not be seen as definitive.

Major Change

This is a breaking change, and as such, implementers will need to understand the changes that have been made in the new version, and make changes to their implementations, if required, as such a change is not backwards compatible. An example could be :-

• Addition of new mandatory element(s) in a profile
• ValueSet binding increasing in strength, e.g from preferred to extensible

Minor Change

A minor change is defined as a backwards compatible change which is not expected to break existing implementations. Examples include :-

• Addition of new optional element(s) in a profile
• Addition of new operations whose names do not clash with existing operations

Patch

This is defined as a version in which backwards compatible bug fixes are made that do not change the original intent of the asset. An example could be :-

• Correcting typos in the short description of an element in a FHIR profile
• fixing broken ValueSet bindings

The UK Core is released as a pre-release for comment before an actual release, this will be with full change history for the changes applied so that implementers can agree the versioning that has been applied to the FHIR assets.

Atifact Versioning Policy

The UK Core follows the metadata versioning policy, which indicates that non-substantive changes to the metadata elements of an artifact may be made without incrementing the version number. When this occurs, the date element SHALL be updated.

Publication of a version within a UK Core asset

Version data will be carried in the version element for all assets.
These assets are :-

• StructureDefinitions
• Extensions
• ValueSets/CodeSystems
• ConceptMaps

The version information is maintained by the UK Core Development team in line with the Semantic Versioning Standard outlined above. Thus, for a StructureDefinition, this could read:

<StructureDefinition xmlns="http://hl7.org/fhir">
  <id value="UKCore-Patient" />
  <url value="https://fhir.hl7.org.uk/StructureDefinition/UKCore-Patient" />
  <version value="2.1.0" />

For a ValueSet, this could read:

<ValueSet xmlns="http://hl7.org/fhir">
<id value="UKCore-MedicationForm"/>
<url value="https://fhir.hl7.org.uk/ValueSet/UKCore-MedicationForm"/>
<version value="2.0.0"/>

Further information about both FHIR asset creation and maintenance is available on the Design Principle page.

Implementation Guide Versioning and Sequences

The versioning approach to the UK Core Implementation Guide releases are based on the FHIR Standard and is summarised below.

There are three numbers used with the versioning in the format n.n.n for example 0.3.0. The following rules apply:

• The first number is linked to the HL7 UK Ballot process and is always 0 until the release has been though the Ballot process
• The second number is incremented for every development release
• The third number can also be incremented for patch a development

The version number will formally be agreed for each release by the UK Core Development Team in consultation with HL7 UK.

The Release Sequence

The UK Core uses similar release sequences as the FHIR standard, these are:

• Draft
• Draft Standard for Trial Use (DSTU)
• Standard for Trial Use (STU)
• Normative

Draft

This is for when FHIR assets are in development this status is only used in the HL7 FHIR® Draft UK Core Profiles (Draft) Simplifier project.

Draft Standard for Trial Use (DSTU)

This is used for early development of the UK Core

Standard for Trial Use (STU)

This is the sequence used for the UK Core release when its ready for the HL7 ballot process. This version of the release is relatively stable because it has been though the Clinical and Technical Assurance process and all known/raised issues resolved and agreed. The HL7 UK Ballot process is the final endorsement of the release of the UK Core. There will be a number of releases of the STU sequence which will be denoted by the number STU1, STU2, STU3 etc...

Normative

This is the final status of the UK Core release which has passed the HL7 UK ballot process and has been proven by multiple implementations of the UK Core.

Releases

Each of the sequences will have a major release number to indicate the release within the sequence for example:-

• STU1 indicates it is the first release in the sequence STU (Standard for Trial Use)
• STU2 indicates it is the second release in the sequence STU (Standard for Trial Use)

The release aligns with the HL7 UK Ballot process, and the major version number of the Implementation Guide reflects this. There is only one major release per sequence and likewise only one HL7 UK Ballot. There will be multiple minor releases and maybe some patch releases.

For the full details of FHIR release see the FHIR Standard.

Package Versioning

The UK Core uses Simplifier NPM packages to release the FHIR Conformance Assets. From STU2 every package SHALL contain the snapshot and differential elements within each Profile. The profiles within GitHub SHALL only contain the differntial element, with the snapshot being rendered when the package is created using the Simplifer Bake scripting.

The UK Core Packages are located with the Project Packages area.

Further information on Packages is available in the Simplifier documentation and HL7 Confluence.

These packages may be used to validate conformance of an implementation of FHIR against a particular version or versions of the UK Core. For more information on conformance to UK Core see the Claiming Conformance to UK Core .

The Simplifier NPM pages are released as part of a UK Core release and normally coincides with an an Implementation Guide release. The NPM package name format is all lower case and as described below:

fhir.[fhir version].ukcore.[sequence release] [major].[minor].[patch]

where

• [fhir version] - The release version of FHIR used with the UK Core (currently R4).
• [sequence release] - The sequence and release (currently stu1).
• [major] - The major release aligns with the Implementation Guide major version and is indicative of the number of ballots the Implementation Guide has been through.
• [minor] - The minor version aligns with the Implementation Guide minor version.
• [patch] - The patches release is used for bug fixes within the package. The patch version starts at 0 and increments by 1 for every package release for a particular Implementation Release. Note: a Implementation guide may have more than one package associated with it.

Package example

For example fhir.r4.ukcore.stu1 0.1.0