ValueSet Design

Metadata Usage

The list below contains the element differences between the UKCore and HL7.

Base Resource Definitions

View further information about FHIR base resource definitions.

Resource ValueSet - Content

View further information about Resource ValueSet - Content.

ValueSet Extensions

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

ValueSet Descriptions

A free text natural language description of the of the ValueSet from a consumer's perspective. The textual description specifies the span of meanings for concepts to be included within the ValueSet Expansion, and also may specify the intended use and limitations of the ValueSet. In the UK Core there is a preference to use the words "define" or "describe" and more rarely, "identify".

The prefix SHOULD be as follows:

A set of codes that define [description].

For SNOMED CT and dm+d concepts, the following SHOULD be added after the prefix:

• For a ValueSet containing a set of SNOMED CT Reference Sets and/or hierarchies and/or individual concepts:

Selected from the following SNOMED CT UK coding system: \n 
- [long syntax1] [RefSet/hierarchy1 code] | [description of RefSet/hierarchy1] \n
- [long syntax2] [RefSet/hierarchy2 code] | [description of RefSet/hierarchy2] \n,  etc. 

• Where the ValueSet include dm+d concept classes:

Selected from the following dm+d (dictionary of medicines and devices) concept classes:\n
[concept1] | [description1] \n
[concept2] | [description2] \n, etc.

Where the ValueSet includes nullFlavor(s) in addition to other sets of codes, the suffix SHOULD be as the following:

Where no [MainCodeSystems] coded information is available, a specific code from the nullFlavor CodeSystem can be used instead to indicate this.

For complicated descriptions, particularly where a complex set of SNOMED references is used, and where inclusion of a carriage return / line feed can make the content more presentable in Simplifier, the sequence can be inserted to start a new line and can be inserted to leave a line break before the next line starts. For examples see Example ValueSets from the UK Core section.

Country Specific CodeSystems

Important note regarding the use of the "preferred" binding strength for UK Core ValueSets containing CodeSystems specific to individual UK countries. Where different countries within the UK use different sets of concepts for the same data item, currently the default approach to supporting this data within the UK Core is to create a CodeSystem for each individual country where requirements have been confirmed, and incorporate each such CodeSystem within a ValueSet that is then bound into the profile or extension supporting the data item (referred to as the "individual country specific CodeSystem" approach).

In most cases where this approach is taken, for some of the concepts the ValueSet does contain more than one entry for the same concept. For this reason, the use of the "extensible" binding strength is deemed to be inappropriate and "preferred" is determined to be the most suitable binding strength to use instead.

Content Logical Definition - ValueSets containing UK Core CodeSystems

Content Logical Definition - Single 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 CT concepts

The UK Core approach is that all SNOMED CT is encapsulated within the Content Logical Definition using SNOMED CT 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 and Using SNOMED CT with HL7 Standards is available online.

The ECL informative long syntax SHALL be used to identify a hierarchy or reference set within 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 SHALL NOT be included in the ECL statement to avoid potential duplication with the ValueSet description and to avoid any need to encode separator characters. The ValueSet 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 ValueSet expansion, again to avoid duplication.

<compose>
    <include>
        <system value="http://snomed.info/sct" />
        <filter>
            <property value="constraint" />
            <op value="=" />
            <value value="[long syntax1] [SNOMED CT Code1] OR [long syntax2] [SNOMED CT Code2] OR , etc." />
        </filter>
    </include>
</compose>

Content Logical Definition – ValueSets containing dm+d concepts

<compose>
    <include>
        <system value="https://dmd.nhs.uk" />
        <filter>
            <property value="parent" />
            <op value="=" />
            <value value="[ValueSet1]" />
        </filter>
    </include>
    <include>
        <system value="https://dmd.nhs.uk" />
        <filter>
            <property value="parent" />
            <op value="=" />
            <value value="[ValueSet1]" />
        </filter>
    </include>
</compose>

Expanding ValueSets

