View raw Markdown
type: resourceresource: ValueSet

ValueSet

Introduction

Scope and Usage

The FHIR terminology specification is based on the concepts of code system and value set originally defined in HL7 v3 Core Principles:

Value sets have 2 aspects:

The ValueSet resource can carry either the .compose or the .expansion, both of them, or neither of them (if only the metadata is being represented). There is an "$expand" operation which can be used to ask a server to generate an expansion given the composition rules, in a particular context, and a "$validate-code" operation which can be used to ask a server to check whether a given code or concept is in the value set in a particular context.

Boundaries and Relationships

Value Sets are used by many resources:

For a full list of uses, see below.

The Characteristics of the ValueSet resource are derived from Formal Value Set Definitions:

Background and Context

When using value sets, proper differentiation between a code system and a value set is important. This is one very common area where significant clinical safety risks occur in practice. Implementers should be familiar with the content in Using Codes in Resources.

ValueSet Identification

A value set has 3 identifiers:

In addition, any expansion for the value set also has ValueSet.expansion.identifier which uniquely identifies each expansion. For further information regarding resource identification, see Resource Identity.

This means that each value set has 2 different URLs that can be used to reference it - its canonical URL (the url element), and its local location from which it may be retrieved (which includes the id element). Because it is common practice to copy (cache) value sets locally, most references to value sets use the canonical URL.

For example, the value sets published as part of FHIR all have a location ("literal") URI which is the URL where they may be accessed in the FHIR specification itself. Note, though, that while a new version of the FHIR Specification is being prepared, value sets that are published in the drafts will not be found in the current published FHIR specification at their canonical URL.

Alternatively, the identifier and version elements may be used to reference this value set in a design, a profile, a CDA template or HL7 v3 message (in the CD data type valueSet and valueSetVersion properties). These different contexts may make additional restrictions on the possible values of these elements. The identifier is generally not needed when using value sets in a FHIR context, where the canonical URL is always the focus.

Intensional vs Extensional

A value set may be described as intensional or extensional. The terms intensional and extensional come from the fields of mathematical logic and set theory.

An intensionally defined value set may be algorithmically defined e.g. all codes with the word diabetes in the description. A key benefit of intensionally defined value sets is that their expansion can be dynamically updated without changing the value set definition. This helps healthcare organizations keep current for example, when new drugs (and their associated codes) become available or codes for diseases and other clinical concepts are added.

Extensional value sets, meanwhile, are enumerated lists of codes where each code is listed individually. This gives the author and user of the value set more control over the which codes are in the value set, but there is a greater maintenance burden to ensure that the value set is kept up to date.

Notes

Composition Rules

A value set can be a simple list of included codes, or it can be some kind of general selection criteria using the facilities provided by the code system. For these value sets:

Compose

The rules for the content of the value set are found in the ValueSet.compose element, which are analogous to the Content Logical Definition (CLD) as defined by the VSD Project. The ValueSet compose is a set of instructions for what codes are in the ValueSet, and defined by the author consistent with the ValueSet.description

The ValueSet composition can be defined in a number of ways:

The first approach - listing codes explicitly - is called an 'extensional' definition; all the other ways are called 'intensional' definitions.

Filters

Mapping from VSD to ValueSet.compose

VSD ScenarioFHIR Implementation
When the ValueSet.compose is an expression (ValueSet.expression), declare the type of expression here

| | When the ValueSet.compose describes Concepts to include based on CodeSystem properties |

compose.include.filter.property = "property name"

Either the Value or Expression must be provided

Value:

Expression:

| | When the ValueSet.compose defines the types of relationships between concepts to include in the ValueSet Expansion |

compose.filter.property = "RelationshipType"

(note: filter property is a string in VSD, code in FHIR)

Example:

to find all concepts in SNOMED CT with the SNOMED CT laterality qualifier relationship to the SNOMED CT concept "left":

|

Using Filter Values

The element compose.include.filter.value is a string. The actual format of the value depends on the value of compose.include.filter.op and/or the definitions of the underlying CodeSystem. The following rules apply (in order).

