FHIR Assets

Design Principles

Background

During collaboration with stakeholders and development of UK Core FHIR assets, important design principles have been established. They are critical in ensuring a consistent approach to asset creation.

Key Principle:

• "FHIR assets must not be England specific and must be capable of representing the requirements of each UK nation identified during collaboration."

Other Principles

Extensions

• "Will be applied to profiles after agreement during Clinical and Technical assurance
• "Will be added to an Extension Library within the UK Core."

Read more about FHIR Extensions and Extension design in the UK Core.

Cardinalities

• "FHIR resource element cardinalities will only be amended, if clinical justifications are agreed during Clinical and Technical assurance."
• "No elements will be removed unless deemed clinically unsafe following consultation and agreement during Clinical and Technical assurance."

Read more about FHIR resource cardinalities.

Slicing

• "Must only be used where it enforces structure in a profile", for example
  • for a ValueSet binding
  • for the representation of an identifier in a list, such as a patient's NHS number
• "Slicing must be Open e.g. one or more additional slices can be added."

Read more about Slicing in FHIR.

Must Support

• "Will only be used when there is a requirement arising from a use case identified during Clinical and Technical assurance."

Read more about "Must Support" in FHIR.

ValueSets

• "Binding strength should be set to 'extensible', where not defined as 'required' by the FHIR standard."
• "'required' or 'preferred' binding strengths for ValueSets should only be used, if agreed during collaboration." The binding strength should be decided as part of the Clinical and Technical Assurance process.

Read more about ValueSets and ValueSet bindings in FHIR.

Profile Design

This approach is used by the UK Core Development team to produce the UK Core Implementation Guides and the UK Core FHIR assets. It will be updated and matured in line with decisions taken during the Clinical and Technical Assurance process. This documentation is aimed at the technical reader and is included as reference material. The approach is based on the design principles.

Background

The HL7 FHIR® standard

The HL7 FHIR® standard creates a common foundation on which a variety of different solutions are implemented. The resources contained in the specification usually require further adaptation to particular health or social care use cases; this adaptation is referred to as "profiling" and the resulting artefacts as "profiles".

CareConnect

Prior to the development of the UK Core, HL7 UK and INTEROPen collaborated with NHS Digital as a development partner to create a library of nationally defined HL7 FHIR assets in FHIR version STU3. This was called the CareConnect initiative and the assets were formally reviewed by different stakeholders to make them suitable for implementation.
However, issues were identified with the CareConnect landscape, for example the scope of CareConnect was England only rather than the whole of the UK. The UK Core initiative aimed to address these issues, but also to build on the useful work already done. Therefore, where they existed, CareConnect assets were used as input for initial UK Core development.

General profiling approach

The checklist below was adhered to when developing a draft UK Core profile suitable for progression to Clinical and Technical Assurance.

Use any corresponding CareConnect profile as a starting point

For each profile, where a CareConnect STU3 profile exists, refer to it as a starting point for the UK Core FHIR R4 profiling exercise

Consider the resource changes between FHIR STU3 and R4 versions

Analyse the changes in the FHIR standard between FHIR STU3 version and FHIR R4,for example the addition or deletion of any elements and the introduction of new or updated terminology assets in the R4 version.

Approach to StructureDefinition elements

Cardinality

FHIR R4 resource cardinalities remain unchanged in initial development

Element cardinalities should remain unchanged from the base FHIR R4 resource when a profile is initially developed and this will then be reviewed during the Clinical and Technical assurance process

Identifiers

Where existing CareConnect STU3 profiles have applied slicing and profiling to identifiers, this will be recreated in the UK Core profiles, then evaluated during Clinical and Technical assurance.

MustSupport labelling

The MustSupport property in StructureDefinitions will not be used for the UK Core profiles.

Removal of elements

No elements will be removed from the FHIR assets for the UK Core profiles during initial profiling prior to Clinical and Technical Assurance.

Experimental element