For some SNOMED CT and dm+d ValueSets, where the expansion would contain a list of concepts larger than 600, they will not be expanded so that the viewers do not misinterpret a partially expanded list as a full list.

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.

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

ValueSet Illustration

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 ValueSet.

• ValueSet containing content from a single entire UK Core CodeSystem

• ValueSet containing selected content from a single FHIR standard CodeSystem and selected content from a single UK Core CodeSystem

• ValueSet containing content from a multiple UK Core CodeSystems and selected nullFlavors

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

• ValueSet containing selected individual codes from SNOMED CT

• ValueSet containing a single Reference Set from SNOMED CT

• ValueSet containing a single hierarchy from SNOMED CT

• ValueSet containing a multiple hierarchies from SNOMED CT

• Complex ValueSet (SNOMED CT hierarchies and individual codes, and dm+d concept classes)

ValueSet containing content from a single entire UK Core CodeSystem

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

HTML View Table View XML View JSON View

HTML View

This value set includes codes from the following code systems:

• The following codes from system: medicationRequest Course of Therapy Codes

  Code	Display
  continuous	Continuous long term therapy
  acute	Short course (acute) therapy

• The following codes from system: UKCoreMedicationRequestCourseOfTherapy

  Code	Display
  continuous-repeating-dispensing	Continuous long term (repeat dispensing)

Expansion

This expansion was generated on 2021-09-09T15:02:07+00:00

This value set contains 3 concepts

Code	System	Display
continuous	http://terminology.hl7.org/CodeSystem/medicationrequest-course-of-therapy	Continuous long term therapy
acute	http://terminology.hl7.org/CodeSystem/medicationrequest-course-of-therapy	Short course (acute) therapy
continuous-repeating-dispensing	https://fhir.hl7.org.uk/CodeSystem/UKCore-MedicationRequestCourseOfTherapy	Continuous long term (repeat dispensing)

Table View

