HL7 FHIR® UK Core Design and Development Approach

HL7 FHIR® UK Core Design and Development Approach

Introduction

This section details the development and release cycles, including associated processes used for the UK Core Implementation Guides.

Simplifier Platform Structure

Overview

Simplifier is the chosen platform for UK Core development. Further information about Simplifier can be found on the Simplifier homepage.

Simplifier Projects

The UK Core consists of a collection of projects and Implementation Guides. These are developed and released using the Simplifier platform in an organisation account owned by HL7 UK. There are two projects used for the UK Core and related Implementation Guides.

  • HL7 FHIR® UK Core R4 - The UK Core project which contains the FHIR assets and Implementation Guides at various stages of the development and release cycles.
  • UK FHIR Community Assets - A HL7 UK project that contains other assets and guides important for FHIR implementers in the UK.

There is also another HL7 UK project:

  • HL7 FHIR® CareConnect Baseline for STU3 - This is project for the CareConnect STU3 FHIR assets and guides. This project is not directly related to the UK Core but was used as input in the early development of the UK Core. There is currently work in progress to map the CareConnect FHIR assets to UK Core FHIR assets to help implementers migrate to UK Core.

Simplifier Implementation Guides

There are a number of UK Core Implementation Guides, and these will increase over time as more releases are released. Below is a snapshot of the current guides as an illustration of the type of guides that are contained in the UK Core project.

  • UK Core Version History Implementation Guide - the UK Core version History guide which contains the history of the versions of the UK Core either released or in development.
  • UK Core Releases - These are official releases which are deemed as "read only" and these will increase over time
  • C&TA UK Core Releases - These are official releases which MUST NOT be implemented and are only released as input into the Clinical and Technical Assurance process.
  • UK Core FHIR Assets in development - This implementation Guide contains all the FHIR assets that are currently in development and are of low maturity and should be considered as "work in progress". These FHIR assets can be used in implementations but should be used with caution as these have not yet been Clinically and Technically assured. Implementers should feedback issues and requests for change to help increase the maturity of these FHIR assets.

The FHIR Community Assets project currently only contains the UK Naming Systems Implementation Guide.

GitHub Setup

Overview of GitHub Setup

This section gives a brief overview of how GitHub is used with Simplifier for version control of the UK Core FHIR assets. Simplifier has the functionally of linking a project with a GitHub repository. The components of a UK Core Implementation Guide are managed in either GitHub or Simplifier. The Simplifier Project will contain all components but will not be the master for many. The current approach is illustrated below:

Simplifier will synchronise the project every time a commit(change) is detected in the master branch of the GitHub repository, this is standard behaviour and is not detailed in this guide but further information is contained in the Firely documentation.

Version Management

Overview

This section details the version management approach used with the UK Core Implementation Guides, UK Core packages and FHIR assets. The approach differs for each of these items and so is documented in separate sections.

FHIR Assets Versioning

FHIR Assets Versioning

All profiles produced for the UK Core will be versioned during development using Git and will follow the standard GitFlow model.
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 MUST therefore be in one of the following forms:-

  • MAJOR – e.g. 1
  • MAJOR.MINOR – e.g. 1.0
  • MAJOR.MINOR.PATCH – e.g. 1.0.2

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

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. An example could be :-

  • Correcting typos in the short description of an element in a FHIR profile

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.

Publication of a version within a UK Core asset

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

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.

Instance Conformance Identification

For some information flows, there is a requirement to identify which UK Core profile(s) an instance being exchanged between healthcare IT systems conforms to. This could be for the purpose of validation of the instance against the profile definition and/or for conformance testing. This profile conformance is declared using the profile.meta element. The element carries the profile URL appended with the version information.

The format is: 'URL' "|" 'version' For example:

https://fhir.nhs.uk/R4/StructureDefinition/UKCore-RelatedPerson|1.1.0

This is illustrated below:

<RelatedPerson xmlns="http://hl7.org/fhir">
    <id value="RP123" />
    <meta>
        <profile value="https://fhir.hl7.org.uk/StructureDefinition/UKCore-RelatedPerson|1.1.0" />
    </meta>

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.

Change Control

This section details a change control process for use with the UK Core standard. The change control process is part of the overall configuration management.

Overview of Process

Change Control Roles

  • Requester - Any individual or group/organisation requesting a change to an existing FHIR asset in the UK Core or requesting a new FHIR asset to be added to the UK Core.
  • UK Core Development Team - Individuals who are involved in the UK Core FHIR assets development and/or authoring guidance contained in the UK Core Implementation Guide.
  • UK FHIR Delivery Senior Leadership Team (SLT) - a group of people from the FHIR community who represent the interests of stakeholders in the UK Core.
  • UK FHIR Delivery Senior Leadership Team Technical Subgroup - a group of FHIR/Interoperability and clinical subject matter experts who evaluate UK Core requests for change then triage and route them as appropriate.

