This page is part of the FHIR Specification (v1.0.0: DSTU 2 Ballot 3). The current version which supercedes this version is 5.0.0. For a full list of available versions, see the Directory of published versions . Page versions: R5 R4B R4 R3 R2

• Content
• Examples
• Detailed Descriptions
• Mappings
• Profiles
• Operations

6.21 Resource ValueSet - Content

Vocabulary Work Group

Maturity Level: 4

Compartments: Not linked to any defined compartments

A value set specifies a set of codes drawn from one or more code systems.

This resource is referenced by ConceptMap, OperationDefinition and Questionnaire

6.21.4 Resource Content

 

Alternate definitions: Schema/Schematron, Resource Profile (XML, JSON), Questionnaire

6.21.4.1 Terminology Bindings

Path	Definition	Type	Reference
ValueSet.status	The lifecycle status of a Value Set or Concept Map	Required	ConformanceResourceStatus
ValueSet.useContext	Indicates the countries, regions, disciplines and other aspects of use this artifact is targeted for use within	Extensible	Context of Use ValueSet
ValueSet.codeSystem.concept.designation.language	A human language	Required	IETF language tag
ValueSet.codeSystem.concept.designation.use	Details of how a designation would be used	Extensible	Designation Use
ValueSet.compose.include.filter.op	The kind of operation to perform as a part of a property based filter	Required	FilterOperator

6.21.4.2 Constraints

• vsd-1: On ValueSet.compose: A value set composition SHALL have an include or an import (xpath on f:ValueSet/f:compose: exists(f:include) or exists(f:import))
• vsd-10: On ValueSet.expansion.contains: Must have a system if a code is present (xpath on f:ValueSet/f:expansion/f:contains: exists(f:system) or not(exists(f:code)))
• vsd-11: On ValueSet.compose.include: Cannot have both concept and filter (xpath on f:ValueSet/f:compose/f:include: not(exists(f:concept)) or not(exists(f:filter)))
• vsd-2: A value set with only one import SHALL also have an include and/or an exclude unless the value set includes and inline code system (xpath: not(exists(f:compose)) or (count(f:compose/f:import)!=1 or exists(f:compose/f:include) or exists(f:compose/f:exclude) or exists(f:codeSystem)))
• vsd-3: On ValueSet.codeSystem: Within a code system definition, all the codes SHALL be unique (xpath on f:ValueSet/f:codeSystem: count(distinct-values(descendant::f:concept/f:code/@value))=count(descendant::f:concept))
• vsd-5: Value set SHALL contain at least one of a codeSystem, a compose, or an expansion element (xpath: exists(f:codeSystem) or exists(f:compose) or exists(f:expansion))
• vsd-6: On ValueSet.expansion.contains: SHALL have a code or a display (xpath on f:ValueSet/f:expansion/f:contains: exists(f:code) or exists(f:display))
• vsd-7: A defined code system (if present) SHALL have a different identifier to the value set itself (xpath: not(f:codeSystem/f:system/@value = f:identifier/@value))
• vsd-8: On ValueSet.codeSystem: Codes must be unique (xpath on f:ValueSet/f:codeSystem: count(descendant::f:concept)=count(distinct-values(descendant::f:concept/f:code/@value)))
• vsd-9: On ValueSet.expansion.contains: Must have a code if not abstract (xpath on f:ValueSet/f:expansion/f:contains: exists(f:code) or (f:abstract/@value = 'true'))

6.21.5 Identifier and Version

The identifier and version elements may be used to reference this value set in a design, a profile, a CDA template or V3 message (valueSet and valueSetVersion). These different contexts may make additional restrictions on the possible values of these elements. These elements are generally not needed when using value sets with FHIR implementations as they can make use of the innate identifier and versioning mechanism associated with the resource

6.21.6 Value Sets with In-line Code Systems

A value set that contains an inline code system automatically includes all the codes in that the code system defines. This is useful for simple sets of codes that are highly specific and context-dependent. The value set and the code system are both given URI identifiers by which they may be identified from elsewhere (ValueSet.identifier and ValueSet.codeSystem.system). These identifiers SHALL be different.

• ValueSet.codeSystem.system is the URI that identifies these codes when used in a Coding
• The usability of the codes is closely linked to the quality of the definitions. Although a definition is not required for each concept, a good definition SHOULD be provided. In the absence of any definition, there is no formal meaning associated with the concept
• This specification does not fix the meaning of the relationship between parent and child codes, Most code systems use a subsumption based approach, but other kinds of relationships are possible, including partitive and categorization relationships. The definitions of the concepts dictate the nature of the relationship
• An abstract concept SHALL have contained concepts
• The code system SHALL NOT contain duplicate codes

Note: Value sets only contain inline code systems when they are not defined elsewhere, such as in SNOMED CT, LOINC, RxNorm etc which have their own public distributions. To specify a value set that is made up of codes from other code systems, see "compose" below.

6.21.6.1 Versioning Code Systems