ValueSet.id[0]	UKCore-MedicationRequestCourseOfTherapy
ValueSet.url[0]	https://fhir.hl7.org.uk/ValueSet/UKCore-MedicationRequestCourseOfTherapy
ValueSet.version[0]	1.0.0
ValueSet.name[0]	UKCoreMedicationRequestCourseOfTherapy
ValueSet.title[0]	UK Core Medication Request Course Of Therapy
ValueSet.status[0]	active
ValueSet.date[0]	2021-09-10
ValueSet.publisher[0]	HL7 UK
ValueSet.contact[0].name[0]	HL7 UK
ValueSet.contact[0].telecom[0].system[0]	email
ValueSet.contact[0].telecom[0].value[0]	ukcore@hl7.org.uk
ValueSet.contact[0].telecom[0].use[0]	work
ValueSet.contact[0].telecom[0].rank[0]	1
ValueSet.description[0]	A set of codes to define a course of therapy for a medication request.
ValueSet.copyright[0]	Copyright © 2021+ 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.
ValueSet.compose[0].include[0].system[0]	http://terminology.hl7.org/CodeSystem/medicationrequest-course-of-therapy
ValueSet.compose[0].include[0].concept[0].code[0]	continuous
ValueSet.compose[0].include[0].concept[0].display[0]	Continuous long term therapy
ValueSet.compose[0].include[0].concept[1].code[0]	acute
ValueSet.compose[0].include[0].concept[1].display[0]	Short course (acute) therapy
ValueSet.compose[0].include[1].system[0]	https://fhir.hl7.org.uk/CodeSystem/UKCore-MedicationRequestCourseOfTherapy
ValueSet.compose[0].include[1].concept[0].code[0]	continuous-repeating-dispensing
ValueSet.compose[0].include[1].concept[0].display[0]	Continuous long term (repeat dispensing)
ValueSet.expansion[0].identifier[0]	6fb36f9d-bddd-4fe5-9ed8-a9b1a8ca6d80
ValueSet.expansion[0].timestamp[0]	2021-09-09T15:02:07+00:00
ValueSet.expansion[0].total[0]	3
ValueSet.expansion[0].offset[0]	0
ValueSet.expansion[0].parameter[0].name[0]	version
ValueSet.expansion[0].parameter[0].value[0]	https://fhir.hl7.org.uk/CodeSystem/UKCore-MedicationRequestCourseOfTherapy|1.0.0
ValueSet.expansion[0].parameter[1].name[0]	version
ValueSet.expansion[0].parameter[1].value[0]	http://terminology.hl7.org/CodeSystem/medicationrequest-course-of-therapy|4.0.1
ValueSet.expansion[0].parameter[2].name[0]	count
ValueSet.expansion[0].parameter[2].value[0]	2147483647
ValueSet.expansion[0].parameter[3].name[0]	offset
ValueSet.expansion[0].parameter[3].value[0]	0
ValueSet.expansion[0].contains[0].system[0]	http://terminology.hl7.org/CodeSystem/medicationrequest-course-of-therapy
ValueSet.expansion[0].contains[0].version[0]	4.0.1
ValueSet.expansion[0].contains[0].code[0]	continuous
ValueSet.expansion[0].contains[0].display[0]	Continuous long term therapy
ValueSet.expansion[0].contains[1].system[0]	http://terminology.hl7.org/CodeSystem/medicationrequest-course-of-therapy
ValueSet.expansion[0].contains[1].version[0]	4.0.1
ValueSet.expansion[0].contains[1].code[0]	acute
ValueSet.expansion[0].contains[1].display[0]	Short course (acute) therapy
ValueSet.expansion[0].contains[2].system[0]	https://fhir.hl7.org.uk/CodeSystem/UKCore-MedicationRequestCourseOfTherapy
ValueSet.expansion[0].contains[2].version[0]	1.0.0
ValueSet.expansion[0].contains[2].code[0]	continuous-repeating-dispensing
ValueSet.expansion[0].contains[2].display[0]	Continuous long term (repeat dispensing)

XML View

<ValueSet xmlns="http://hl7.org/fhir">

<id value="UKCore-MedicationRequestCourseOfTherapy" />

<url value="https://fhir.hl7.org.uk/ValueSet/UKCore-MedicationRequestCourseOfTherapy" />

<version value="1.0.0" />

<name value="UKCoreMedicationRequestCourseOfTherapy" />

<title value="UK Core Medication Request Course Of Therapy" />

<status value="active" />

<date value="2021-09-10" />

<publisher value="HL7 UK" />

<contact>

<name value="HL7 UK" />

<telecom>

<system value="email" />

<value value="ukcore@hl7.org.uk" />

<use value="work" />

<rank value="1" />

</telecom>

</contact>

<description value="A set of codes to define a course of therapy for a medication request." />

<copyright value="Copyright © 2021+ 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." />

<compose>

<include>

<system value="http://terminology.hl7.org/CodeSystem/medicationrequest-course-of-therapy" />

<concept>

<code value="continuous" />

<display value="Continuous long term therapy" />

</concept>

<concept>

<code value="acute" />

<display value="Short course (acute) therapy" />

</concept>

</include>

<include>

<system value="https://fhir.hl7.org.uk/CodeSystem/UKCore-MedicationRequestCourseOfTherapy" />

<concept>

<code value="continuous-repeating-dispensing" />

<display value="Continuous long term (repeat dispensing)" />

</concept>

</include>

</compose>

<expansion>

<identifier value="6fb36f9d-bddd-4fe5-9ed8-a9b1a8ca6d80" />

<timestamp value="2021-09-09T15:02:07+00:00" />

<total value="3" />

<offset value="0" />

<parameter>

<name value="version" />

<valueUri value="https://fhir.hl7.org.uk/CodeSystem/UKCore-MedicationRequestCourseOfTherapy|1.0.0" />

</parameter>

<parameter>