Requesting a Change to the UK Core

All requests for a change to the UK Core standard must be made using the create issue option in Simplifier. Requests may be from an individual or group/organisation looking to use the UK Core for an implementation or for an issue reported by a member of the development team. The same approach is used to feedback on issues by participants in the Clinical and Technical Assurance process.

Creating a Simplifier Account

The UK Core uses Simplifier for issue tracking and maintenance. Although the UK Core is in the public domain, you will need to create an account and login to raise issues. Creating a Simplifier account is done by going to https://simplifier.net/ and using the sign-up option on the top right of the page. An email address and a chosen password are the only details needed to set up an account.

Login to Simplifier

Logging in to your Simplifier account is required to raise issues. Browse to https://simplifier.net/ and use the login option on the top right of the page, then enter the chosen credentials.

The UK Core project is located here in Simplifier.

Change to an existing UK Core Asset

When the change request is for a change to an existing UK Core FHIR asset, the preferred approach is to raise the issue at the level of the relevant asset.

Create a Simplifier issue at UK Core Asset level

It is acknowledged that not everyone will have enough knowledge of FHIR Implementation Guides or Simplifier to log an issue to the correct Simplifier resource, therefore logging at the project level is allowable, if this is the case. However, issue logging at asset level is the preferred approach, as it makes triage of issues easier.

Note: Simplifier refers to everything as a resource whether it’s an image, example or FHIR profile and provides a mechanism to filter on type.

Step 1 - How to search and filter

How to search and filter in Simplifier illustration

To search for a particular asset, for example to find the Patient profile, filter by resource category "Profiles" (tick the box alongside Profiles), add the word "Patient" in the search box and hit return. This will bring up a link to the Patient profile which will take you to a page with a view of the Patient profile.

Once the required Simplifier resource page is found, the last tab on the page is the issues tab. Clicking on this will bring up a page where a new issue should be raised by clicking the New Issue button.

Step 2 - Create new issue

Create new issue illustration

This will only require a title and the details of the issue or comment. All other issues logged for this Simplifier resource will be available from this page and you can check these or find out whether this issue has already been logged, if required.

Step 3 - New issue information required

New issue information required illustration

If you cannot locate the Simplifier resource, or it is not appropriate to log an issue at the Simplifier resource level, then you should raise an issue at the project level. In this case, the title and/or issue text should identify which part of the UK Core Implementation is the subject of the issue being raised. See the Creating a Simplifier Issue at Project Level section for how to do this.

Requesting a new UK Core Asset

Issues for new UK Core FHIR assets should be raised at the UK Core project level the issue must indicate the use case or details of the requirement as to why the new asset is needed.

Creating a Simplifier Issue at Project Level

To create a issue at the project level, navigate to the project. Once you are in the project, click on the issues tab and then the create button to create the issue.

Issue Triage by UK Core Development Team

Issues will be triaged by the UK Core Development Team and any change other than a minor issue (for example a typo or a bug fix) will be referred to a Senior Technical lead from the SLT Technical Subgroup or discussed at the UK FHIR Delivery Board for further appraisal.

If the issue raised does not have a solution suggested, then the triage will include further analysis to establish a solution which may include several proposed technical options. If the requester has provided a proposed solution, this will need to be validated, which may result in alternative or other solutions being proposed.

The response time for issues to be initially triaged does not have a formal service level agreement in place but should be responded to in a timely manner. This is managed by NHS Digital as part of its role in the UK Core Development Team using the Interoperability Team's mailbox, which receives auto-notifications from Simplifier on a daily basis. The mailbox is monitored daily by the NHS Digital Interoperability Team and initial triage will be done within a day or two, except when the issue has been raised as part of the Clinical and Technical Assurance process.

Note: The triage of issues raised as part of Clinical and Technical Assurance process (which has a three-week review period) is done at the end of the Clinical and Technical Assurance process as a batch. This enables more efficient triage of issues and the identification of dependencies and issue duplication.

Triage of Non-Clinical and Technical Assurance process issues

The triage process for issues is not something that is a tightly defined process, but more of a discussion forum of SMEs where a consensus of agreement is reached about the issue and any proposed solution. The following are examples of criteria or areas that will be discussed:

  • Is the reason or use case for the requested change or addition to the UK Core clear enough to triage the issue?
  • Is the proposed change suitable for the use case, for example are the profiles that are being requested or requested to be changed the correct profiles for the use case?
  • Is the use case already covered by another asset or set of assets?
  • Is this a potential breaking or non-breaking change? This is only potential, as what is a breaking on non-breaking change can be very hard to quantify in some cases.
  • Does the issue need to be referred to a wider audience or a special resource, for example a Clinical lead?