The format of compose.include.filter.value for Code System Properties depends on the property type:

stringUse the string directly
integerUse the integer value directly
booleanUse true or false
dateTimeUse ISO 8601 format, following the precision rules for the dateTime data type
decimalUse the decimal value directly
codeUse the code directly
CodingUse the format system(

For the ordered data types (integer, decimal and dateTime), the search prefixes can be used (eq, ne, gt, lt, ge, le, sa, eb, ap). Note that the Coding syntax is not the search syntax.

Code Systems Note

Each Code System defines which filters can be used in ValueSet.compose.include.filter. All code systems have base filters and any additional filters defined in (CodeSystem.filter).

HL7 Terminology defines filters for various published code systems:

Union and Intersection

ValueSet.compose may reference other ValueSets.

Intersection:

Union:

For expansion guidance, and how to manage exclude, see Value Set Expansion

When a ValueSet definition includes other ValueSets, use the ValueSet.valueset-compose-include-ValueSetTitle extension to provide the human readable name of the included Value Set.

Referencing CodeSystem Fragments

The VSD Partition aligns with FHIR CodeSystem Fragments.

Code System fragments are a unique and identifiable distinct segment of an overall Code System namespace. While most Code Systems are in essence one fragment and, therefore, do not have identifiable fragments, some Code Systems can be made up of a collection of distinct segments. SNOMED CT is an example of such a Code System. The SNOMED CT International Edition is the base fragment and can be used alone, but there are many distinct additional fragments that can be added to the international core to create what is known as a SNOMED CT Edition.

The CodeSystem referenced in a ValueSet.compose may reference a CodeSystem fragment.

ValueSet Alignment with VSD

Author and Publisher

Author, Steward and Publisher are roles associated with a Value Set Definition.

ValueSet Author is the person or organization that creates and may modify the ValueSet. The Steward is the person or organization responsible for the content, maintenance and life cycle of the ValueSet. The Publisher is the person or organization that makes the ValueSet available. The publisher or a terminology server might provide the ValueSet expansions.

In FHIR, ValueSet.publisher satisfies the requirements for both publisher and steward.

Scope and Description

Description and Purpose are standard elements that appear in many FHIR resources. Neither fully supports the intent of the VSD Scope element, however ValueSet.description does support Focus as defined in VSD.

When a ValueSet definition includes other ValueSets, use ValueSet.description to provide information about the included value sets in context of the parent value set.

Purpose may be used for the ValueSet.author to describe why the ValueSet was created. ValueSet.description may be used to provide the ValueSet Focus as described in VSD.

Example:

Value Set NameDescription
Body Site Value SetAll SNOMED CT anatomic structures, locations, abnormal structures that can be considered to describe an anatomical site.
Familial HypercholesterolemiaThis value set contains terms defining familial hypercholesterolemia, regardless of genetic origin.

Name and Title

The VSD element Name aligns with ValueSet.title which does not support preference or language. Use the ValueSet.valueset-otherTitle extension when a language or preference is necessary. ValueSet.title or ValueSet.valueset-otherTitle must be valued.

Include Active Concepts Only

VSD and FHIR support the constraining the $expand operation to return only active concepts as defined by the CodeSystem.

The VSD element ActiveOnly equal to TRUE is equivalent to ValueSet.compose.inactive equal to FALSE.

Status

The ValueSet resource defines a Value Set Definition and a Value Set Expansion. VSD describes only the characteristics of the Value Set Definition.

The VSD element ActivityStatus aligns with ValueSet.status, which is the status of the entire ValueSet resource with the exception of the ValueSet.expansion. This aligns with VSD using the word definition to mean the Content Logical Definition plus all the other non-expansion metadata. A Value Set Expansion is stateless.

Note: ValueSet.status is bound with required binding strength to the PublicationStatus value set. The following table shows how the ActivityStatus values in VSD align with the values in the PublicationStatus Value Set Expansion.

VSD Activity Status ValueFHIR Publication Status Value
PreliminaryDraft
ActiveActive
InactiveRetired
*Unknown
Deleted*

*There is no equivalent value in either VSD or the PublicationStatus Value Set.

Display and Designations

Concepts used in ValueSets can have a display, which is a short text that represents the meaning of the concept to human users in the context of the value set (which often has narrower meaning and therefore is amenable to shorter displays. If a display is not provided, the value set uses the display from the code system (which is the preferred approach, because overriding the display can lead to very unsafe outcomes).

When a value set enumerates codes, it is sometimes useful to define an alternative display for the code that is to be used wherever the value set is expanded and used in a UI. This facility is provided to cover the following circumstances:

Note that care must be taken in order to avoid "changing the meaning" of the concept by implying that it means something other than the explicit definition of the concept in the underlying code system (e.g., in the case above, using a display of "Glucose Concentration at 10pm"). For this reason, some contexts of use do not allow a display to be associated with a specific code in a value set.

Any display name for a concept provided in the value set is for display to a human user. The display in the Coding that results from a user selecting a concept from the expansion must be taken from the underlying code system definition, even if a value set is referenced explicitly in the Coding (e.g. by an extension). The correct display for a code can be determined by a $lookup operation. Any alternative display specified in the value set would go in CodeableConcept.text, perhaps appended to the UI label for the matching data element.

As an example, the LOINC code 55423-8 has a display value of "Number of steps in unspecified time Pedometer". A value set for a pick list in a patient generated data form might choose a simpler name:

{ "resourceType" : "ValueSet", "compose" : { "include" : [{ "system" : "http://loinc.org", "concept" : [{ "code" : "55423-8", "display" : "Step Count" }] }] } }

The expansion generated by a terminology server will have this:

{ "resourceType" : "ValueSet", "expansion" : { "contains" : [{ "system" : "http://loinc.org", "code" : "55423-8", "display" : "Step Count" }] } }

The expansion display is taken from the value set, and this is what is displayed in the pick list. Once the user picks the code, it will appear in the Observation.code like this:

{ "resourceType" : "Observation", "code" : { "coding" : [{ "system" : "http://loinc.org", "code" : "55423-8", "display" : "Number of steps in unspecified time Pedometer" }], "text" : "Step Count" } }

Note that the correct value for the display is not in the expansion above. The client can either omit the display, look it up using $lookup, or the server might pre-populate it in the expansion:

{ "resourceType" : "ValueSet", "expansion" : { "contains" : [{ "system" : "http://loinc.org", "code" : "55423-8", "display" : "Step Count", "designation" : [{ "use" : { "system" : "http://snomed.info/sct", "code" : "900000000000003001" }, "value" : "Number of steps in unspecified time Pedometer" }] }] } }

Irrespective of this, the display in the expansion always goes in CodeableConcept.text.

StructureDefinition

Elements (Simplified)

Mappings

Implementation Guide

implementationguide-ValueSet-core.xml

<?xml version="1.0" encoding="UTF-8"?>

<ImplementationGuide xmlns="http://hl7.org/fhir">
  <id value="ValueSet-core"/>
  <version value="0.01"/>
  <name value="ValueSetCore"/>
  <title value="ValueSet Core"/>
  <status value="draft"/>
  <date value="1970-01-01T10:00:00+10:00"/>
  <publisher value="HL7"/>
  <description value="Core profiles and extensions defined for the ValueSet resource"/>
  <definition>
  </definition>
</ImplementationGuide>

Operations

Full Operations

Resource Packs

list-ValueSet-packs.xml

<?xml version="1.0" encoding="UTF-8"?>

<List xmlns="http://hl7.org/fhir">
  <id value="ValueSet-packs"/>
  <status value="current"/>
  <mode value="working"/>
  <entry>
    <item>
      <reference value="ImplementationGuide/ValueSet-core"/>
    </item>
  </entry>
</List>

Search Parameters

Full Search Parameters

Examples

Full Examples

Mapping Exceptions

valueset-fivews-mapping-exceptions.xml

Unmapped Elements