Most code systems evolve over time, due to corrections, clarifications, and changes to approach or underlying knowledge or reality. If these changes lead to the meanings of existing codes changing significantly, then the interpretation of the code system becomes version dependent. This significantly complicates implementation based on the code system, to the point where it is not clear that safety can be assured, so SHOULD be avoided whenever possible. It is preferable to assign a new identifier to a code system when any concepts in it have a significant change in meaning (for example, the German diagnostic classification code system ICD10GM2009 has a different system to ICD10GM2008), but this also can have substantial impact on implementation, so is often not practical - for instance, SNOMED CT has a complex version release framework, which may lead to variations in meaning of concepts, but there is only one identifier for LOINC.

For this reason, a code system MAY provide a version identifer in ValueSet.codeSystem.version. The version specific identifier SHOULD be provided whenever there are potentially significant changes in meaning across multiple releases of a code system. There is no particular format requirement for the version identifier, though HL7 recommends a date based approach.

When the value set definition of a code system includes a version identifier, the version identifier SHOULD be used in Coding instances that refer to the code system.

Where the terminology does not clearly define what string should be used to identify code system versions, the recommendation is to use the date (expressed in FHIR date format) on which that version was officially published as the version date.

6.21.7 Value Sets that include codes defined elsewhere

Value sets that include codes defined in some other code system are most useful when dealing with large general code systems such as SNOMED CT, LOINC, RxNorm or various IETF code sets including human language. The 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.

• Within an include or exclude criterion, multiple filters and concept selections are intersected. All the conditions specified SHALL be true.
• An include statement consists of any enumerated codes and any codes that meet the filter criteria
• If the system reference is not version specific and filters are present, then the contents of the value set are open and change over time as the underlying code systems are updated
• The content of the value set is constructed by unioning of all the import and include statements and then eliminating any of the 'excluded' codes.
• A value set needs to do something. It can't simply include an existing value set without also including additional content or excluding content
• Using the property filters is only possible where the underlying code system defines appropriate properties. Note that in some cases, the underlying code system defines the logical concepts but not the syntax for exercising them. In such cases, the literal definitions may be provided by a third party. See below for notes about its use against common code systems
• Value sets may include abstract codes - that is, codes designated by the underlying code system as not for use as a real concept. These abstract codes are typically used as a grouping/searching mechanism, and can be included either by enumerating them, or by using a filter

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

• The system that defines the code or expression doesn't provide a display for this code (or any codes)
• The system that defines the code or expression defines multiple choices for display
• The system provides a very long display name that is unnecessary or inappropriate in the context of this value set (e.g. a display name of "Glucose [Mass/volume] in Serum or Plasma --10 PM specimen" for LOINC code 48991-4, when the value set only includes Glucose mass/vol in serum/plasma codes). As the display names get longer, this becomes more important

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 system (e.g. in the case above, using a display "Glucose Concentration at 10pm"). For this reason, some contexts of use do not allow a display to be associated with a specific code.

The display name for the code in the value set is only used in the UI. The display in a a Coding must be taken from the underlying system, even if a value set is referenced explicitly in the Coding. The alternative display specified in the value set would go in CodeableConcept.text.

6.21.8 Value Sets with multiple code systems

Value sets may select codes from multiple code systems - either by including codes from different systems, importing to other value sets that do, and/or containing their own code system.

Note that a value set always includes any codes in an inline code system, even if it also has a compose. A typical use for containing both a compose statement and an inline code system is when including a set of codes from elsewhere, and adding a few additional codes to cover cases not catered to by the included codes.

Best Practice Note: mixing definitional systems offers the potential for confusing, overlapping, and inconsistent definitions. Creating value sets that cross code systems should be done with care to avoid creating definitional confusion.

6.21.8.1 Code systems Note

How filters are used with various code systems:

• Using LOINC with FHIR
• Using SNOMED CT with FHIR
• Using RxNorm with FHIR
• Using UCUM with FHIR
• Using NCI Metathesaurus with FHIR
• Using CPT with FHIR
• Using NDF-RT with FHIR
• Using UNII with FHIR
• Using NDC with FHIR
• Using CVX with FHIR

System	Property Name	Operation	Value	Definition	Example
V3 Code systems	concept	is-a	[code]	Includes all codes that have a transitive is-a relationship with the concept identified by the value	Relationship Type
V2 Tables				(no filters defined)

6.21.9 Value Set Expansion

A value set can be "expanded", where the definition of the value set is used to create a simple collection of codes suitable for use for data entry or validation. This is most useful when a value set includes all the codes in a code system, or a set of codes by filter.

A resource that represents a value set expansion includes the same identification details as the definition of the value set, and MAY include the definition of the value set (codeSystem and compose elements). In addition it has a expansion element which contains the list of codes that constitute the value set expansion. If the expansion has nested contains elements, there is no implication about the logical relationship between them, and the structure cannot be used for logical inferencing. The structure exists to provide navigational assistance for helping human users to locate codes in the expansion.