The Simplifier issue will be updated with any information that will inform the requester of progress, etc.

Triage of Clinical and Technical Assurance process issues

The triage process for issues raised as part of the Clinical and Technical Assurance process is done as a batch process by the UK Core Development team at the end of the process. The issues raised are filtered to remove duplicates or minor issues such as typos or minor technical errors. The remaining issues are taken forward to the Clinical and Technical Assurance follow up meeting for discussion, agreement and resolution.

The Simplifier issue will be updated with any information that will inform the requester of progress etc.

Approval of issue

Once a change request is accepted, the issue is added to the UK Core Backlog. The requester will be notified via Simplifier by update of the issue. The issue will not be closed at this point, only when the development work has been completed.

Rejection of issue

If a request for change is rejected, then the Simplifier issue is updated with all the information required to inform the requester why it was rejected. Further calls or emails may also be used to explain the reason for rejection, if required, depending on the complexity of the issue.

Development Backlog

The UK Core backlog is where all the development work items are recorded and tracked. The work items are maintained using a tool called JIRA. All the work items in JIRA will be traceable back to Simplifier. The development is carried out using an agile type of methodology and managed on a Kanban board. The UK Core backlog is an internal process which only the UK Core Development team have access to, however this information is mirrored in the Simplifier issues for consumption by the FHIR community. The requester will be emailed whenever there is an update to the Simplifier issue.

Development Cycle

Overview

The UK Core development is driven by requests for change which can come from many sources. The Change control section gives details about how this is managed.

UK Core Development Process

This diagram shows the process used to develop the UK Core FHIR assets.

Development Cycle

The development cycle is feed from three main sources:

  1. The Clinical and Technical Assurance Process
  2. Issues raised by the FHIR Community in Simplifier
  3. Issues raised from HL7 UK Ballots

See the Change Control page for full details on the change control process.

Asset Types

The first part of the development cycle is to identify the type of FHIR asset(s) and any dependencies, for example if the change is to create a new profile then there will be a need to identify any related resources required such as extensions, examples, ValueSets guide pages etc. This is required to size of the development so that resources and timescales can be planned. The required changes are then added to a JIRA backlog which is used by the UK Core Development Team to schedule the development work.

Adding to a Implementation Guide

The changes will be added to either:

  • The UK Core FHIR Assets in development Implementation Guide
  • A UK Core C&TA Release
  • A scheduled UK Core Release

Which Implementation Guide the changes appear in depends on many factors for example:

  • Which release the issue was raised against
  • Which process the issue was raised in (C&TA, HL7 UK Ballot etc)
  • The use case that is driving the development

The Simplifier Platform Structure page gives further information about Implementation Guide types.

Internal Review

Once the change has been done the UK Core Development Team will carry out an internal review and rework as necessary until the development is of the quality required. The page on FHIR Assets gives more information on the principles and design of FHIR assets which are used during internal review.

External Review

There is no external review until the changes are included in a release as part of the C&TA or the Ballot process but as all development is done in the public domain and therefore feedback on any change is always possible via Simplifier.

Overview of Release Cycle

The section details the UK Core release cycle and how the various versions are defined.

Overview Of Cycle

The diagram below illustrates how the UK Core Release cycle works and is an abstract view of the way it is released. This is an evolving process, and the diagram only shows one release cycle of a sequence of a repeating process.

Current releases

This diagram shows current release cycle of the STU sequence of the UK Core. The STU1 indicates it is release 1 of the sequence STU (Standard for Trial Use). The next HL7 UK Ballot will start the STU2 release sequence.

Use of NPM Packages

The UK Core uses Simplifier NPM packages to release the FHIR Conformance Assets.

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

Further information on Packages is available in the Simplifier documentation.

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 .

Package Versioning

The Simplifier NPM pages are released as part of a UK Core release. The release is normally an Implementation Guide and a NPM Package. The NPM package is named based on a seven-item string (1_2_3_4_5_6_7) which is described below:

fhir"fhir version"ukcore"sequence_release""major version"_"minor version"_patch version"`

  1. A fixed value fhir
  2. The release version of FHIR used with the UK Core (currently R4)
  3. A fixed value ukcore
  4. The sequence and release (currently stu1)
  5. The major release aligns with the Implementation Guide major version and always 0 unless the release has been though a ballot
  6. The minor version aligns with the Implementation Guide minor version
  7. 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

back to top