ValueSet Design
This section provides background information on metadata specific to the UKCore ValueSet resources.
Further information about the ValueSet resource is available.
Metadata usage
The list below contains the element differences between the UKcore and HL7. The tables are split into 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.
Resource Elements
| Element name | Base Cardinality | UK Core Cardinality | Type | Definition, Constraints and Notes |
|---|---|---|---|---|
| id | 0..1 | 1..1 | id | Logical id of this artifact. In the UK Core the format is the following, with the BusinessName in PascalCase: UKCore-[BusinessNames]. |
Domain Resource Elements
| Element name | Base Cardinality | UK Core Cardinality | Type | Definition, Constraints and Notes |
|---|---|---|---|---|
| url | 0..1 | 1..1 | uri | Canonical identifier for this ValueSet, represented as a URI (globally unique). In the UK Core the format is the following, with the BusinessName in PascalCase: https://fhir.hl7.org.uk/ValueSet/UKCore-[BusinessNames]. |
| identifier | 0..* | 0..* | Identifier | Additional identifier for the ValueSet, for example an OID. If this is an OID, this should be in the following format: <identifier>
<system value="urn:ietf:rfc:3986"/>
<value value="urn:oid:2.16.840.1.113883.2.1.3.2.4.16.21"/>
</identifier>Further guidance may be needed in due course. |
| version | 0..1 | 1..1 | string | Business version of the ValueSet. This will follow the Semantic Versioning standard [major.minor.patch]. |
| name | 0..1 | 1..1 | string | Computer readable name, this should reflect the name in the url element. In the UK Core the format is PascalCase: UKCore[BusinessNames]. |
| title | 0..1 | 1..1 | string | Human readable name, this should reflect the name in the url element. In the UK Core the format is Proper Case: UK Core [Business Names]. |
| status | 1..1 | 1..1 | code | The publication status as defined in value set publication-status. For the UKCore these are defined as:
|
| date | 0..1 | 1..1 | dateTime | The date (and optionally time) when the ValueSet was published or last changed. The date must change when the business version or status changes. Only the date, without time, is populated in the UK Core. |
| publisher | 0..1 | 1..1 | string | Name of the publisher (organization or individual). For all UK Core ValueSetss, where the base URL is https://fhir.hl7.org.uk, this will be HL7 UK. |
| contact | 0..* | 1..* | ContactDetail | Contact details for the publisher. See the Metadata Design for details of how this SHALL be populated for all UK Core Valuesets, where the base URL is https://fhir.hl7.org.uk/. |
| description | 0..1 | 1..1 | markdown | Natural language description of the ValueSet The UKCore preference can be found under the ValueSet Description section. |
| copyright | 0..1 | 1..1 | markdown | A copyright statement relating to the ValueSet and/or its contents.
All UK Core ValueSets SHALL contain the the copright as listed in Metadata Design |
| compose | 0..1 | 1..1 | BackboneElement | A set of criteria that define the contents of the ValueSet by including or excluding codes selected from the specified code system(s) that the ValueSet draws from. This is also known as the Content Logical Definition (CLD). See the following sections for details on how to populate this: - Content Logical Definition – ValueSets containing UK Core CodeSystems, and - Content Logical Definition – ValueSets containing SNOMED concepts. |
ValueSet Resource Elements
| - include | 1..* | 1..* | BackboneElement | Include one or more codes from a code system or other ValueSet(s). All the conditions in an include must be true. If a system is listed, all the codes from the system are listed. If one or more filters are listed, all of the filters must apply. If one or more ValueSets are listed, the codes must be in all the ValueSets. E.g. each include is 'include all the codes that meet all these conditions'. |
| - - system | 0..1 | 0..1 | uri | A ValueSet include/exclude SHALL have a ValueSet or a system. A ValueSet with concepts or filters SHALL include a system. Currently all UK Core ValueSets contain a system and none contain a ValueSet. |
| compose .include .concept .display |
0..1 | 1..1 | string | The text to display to the user for this concept in the context of this valueset. For SNOMED concepts this will always be the preferred term. Is only required when using single concepts from a CodeSystem, would we use it on SNOMED CT? |
| - - filter | 0..* | 0..* | BackboneElement | Select concepts by specify a matching criterion based on the properties (including relationships) defined by the system, or on filters defined by the system. If multiple filters are specified, they SHALL all be true. A ValueSet with concepts or filters SHALL include a system. Cannot have both concept and filter. For ValueSets containing SNOMED concepts, see the SNOMED Additional Guidance section. |
| - - - property | 1..1 | 1..1 | code | A code that identifies a property or a filter defined in the code system. For UK Core ValueSets containing SNOMED concepts encapsulated within an ECL expression, the "constraint" value is used. |
| - - - op | 1..1 | 1..1 | code | The kind of operation to perform as a part of the filter criteria, as defined in https://hl7.org/fhir/valueset-filter-operator.html [= | is-a | descendent-of | is-not-a | regex | in | not-in | generalizes | exists]. For UK Core ValueSets containing SNOMED concepts encapsulated within an ECL expression, the "=" value is used. |
| - - - value | 1..1 | 1..1 | string | The match value may be either a code defined by the system, or a string value, which is a regex match on the literal string of the property value (if the filter represents a property defined in CodeSystem) or of the system filter value (if the filter represents a filter defined in CodeSystem) when the operation is 'regex', or one of the values (true and false), when the operation is 'exists'. For UK Core ValueSets containing SNOMED concepts encapsulated within an ECL expression, the ECL expression is contained in this element. |
| - - valueSet | 0..* | 0..* | canonical(ValueSet) | Selects the concepts found in this ValueSet (based on its ValueSet definition). This is an absolute URI that is a reference to ValueSet.url. If multiple ValueSets are specified this includes the union of the contents of all of the referenced ValueSets. A ValueSet include/exclude SHALL have a ValueSet or a system. Currently all UK Core ValueSets contain a system and none contain a ValueSet. |
| - exclude | 0..* | 0..* | See include | Explicitly exclude codes from a code system or other ValueSets. An example of the use of exclude can be found in the Example ValueSets from the UK Core section. |
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 Description
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 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.
ValueSets containing 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 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 and Using SNOMED CT with HL7 Standardsis 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 are not 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>
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
ValueSet containing content from a single entire UK Core CodeSystem
ValueSet containing content from a single entire UK Core CodeSystem and selected nullFlavors
Complex ValueSet (SNOMED hierarchies and individual codes, and dm+d concept classes)
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 and dm+d ValueSets, where the expansion would contain a list of concepts larger than 300, 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.