When a request for an expansion is received (e.g. for the $expand operation, the following process should be followed:

• If the value set already has an expansion (e.g. a stored expansion), simply take the existing expansion as it is. If not, then:
• for each compose.import, find the referenced value set by ValueSet.url, expand that (e.g. using the $expand operation: GET [base]/ValueSet/$expand$identifier=[compose.import]), and add it to the result set. This means that expansion across imports is a recursive process
• for each compose.include, identify the correct version of the code system, and then:
  • if there are no codes or filters, add every code in the code system to the result set
  • if codes are listed, check that they are valid, and check their active status, and if ok, add them to the result set (the profile parameter to the $expand operation may be used to control whether active codes are included)
  • if any filters are present, process them in order (as explained above), and add the intersection of their results to the result set
• for each compose.exclude, follow the same process as for compose.include, but remove any codes from the result set, instead of adding them
• add any codes in the codeSystem to the result set

The "result set" is then represented in expansion. Note that the expansion structure is inherently ordered, and also provides support for a hierarchical tree of items. This specification does not fix the meaning of use of either of these, and the conceptual approach described should not be understood to prohibit any implementation approach in these regards. There is a defined operation to ask a server to perform this expansion.

An expansion may include entries in the expansion that only serve an arbitrary grouping purpose, to make it easier for a human to use the list. These entries have no system or code, and must be marked as abstract. Note that the value set codeSystem and compose offer no support for defining these, but this does not exclude servers from using extensions or other knowledge to introduce such groups as an implementation feature.

The codes in the expansion should be treated as case sensitive - implementers should use the correct case. Implementers can consult the definition of the code system to determine whether the code system that defines the code is case sensitive or not.

Whether to store expanded value sets, or simply to store their definitions, and expand on the fly is a matter for system deployment. Some servers, including public value sets servers, only store expansions. However any system that stores an expansion must be concerned with how to determine whether the expansion is still current, and this requires deep knowledge of how the expansion was created. A system with a dedicated terminology server that returns expansions on demand avoids this problem, but leaves open the question of how to audit the specific expansion that was used for a particular case. One solution to this is to use a dedicated terminology server, and have the clients ask for expansions on demand based on the value set definitions, and for the server to store (and reuse as appropriate) the returned expansion (when it reuses the expansion, ValueSet.expansion.identifier will be the same).

6.21.9.1 Code systems with detailed metadata

Sometimes code systems may be used to represent more complex information than just code, display name and code system. For example, a code system of drug information which contains information about the content of the medication (e.g. RxNorm), or a set of observation types, that contain methods, units, etc (e.g. LOINC). In FHIR, these are handled by splitting the concept into two distinct parts - the ValueSet resource is used to manage the codes, display names and relationships. A separate "detail" resource (e.g. Medication for drugs, DataElement for observation types, Location for location, etc.) is used to convey detailed information (dose form & strength, allowed data type or permitted values, address & hours of operation, etc.) One "detail" resource instance is created for each code.

This division accomplishes several things:

• It allows generic systems that support terminology management to perform standard terminology operations on code systems dealing with complex structures - code lookup, validation, subsumption testing, mapping and translation.
• It allows information to be exchanged about individual medications, data elements and locations. Codes can't be retrieved individually in FHIR - it is necessary to retrieve the entire resource. By packaging the detailed information in separate resources, independent retrieval and update is possible.
• It supports use-cases for sharing medication, location, observation type and similar information in circumstances where the code may be unknown, unavailable or occasionally non-existent (e.g. custom compounds, non-registered locations). Having a distinct resource supports these capabilties which would not be possible using ValueSet.

Note that this division in FHIR does not imply that a similar division is required in the internal representation used by systems exposing a FHIR interface. Similarly, some systems may choose to only expose or maintain one aspect of such information types (i.e. only the discrete resource instances or only the value set.)

The linkage between the "detail" resource and the ValueSet is accomplished via the code element (or equivalent) on the detail resource. As well, the "name" or "title" on the detail resource generally corresponds with the display name on the matching code. Most detail resources will also have an "identifier" element. This can be set to the same value and namespace as the code, but if the only identifier a resource has is its defining code, it may be better to omit the identifier entirely.

6.21.10 Search Parameters

Search parameters for this resource. The common parameters also apply. See Searching for more information about searching in REST, messaging, and services.

Name	Type	Description	Paths
code	token	A code defined in the value set	ValueSet.codeSystem.concept.code
context	token	A use context assigned to the value set	ValueSet.useContext
date	date	The value set publication date	ValueSet.date
description	string	Text search in the description of the value set	ValueSet.description
expansion	uri	Uniquely identifies this expansion	ValueSet.expansion.identifier
identifier	token	The identifier for the value set	ValueSet.identifier
name	string	The name of the value set	ValueSet.name
publisher	string	Name of the publisher of the value set	ValueSet.publisher
reference	uri	A code system included or excluded in the value set or an imported value set	ValueSet.compose.include.system
status	token	The status of the value set	ValueSet.status
system	uri	The system for any codes defined by this value set	ValueSet.codeSystem.system
url	uri	The logical url for the value set	ValueSet.url
version	token	The version identifier of the value set	ValueSet.version