<name value="version" />

<valueUri value="http://terminology.hl7.org/CodeSystem/medicationrequest-course-of-therapy|4.0.1" />

</parameter>

<parameter>

<name value="count" />

<valueInteger value="2147483647" />

</parameter>

<parameter>

<name value="offset" />

<valueInteger value="0" />

</parameter>

<contains>

<system value="http://terminology.hl7.org/CodeSystem/medicationrequest-course-of-therapy" />

<version value="4.0.1" />

<code value="continuous" />

<display value="Continuous long term therapy" />

</contains>

<contains>

<system value="http://terminology.hl7.org/CodeSystem/medicationrequest-course-of-therapy" />

<version value="4.0.1" />

<code value="acute" />

<display value="Short course (acute) therapy" />

</contains>

<contains>

<system value="https://fhir.hl7.org.uk/CodeSystem/UKCore-MedicationRequestCourseOfTherapy" />

<version value="1.0.0" />

<code value="continuous-repeating-dispensing" />

<display value="Continuous long term (repeat dispensing)" />

</contains>

</expansion>

</ValueSet>

JSON View

{

"resourceType": "ValueSet",

"id": "UKCore-MedicationRequestCourseOfTherapy",

"url": "https://fhir.hl7.org.uk/ValueSet/UKCore-MedicationRequestCourseOfTherapy",

"version": "1.0.0",

"name": "UKCoreMedicationRequestCourseOfTherapy",

"title": "UK Core Medication Request Course Of Therapy",

"status": "active",

"date": "2021-09-10",

"publisher": "HL7 UK",

"contact": [

{

"name": "HL7 UK",

"telecom": [

{

"system": "email",

"value": "ukcore@hl7.org.uk",

"use": "work",

"rank": 1

}

]

}

],

"description": "A set of codes to define a course of therapy for a medication request.",

"copyright": "Copyright © 2021+ 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.",

"compose": {

"include": [

{

"system": "http://terminology.hl7.org/CodeSystem/medicationrequest-course-of-therapy",

"concept": [

{

"code": "continuous",

"display": "Continuous long term therapy"

},

{

"code": "acute",

"display": "Short course (acute) therapy"

}

]

},

{

"system": "https://fhir.hl7.org.uk/CodeSystem/UKCore-MedicationRequestCourseOfTherapy",

"concept": [

{

"code": "continuous-repeating-dispensing",

"display": "Continuous long term (repeat dispensing)"

}

]

}

]

},

"expansion": {

"identifier": "6fb36f9d-bddd-4fe5-9ed8-a9b1a8ca6d80",

"timestamp": "2021-09-09T15:02:07+00:00",

"total": 3,

"offset": 0,

"parameter": [

{

"name": "version",

"valueUri": "https://fhir.hl7.org.uk/CodeSystem/UKCore-MedicationRequestCourseOfTherapy|1.0.0"

},

{

"name": "version",

"valueUri": "http://terminology.hl7.org/CodeSystem/medicationrequest-course-of-therapy|4.0.1"

},

{

"name": "count",

"valueInteger": 2147483647

},

{

"name": "offset",

"valueInteger": 0

}

],

"contains": [

{

"system": "http://terminology.hl7.org/CodeSystem/medicationrequest-course-of-therapy",

"version": "4.0.1",

"code": "continuous",

"display": "Continuous long term therapy"

},

{

"system": "http://terminology.hl7.org/CodeSystem/medicationrequest-course-of-therapy",

"version": "4.0.1",

"code": "acute",

"display": "Short course (acute) therapy"

},

{

"system": "https://fhir.hl7.org.uk/CodeSystem/UKCore-MedicationRequestCourseOfTherapy",

"version": "1.0.0",

"code": "continuous-repeating-dispensing",

"display": "Continuous long term (repeat dispensing)"

}

]

}

}

ValueSet containing content from a multiple UK Core CodeSystems and selected nullFlavors

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