The FHIR specification defines the 'StructureDefinition.experimental' element as the following, when set to ‘true’: 'This structure was authored for testing purposes (or education/evaluation/marketing), and is not intended for genuine usage.' (Source: http://hl7.org/fhir/r4/structuredefinition.html). Currently there is no requirement in the UK Core to set the experimental element as ‘true’ or ‘false’, so this field should remain in the default view (undefined).

URL prefix for profiles

The URL prefix which SHALL be applied to all UK Core assets is https://fhir.hl7.org.uk/

Naming convention for profiles

The UK Core profile name SHALL follow an agreed format. The name of a profile consists of a number of name segments, and will be in the form:-

[Base][FHIRAssetName][Specialism]

The segments are defined as follows:-

• Base: Mandatory The base for a profile this will always be UKCore.
• FHIRAssetName: Mandatory The name of the base FHIR Resource.
• Specialism: Required This is only used where there are multiple UK Core profiles for a given base resource type.

Note: "Mandatory" means that a segment SHALL be present. "Required" means that a segment SHOULD be present, in this case in the event of there being multiple profiles for one base resource.

This name SHALL be used in three places:

• The profile's physical filename.
• The name of the profile - carried in the StructureDefinition.name.value element
• The profile's logical id. This is carried in the element StructureDefinition.id.value
  Read more about logical ids in FHIR.

Example of usage of the name element

    <StructureDefinition xmlns="http://hl7.org/fhir">
    <id value="UKCore-MedicationStatement" />
    <url value="https://fhir.hl7.org.uk/StructureDefinition/UKCore-MedicationStatement" />
    <version value="1.0.0" />
    <name value="UKCoreMedicationStatement" />
    <title value="UK Core Medication Statement" />

Extensions

There is a UK Core requirement to develop extensions based on any equivalent CareConnect STU3 extensions. The exception to this is where an extension is no longer needed because either

• the data can be carried in a new element for a relevant resource in FHIR R4
• a corresponding common extension has been developed in FHIR R4

Extensions will be constrained (hard coded) into profiles.

The Implementation Guide for the UK Core will include an Extension Library page, which will list extensions and their corresponding UK Core profiles.

HL7 Extensions

There is no requirement to profile HL7 extensions locally. Where a HL7 extension is identified as in scope, a link to it will be added on the Extension Library page under HL7 Common Extensions.

View further information about Extension design.

Versioning

Internal versioning for UK Core assets will be entered in the StructureDefinition.version element.
Further details about internal versioning for UK Core assets are available.

Note: No version information is allowed in the R4 profile name.

ConceptMaps

To develop a ConceptMap:

• Create a UK Core ValueSet
• Create a ConceptMap which maps the UK Core ValueSet to the FHIR R4 ValueSet

Guidance for Creating new profile or new version

• Refer to UK Core Design Principles and Profile Design guidance

• Compare to any existing CareConnect profile as a baseline

• Refer to any existing FHIR R4 Uplift impact assessment for the CareConnect profile. This will show any changes between FHIR versions which must be accounted for when upversioning the UK Core profile to FHIR R4.

• (If required), create supporting UK Core FHIR assets:

  • Create Extensions
  • Create ValueSets
  • Create CodeSystems
  • Create ConceptMaps
  • Create Examples
  • Create Simplifier page
  • Import to Simplifier and provide relevant documentation pages in the Implementation Guidance.

Guidance for Reviewing new profile or new version

• Review profile against UK Core Design Principles and Profile Design guidance

• Review against any corresponding CareConnect profile

• Review against any existing FHIR R4 Uplift impact assessment for the CareConnect profile

• Identify which supporting FHIR assets terminology assets have been developed for this profile and review them

• Review Extensions

• Review ValueSets

• Review CodeSystems

• Review ConceptMaps

• Review Examples

• Review Simplifier page

Extension Design

Background

It is common for specific implementations to have valid requirements that are not part of the agreed common requirements modelled in the FHIR standard. Incorporating all specific use cases would make the standard too cumbersome. Therefore additional valid requirements can be implemented as extensions to the agreed common resources.

This section gives guidance on the correct modelling of extensions. There are two basic types of extensions used by UK Core:

• Simple extensions
  A simple extension has a single extension.urlelement and a single extension.value element.
• Complex extensions
  Complex extensions contain extensions to define a nested structure and are used to model more complex content.

Currently the UK Core does not use modifierExtensions, so no guidance is given here on this type. More information on modifierExtensions is available in the FHIR specification.

Extension Development Rules

General Rules for Extensions

These rules apply to simple and complex extensions.

Extension naming and url format

This section gives details on the format of:

• the extension.id.value
• the extension.url.value
• the extension.name.value
• the extension.title.value

extension.id.value

MUST conform to the format: Extension-UKCore-[extension name]
e.g. Extension-UKCore-AddressKey

extension.url.value

MUST conform to the format: https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-[extension name]
e.g. https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey

extension.name.value

MUST conform to the format:
Camelcase for each full word e.g. "AddressKey"
Note: only the characters [A-Z,a-z] can be used and full word means Careplan, not CarePlan.

extension.title.value

MUST conform to the format:
The full extension name with a space between each full word e.g. "Extension UK Core Address Key"

Example usage in a UK Core extension

   <StructureDefinition xmlns="http://hl7.org/fhir">
    <id value="Extension-UKCore-AddressKey" />
    <url value="https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey" />
    <version value="2.1.0" />
    <name value="ExtensionUKCoreAddressKey" />
    <title value="Extension UK Core Address Key" />
    <status value="active" />
    <date value="2021-09-10" />
    <publisher value="HL7 UK" />

The Extension Root Element

The cardinality of the extension root element MUST be 0..1 or 0..*.
This cardinality determines how many times the extension can occur in the profile or profile element.

Extensions are optional within the UK Core, but certain use cases may mandate their use. Therefore, all UK Core extensions are modelled as being optional at the extension root element.
Where the use case requires an extension to be mandated, the Implementation Guide for that use case will specify the requirements.

It is important that certain extensions are limited to one occurrence. For example, an extension for a date of death logically can only be populated once and therefore should have a cardinality 0..1 at the root level.

Rules for Modelling Simple Extensions

This section details the rules to follow when creating, updating or reviewing a simple extension.

Simple Extension Illustration

Extension

Extension.url

https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-EthnicCategory

Extension.value[x]

The extension.url element rules

A simple extension has only one extension.url element and the rules for this element are:
The extension.url element MUST be a Fixed value. The fixed value of the extension.url element MUST comply with UK Core Extension URL formats.

The extension.value element rules

The extension.value element in an extension is normally constrained to one or a few datatypes. The rules in this section are applicable to the various datatypes used by the UK Core extensions. Where a value's datatype is not currently used in the UK Core, no specific rules may be given.

Further information about FHIR datatypes is available.

Extension Bindings When the Value is a Coded Type

If the extension.value is constrained to a coded type e.g. one of: Code, Coding, or CodeableConcept: The extension.value MUST be bound to a ValueSet.

Cardinality of an extension.value element

On a simple extension the extension.value must be mandated, so MUST have a cardinality of 1..1.

Rules for Modelling Complex Extensions

This section details the rules to follow when creating, updating or reviewing a complex extension. A complex extension has a multiple extension.url elements and multiple extension.value elements.

Complex Extension Illustration

Extension

Extension.extension

Extension.extension:type

Extension.extension:type.url

type

Extension.extension:type.value[x]

Extension.extension:value

Extension.extension:value.url

value

Extension.extension:value.value[x]

Extension.url

https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey

Extension.value[x]

The extension.url element rules

A complex extension has multiple extension.url elements and the rules for the extension.url are:
All extension.url elements MUST be a Fixed value.
All the fixed values of the extension.url elements MUST comply with UK Core Extension URL formats.

Component extension rules

Component extensions may have a cardinality of 0..1, 0..* 1..1 or 1..* depending on the requirements.

The Extension.value element rules

The extension.value elements in a complex extension are normally constrained to one or a few types. The rules in this section are applicable to the various datatypes used by the UK Core extensions. Where a value's datatype is not currently used in the UK Core, no specific rules may be given.

Extension Bindings When the Value is a Coded type

If any of the extension.value elements is constrained to a coded type e.g. one of Code, Coding, or CodeableConcept:

The extension.value MUST be bound to a ValueSet.

Cardinality of an extension.value element

On a complex extension all the extension.value elements must be mandated. The extension.value MUST be mandated.

ValueSet Design

Background

Metadata used in UK Core Valuesets

This section provides background information on metadata used within ValueSet resources:

• the metadata element name
• the cardinality of the metadata in the HL7 FHIR standard
• the cardinality of the metadata to be applied in the UK Core
• the type (i.e. datatype) for the metadata, taken from the HL7 FHIR standard
• a definition of the metadata, taken from the HL7 FHIR standard
• any constraints that the HL7 FHIR standard applies to the metadata
• any notes relating to the use of the metadata within the UK Core

Further information about the ValueSet resource is available.

Other Information about UK Core ValueSets

Further information in this section includes:

• Lists of HL7 FHIR standard extensions that may be considered relevant to a UK Core ValueSet
• An XML template for a new ValueSet including options for the Content Logical Definition
• Links to example ValueSets already created for the UK Core
• Information about expanding ValueSets

Metadata usage

The list below contains generic Resource elements, followed by generic DomainResource elements, followed by ValueSet resource elements.

View further information about FHIR base resource definitions and elements.

View further information about FHIR domain resources.

    <identifier>
        <system value="urn:ietf:rfc:3986"/>
        <value value="urn:oid:2.16.840.1.113883.2.1.3.2.4.16.21"/>
    </identifier>

ValueSet Extensions

Currently there is no identified HL7 FHIR standard value set extension that has been recommended to be considered for use in UK Core value sets. The full list of FHIR Standard value set extensions available can be viewed online.

XML template for a new ValueSet

Main body of ValueSet

<ValueSet xmlns="http://hl7.org/fhir">
	<id value="UKCore-[ConcatenatedBusinessName(s)]" />
	<url value="https://fhir.hl7.org.uk/ValueSet/UKCore-[ConcatenatedBusinessName(s)]" />
	<version value="1.0.0" />
	<name value="UKCore[ConcatenatedBusinessName(s)]" />
	<title value="UK Core [SpaceSeparatedBusinessName(s)]" />
	<status value="draft" />
	<date value="2021-07-01" />
	<publisher value="HL7 UK" />
	<contact>
		<name value="HL7 UK" />
		<telecom>
			<system value="email" />
			<value value="secretariat@hl7.org.uk" />
			<use value="work" />
			<rank value="1" />
		</telecom>
	</contact>
	<contact>
		<name value="NHS Digital" />
		<telecom>
			<system value="email" />
			<value value="interoperabilityteam@nhs.net" />
			<use value="work" />
			<rank value="2" />
		</telecom>
	</contact>
	<description value="A set of codes that define ..." />
	<copyright value="Copyright &#169; [YYYY]+ HL7 UK Licensed under the Apache License, Version 2.0 (the &quot;License&quot;); you may not use this file except in compliance with the License. You may obtain a copy of the License at	http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an &quot;AS IS&quot; BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. HL7&#174; FHIR&#174; standard Copyright &#169; 2011+ HL7	The HL7&#174; FHIR&#174; standard is used under the FHIR license. You may obtain a copy of the FHIR license at	https://www.hl7.org/fhir/license.html." />
	<!--Insert Content Logical Definition below here. See next two main sections for Content Logical Definition templates.-->
</ValueSet>

Content Logical Definition – ValueSets containing UK Core CodeSystems

Content Logical Definition - Single entire code system

  <compose>
		<include>
			<system value="https://fhir.hl7.org.uk/CodeSystem/UKCore-[ConcatenatedBusinessName(s)]" />
		</include>
  </compose>

Content Logical Definition – Selected included codes from a single code system

  <compose>
		<include>
			<system value="https://fhir.hl7.org.uk/CodeSystem/UKCore-[ConcatenatedBusinessName(s)]" />
			<concept>
				<code value="[conceptCode1]" />
				<display value="[conceptDisplay1]" />
			</concept>
			<concept>
				<code value="[conceptCode2]" />
				<display value="[conceptDisplay2]" />
			</concept>
		</include>
  </compose>

Content Logical Definition – Selected excluded codes from a single code system

  <compose>
		<include>
			<system value="https://fhir.hl7.org.uk/CodeSystem/UKCore-[ConcatenatedBusinessName(s)]" />
		</include>
		<exclude>
			<system value="https://fhir.hl7.org.uk/CodeSystem/UKCore-[ConcatenatedBusinessName(s)]" />
			<concept>
				<code value="[conceptCode1]" />
				<display value="[conceptDisplay2]" />
			</concept>
			<concept>
				<code value="[conceptCode2]" />
				<display value="[conceptDisplay2]" />
			</concept>
		</exclude>
  </compose>

Content Logical Definition – ValueSets containing SNOMED concepts

The UK Core approach is that all SNOMED is encapsulated within the Content Logical Definition using SNOMED Expression Constraint Language (ECL) in a single statement in the value element, together with a property element value of "constraint" and an op element value of "=".

More information about ECL is available online.

The ECL informative long syntax rather than the normative brief syntax is used to identify a hierarchy or reference set. As the brief and long syntaxes are logically equivalent, the long syntax is used in the UK Core to both provide greater clarity to a potentially wide audience and to simplify the process of creating, validating and using the ECL statement for a range of potential users as it avoids any need to encode and decode symbols otherwise used in the brief syntax.

Concept display values are not included in the ECL statement to avoid potential duplication with the value set description and to avoid any need to encode separator characters. The value set description field is used to provide hierarchy / reference set display name information, although display values for lists of individual codes will only be available via a value set expansion again to avoid duplication.

It is intended that at least a partial value set expansion be provided for all value sets containing SNOMED. Where the expansion would contain a very large number of concepts, a limit of 600 concepts will be listed. Note that expansions are only ever current at the time they are created. The date/time of expansion is currently only viewable from within the XML or JSON view of the ValueSet.

Example ValueSets from the UK Core

This section is intended to provide examples that illustrate the different ways in which the Content Logical Definition (i.e. the element and its children elements) might be constructed, depending on the required code system content of the value set.

Value set containing content from a single entire UK Core CodeSystem

https://simplifier.net/HL7FHIRUKCoreR4/UKCore-AddressKeyType/~xml

Value set containing selected content from a single FHIR standard CodeSystem and selected content from a single UK Core CodeSystem

https://simplifier.net/HL7FHIRUKCoreR4/UKCore-MedicationRequestCourseOfTherapy-duplicate-2/~xml

Value set containing content from a single entire UK Core CodeSystem and selected nullFlavors

https://simplifier.net/HL7FHIRUKCoreR4/UKCore-NHSNumberVerificationStatus-duplicate-2/~xml

Value set containing selected content from a single UK Core CodeSystem and multiple FHIR standard CodeSystems and also excluding specific concepts

https://simplifier.net/HL7FHIRUKCoreR4/UKCore-PersonRelationshipType-110/~xml

Value set containing selected individual codes from SNOMED

https://simplifier.net/HL7FHIRUKCoreR4/UKCore-ReasonImmunizationNotAdministered/~xml

Value set containing a single Reference Set from SNOMED

https://simplifier.net/HL7FHIRUKCoreR4/UKCore-MedicationForm/~xml

Value set containing a single hierarchy from SNOMED

https://simplifier.net/HL7FHIRUKCoreR4/UKCore-BodySite/~xml

Value set containing a multiple hierarchies from SNOMED

https://simplifier.net/HL7FHIRUKCoreR4/UKCore-VaccinationProcedure/~xml

Complex value set (SNOMED hierarchies and individual codes, and dm+d concept classes)

https://simplifier.net/HL7FHIRUKCoreR4/UKCore-AllergyCode/~xml

Expanding ValueSets for the UK Core

At the time of writing, a direct interface to a Terminology Server to enable automated expansion of a ValueSet content within Simplifier has not been implemented.

It is possible to manually obtain a ValueSet expansion from the NHS Digital Terminology Server (Ontoserver), and this expansion can be manually incorporated into an existing ValueSet. This approach was taken for the ValueSet examples above.

For some SNOMED ValueSets, the amount of content (e.g. 100,000s of concepts) is far too large to be incorporated into a ValueSet expansion or its display in Simplifier. For such ValueSets, a fragment of the ValueSet expansion can still be made available however.

CodeSystem Design

This section provides background information on metadata used within CodeSystem resources:

• the metadata element name
• the cardinality of the metadata in the HL7 FHIR standard
• the cardinality of the metadata to be applied in the UK Core
• the type (i.e. datatype) for the metadata, taken from the HL7 FHIR standard
• a definition of the metadata, taken from the HL7 FHIR standard
• any constraints that the HL7 FHIR standard applies to the metadata
• any notes relating to the use of the metadata within the UK Core

Further information about the CodeSystem resource is available online.

This section also lists HL7 FHIR standard extensions that may be considered relevant to a UK Core CodeSystem, followed by an XML template for a new CodeSystem and links to example CodeSystems already created for the UK Core.

Metadata usage

The list below contains generic Resource elements, followed by generic DomainResource elements, followed by CodeSystem resource elements.

View further information about FHIR base resource definitions and elements.

View further information about FHIR domain resources.

    <identifier>
        <system value="urn:ietf:rfc:3986"/>
        <value value="urn:oid:2.16.840.1.113883.2.1.3.2.4.16.21"/>
    </identifier>

CodeSystem Extensions

This section lists HL7 FHIR standard code system extensions that could be considered for use in UK Core code systems.

The full list of FHIR standard code system extensions is available online.

codesystem-concept-comments

The FHIR Standard extension https://hl7.org/fhir/extension-codesystem-concept-comments.html could be considered where there is a need to include comments against individual code system concepts.

See the following example: https://hl7.org/fhir/codesystem-administrative-gender.xml.html

XML template for a new CodeSystem

<CodeSystem xmlns="http://hl7.org/fhir">
	<id value="UKCore-[ConcatenatedBusinessName(s)]" />
	<url value="https://fhir.hl7.org.uk/CodeSystem/UKCore-[ConcatenatedBusinessName(s)]" />
	<version value="1.0.0" />
	<name value="UKCore[ConcatenatedBusinessName(s)]" />
	<title value="UK Core [SpaceSeparatedBusinessName(s)]" />
	<status value="draft" />
	<date value="2021-07-01" />
	<publisher value="HL7 UK" />
	<contact>
		<name value="HL7 UK" />
		<telecom>
			<system value="email" />
			<value value="secretariat@hl7.org.uk" />
			<use value="work" />
			<rank value="1" />
		</telecom>
	</contact>
	<contact>
		<name value="NHS Digital" />
		<telecom>
			<system value="email" />
			<value value="interoperabilityteam@nhs.net" />
			<use value="work" />
			<rank value="2" />
		</telecom>
	</contact>
	<description value="A set of codes that define [business definition]." />
	<copyright value="Copyright &#169; [YYYY]+ HL7 UK Licensed under the Apache License, Version 2.0 (the &quot;License&quot;); you may not use this file except in compliance with the License. You may obtain a copy of the License at	http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an &quot;AS IS&quot; BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. HL7&#174; FHIR&#174; standard Copyright &#169; 2011+ HL7	The HL7&#174; FHIR&#174; standard is used under the FHIR license. You may obtain a copy of the FHIR license at	https://www.hl7.org/fhir/license.html." />
<!--Only include the following caseSensitive element where the CodeSystem contains alpha/alphanumeric codes.-->	
	<caseSensitive value="true" />
	<content value="complete" />
	<!--The concept element below is repeated for each concept in the code system.-->
	<concept>
		<code value="[conceptCode]" />
		<display value="[conceptDisplay]" />
	</concept>
</CodeSystem>

Creating codes for a CodeSystem

Where they don't already exist, the UK Core approach to creating codes for concepts in a new CodeSystem is by placing a hyphen between each word of the display value (if they contain more than one word) and using solely lower case alphabetic characters.

An exception to this is where the CodeSystem is a copy of a Data Dictionary set of concepts from any of the UK nations, where the approach is to faithfully use both the code and its description within the CodeSystem as defined within the Data Dictionary source at the time of creation of the CodeSystem. Note that for some CodeSystems already in existence in the UK core, including content previously created for other projects, alternative code construction forms have also been used.

Example CodeSystems from the UK Core

Code system created for the UK Core

https://simplifier.net/HL7FHIRUKCoreR4/UKCore-MedicationPrescribingOrganization/~xml

Code system based on previously created content

https://simplifier.net/HL7FHIRUKCoreR4/UKCore-DeathNotificationStatus/~xml

Code system based on Data Dictionary content (to be provided once the resource has been incorporated into the UK Core).

ConceptMap Design

This section provides background information on metadata used within ConceptMap resources:

• the metadata element name
• the cardinality of the metadata in the HL7 FHIR standard
• the cardinality of the metadata to be applied in the UK Core
• the type (i.e. datatype) for the metadata, taken from the HL7 FHIR standard
• a definition of the metadata, taken from the HL7 FHIR standard
• any constraints that the HL7 FHIR standard applies to the metadata
• any notes relating to the use of the metadata within the UK Core Further information about the ConceptMap resource is available online.

This section also lists HL7 FHIR standard extensions that may be considered relevant to a ConceptMap, followed by an XML template for a new ConceptMap and links to example ConceptMaps already created for the UK Core.

Metadata usage

The list below contains generic Resource elements, followed by generic DomainResource elements, followed by ConceptMap resource elements.

View further information about FHIR base resource definitions and elements.

View further information about FHIR domain resources.

    <identifier>
        <system value="urn:ietf:rfc:3986"/>
        <value value="urn:oid:2.16.840.1.113883.2.1.3.2.4.16.21"/>
    </identifier>

ConceptMap Extensions

This section lists HL7 FHIR Standard concept map extensions that could be considered for use in UK Core concept maps.

The full list of HL7 FHIR Standard concept map extensions is available online.

Concept-bidirectional

The HL7 FHIR standard extension https://hl7.org/fhir/extension-concept-bidirectional.html MAY be used where the ConceptMap can be safely interpreted in reverse, in order to avoid needing to create an additional ConceptMap for the reverse mapping.

XML template for a new ConceptMap

<ConceptMap xmlns="http://hl7.org/fhir">
	<id value="UKCore-[ConcatenatedBusinessName(s)]" />
	<url value="https://fhir.hl7.org.uk/ConceptMap/ConceptMap-UKCore-[ConcatenatedBusinessName(s)]" />
	<version value="1.0.0" />
	<name value="ConceptMap[ConcatenatedBusinessName(s)]" />
	<title value="Concept Map - [SpaceSeparatedBusinessName(s)]" />
	<status value="draft" />
	<date value="2021-07-01" />
	<publisher value="HL7 UK" />
	<contact>
		<name value="HL7 UK" />
		<telecom>
			<system value="email" />
			<value value="secretariat@hl7.org.uk" />
			<use value="work" />
			<rank value="1" />
		</telecom>
	</contact>
	<contact>
		<name value="NHS Digital" />
		<telecom>
			<system value="email" />
			<value value="interoperabilityteam@nhs.net" />
			<use value="work" />
			<rank value="2" />
		</telecom>
	</contact>
	<description value="A mapping between codes from [sourceCodeSystem] and codes from [targetCodeSystem]." />
	<copyright value="Copyright &#169; [YYYY]+ HL7 UK Licensed under the Apache License, Version 2.0 (the &quot;License&quot;); you may not use this file except in compliance with the License. You may obtain a copy of the License at	http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an &quot;AS IS&quot; BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. HL7&#174; FHIR&#174; standard Copyright &#169; 2011+ HL7	The HL7&#174; FHIR&#174; standard is used under the FHIR license. You may obtain a copy of the FHIR license at	https://www.hl7.org/fhir/license.html." />
	<sourceUri value="[sourceValueSetURI]" />
	<targetUri value="[targetValueSetURI]" />
	<!--The group element is repeated for each separate source code system within the concept map.-->
	<group>
		<source value="[sourceCodeSystemURI]" />
		<target value="[targetCodeSystemURI]" />
		<element>
			<code value="[sourceCode]" />
			<display value="[sourcedisplay]" />
			<target>
				<code value="[targetCode]" />
				<display value="[targetdisplay]" />
				<equivalence value="[equivalence]" />
			</target>
		</element>
	</group>
</ConceptMap>

Example Concept Maps from the UK Core

ConceptMap between an HL7UK code system and a code system of SNOMED concepts

https://simplifier.net/HL7FHIRUKCoreR4/UKCore-ConditionEpisodicity-duplicate-2/~xml

Terminology Metadata Design

This section describes the approach taken for metadata relating to (Terminology assets, ValueSet, CodeSystem and ConceptMap resources) used within the UK Core.

Properties for ValueSets, CodeSystems and ConceptMaps

Filename format The physical filename format to be used for these assets is as below:

• ValueSets: ValueSet-UKCore-[Name]
• CodeSystems: CodeSystem-UKCore-[Name]
• ConceptMaps: ConceptMap-UKCore-[Name]

url property The url format to be used for these assets is as below:

• ValueSets: https://fhir.hl7.org.uk/ValueSet/UKCore-[Name]
• CodeSystems: https://fhir.hl7.org.uk/CodeSystem/UKCore-[Name]
• ConceptMaps: https://fhir.hl7.org.uk/ConceptMap/UKCore-[Name]

Common properties

• id: UKCore-[Name]
• name: UKCore[Name]
• title: UK Core [Name] – remember to use spaces between words
• status: draft – unless stated otherwise

Copyright, publisher and contact information – ValueSets and ConceptMaps

The copyright, publisher and contact information to be used for ValueSets and ConceptMaps is as below:

• copyright: Copyright © 2020 HL7 UK Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. HL7® FHIR® standard Copyright © 2011+ HL7 The HL7® FHIR® standard is used under the FHIR license. You may obtain a copy of the FHIR license at https://www.hl7.org/fhir/license.html.
• publisher: HL7 UK
• contact information:
  • name: HL7 UK
  • system: email
  • value: secretariat@hl7.org.uk
  • use: work
  • rank: 1
• contact information:
  • name: NHS Digital
  • system: email
  • value: interoperabilityteam@nhs.net
  • use: work
  • rank: 2

Copyright, publisher and contact information – CodeSystems

By default, all CodeSystems will use the following copyright, publisher and contact information:

• copyright: Copyright © 2020 NHS Digital
• publisher: NHS Digital
• contact information:
  • name: NHS Digital
  • system: email
  • value: interoperabilityteam@nhs.net
  • use – work

This may change if a different copyright owner, publisher and contact is identified in CodeSystem requirements.

Instance Example Design

This section details how examples are constructed, named and referenced in the UK Core.

Simplifier Constraints and Configuration

Instance examples in Simplifier need to be correctly named and constructed to avoid duplicates being generated or other conflicts occurring. This guidance overrides the default Simplifier behaviour and has been developed following consultation with the Simplifier development team.

Configuration of Simplifier

Simplifier creates metadata around an instance when imported from GitHub. This metadata needs a custom configuration to allow the examples to be correctly imported. The url for updating the metadata expressions is accessible via:

"https://simplifier.net/ukcore/$editmetadataexpressions" which requires Admin access to update or configure.

For each FHIR resource type the following three lines need adding in the editor pane.

• ResourceName.Title: ('ResourceName example: ' + id)
• ResourceName.Description: ('ResourceName example: ' + id)
• ResourceName.UrlKey: id

For example for Patient resource the following should be added:

• Patient.Title: ('Patient example: ' + id)
• Patient.Description: ('Patient example: ' + id)
• Patient.UrlKey: id

Naming and Construction of Examples of Resources

This section details how the examples of a resource or group of resources are done. Examples always take on the name of the "root" resource. The root of the example is the first tag name in an example. This must always be a resource name. Extension examples are handled slightly differently and are documented in a separate sub-section below.

Within Simplifier, there are four metadata elements:

Title

This is auto-generated as shown in the example below:

• AllergyIntolerance example:UKCore-AllergyIntolerance-EnteredInError-Example

Description

This is auto-generated as shown in the example below:

• AllergyIntolerance example:UKCore-AllergyIntolerance-EnteredInError-Example

URL

This is auto-generated as shown in the example below:

• UKCore-AllergyIntolerance-EnteredInError-Example

Filename

The filename is taken from the filename of the example in GitHub. The filename in GitHub MUST be in the following format:

• UKCore-"ResourceName"-"FurtherDescription"-Example.xml, here the "FurtherDescription" is enough information for a reader to to able to understand what the example is representing. This description must also be sufficient to make the example unique in the UK Core. For example:

• UKCore-AllergyIntolerance-EnteredInError-Example.xml

Naming and Construction of Examples of Extensions

This section details how the examples of an extension are done. All extension examples are inserted into resource tags for the context for the extension. For example, an extension for Patient will have an opening Patient tag, then an id element present before the extension elements, then a closing Patient tag.

For example:

<Patient>

<id value="UKCore-Patient-Extension-EthnicCategory-Example" />

<extension>

...... extension elements

</extension>

</Patient>|

Within simplifier there are four Simplifier metadata elements which are shown below.

Title

This is auto-generated as shown in the example below:

• Patient example:UKCore-Patient-Extension-EthnicCategory-Example

Description

This is auto-generated as shown in the example below:

• Patient example:UKCore-Patient-Extension-EthnicCategory-Example

URL

This is auto-generated as shown in the example below:

• UKCore-Patient-Extension-EthnicCategory-Example

Filename

The filename is taken from the filename of the extension example in GitHub. The filename in GitHub MUST be in the following format:

• UKCore-"ResourceName"-Extension-"ExtensionName"-Example.xml For example:

• UKCore-Patient-Extension-EthnicCategory-Example.xml

Important Note: the properties of examples MUST not be manually changed or updated in Simplifier

An illustration of the properties of an example is shown below for information.