This page is part of the FHIR Specification (v0.0.82: DSTU 1). 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
• Formal Definitions
• Mappings
• Profiles

6.13 Resource ValueSet - Content

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

6.13.4 Resource Content

This resource is referenced by ConceptMap, Profile and Questionnaire

<ValueSet xmlns="http://hl7.org/fhir"> 
 <!-- from Resource: extension, modifierExtension, language, text, and contained -->
 <identifier value="[string]"/><!-- 0..1 Logical id to reference this value set § -->
 <version value="[string]"/><!-- 0..1 Logical id for this version of the value set § -->
 <name value="[string]"/><!-- 1..1 Informal name for this value set § -->
 <publisher value="[string]"/><!-- 0..1 Name of the publisher (Organization or individual) § -->
 <telecom><!-- 0..* Contact Contact information of the publisher § --></telecom>
 <description value="[string]"/><!-- 1..1 Human language description of the value set § -->
 <copyright value="[string]"/><!-- 0..1 About the value set or its content -->
 <status value="[code]"/><!-- 1..1 draft | active | retired § -->
 <experimental value="[boolean]"/><!-- 0..1 If for testing purposes, not real usage § -->
 <extensible value="[boolean]"/><!-- 0..1 Whether this is intended to be used with an extensible binding -->
 <date value="[dateTime]"/><!-- 0..1 Date for given status § -->
 <define>  <!--  0..1 When value set defines its own codes § -->
  <system value="[uri]"/><!-- 1..1 URI to identify the code system § -->
  <version value="[string]"/><!-- 0..1 Version of this system § -->
  <caseSensitive value="[boolean]"/><!-- 0..1 If code comparison is case sensitive § -->
  <concept>  <!-- 0..* Concepts in the code system -->
   <code value="[code]"/><!-- 1..1 Code that identifies concept -->
   <abstract value="[boolean]"/><!-- 0..1 If this code is not for use as a real concept -->
   <display value="[string]"/><!-- 0..1 Text to Display to the user -->
   <definition value="[string]"/><!-- 0..1 Formal Definition -->
   <concept><!-- 0..* Content as for ValueSet.define.concept Child Concepts (is-a / contains) --></concept>
  </concept>
 </define>
 <compose>  <!--  0..1 When value set includes codes from elsewhere -->
  <import value="[uri]"/><!--  0..* Import the contents of another value set § -->
  <include>  <!--  0..* Include one or more codes from a code system § -->
   <system value="[uri]"/><!-- 1..1 The system the codes come from § -->
   <version value="[string]"/><!-- 0..1 Specific version of the code system referred to § -->
   <code value="[code]"/><!-- 0..* Code or concept from system -->
   <filter>  <!-- 0..* Select codes/concepts by their properties (including relationships) -->
    <property value="[code]"/><!-- 1..1 A property defined by the code system -->
    <op value="[code]"/><!-- 1..1 = | is-a | is-not-a | regex | in | not in -->
    <value value="[code]"/><!-- 1..1 Code from the system, or regex criteria -->
   </filter>
  </include>
  <exclude><!--  0..* Content as for ValueSet.compose.include Explicitly exclude codes --></exclude>
 </compose>
 <expansion>  <!--  0..1 When value set is an expansion -->
  <identifier><!-- 0..1 Identifier Uniquely identifies this expansion --></identifier>
  <timestamp value="[instant]"/><!-- 1..1 Time valueset expansion happened -->
  <contains>  <!-- 0..* Codes in the value set -->
   <system value="[uri]"/><!-- 0..1 System value for the code -->
   <code value="[code]"/><!--  0..1 Code - if blank, this is not a choosable code -->
   <display value="[string]"/><!--  0..1 User display for the concept -->
   <contains><!-- 0..* Content as for ValueSet.expansion.contains Codes contained in this concept --></contains>
  </contains>
 </expansion>
</ValueSet>

Alternate definitions: Schema/Schematron, Resource Profile

6.13.4.1 Terminology Bindings

6.13.4.2 Constraints

• Inv-2: A value set with only one import SHALL also have an include and/or an exclude unless the value set defines its own codes (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:define)))
• Inv-5: Value set SHALL contain either a define, a compose, or an expansion element (xpath: exists(f:define) or exists(f:compose) or exists(f:expansion))
• Inv-7: A defined code system (if present) SHALL have a different identifier to the value set itself (xpath: not(exists(f:define)) or (f:define/f:system/@value != f:identifier/@value))
• Inv-3: On ValueSet.define: Within a code system definition, all the codes SHALL be unique (xpath on f:ValueSet/f:define: count(distinct-values(descendant::f:concept/f:code/@value))=count(descendant::f:concept))
• Inv-8: On ValueSet.define: Codes must be unique (xpath on f:ValueSet/f:define: count(descendant::f:concept)=count(distinct-values(descendant::f:concept/f:code/@value)))
• Inv-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))
• Inv-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))

6.13.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.13.6 Value Sets that define codes

Valuesets can define their own codes. A value set that defines codes automatically includes all the codes it defines, and 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.define.system). These identifiers SHALL be different.

• ValueSet.define.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
• If concepts contain other concepts, then the contained concepts are "subsumed" by the containing concept (there is an "is-a" relationship between the codes).
• An abstract concept SHALL have contained concepts

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

6.13.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, LOINC has re-defined the meaning of codes in the past, but there is only one identifier for LOINC.

For this reason, a code system MAY provide a version identifer in ValueSet.define.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.

6.13.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.
• The value set always includes any codes it defines itself. A typical use for this 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
• 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

6.13.7.1 Code systems Note

How filters are used with various code systems:

6.13.8 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 children of a code 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 (define 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 is heirarchical (codes contain other concepts), there is no implication about the logical relationship between them; this is guidance for helping human user navigate the choice of codes that may or may not relate to the logical definitions of the codes or concepts.

In general, the following process should be followed when expanding a value set:

• for each compose.import, find the referenced value set, expand that, and add it to the result set
• for each compose.include, identify the correct version of the code system, and then:
  • if there is no codes or filters, add every code in the code system to the result set
  • if codes are listed, add them to the result set
  • 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 define 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 codes. 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.

An application MAY offer to expand value sets for other applications. In this case, the standard way to produce a value set expansion is to perform a query on the value set with _query=expand:

  GET [service-url]/ValueSet/?_query=expand&id=:valueSet&...

This is a request to produce a value set expansion for the value set with the provided id which is either a logical id, or an absolute reference to a value set. The value set can be identified by other means, such as identifier and version. Servers can define their own additional parameters that influence the expansion process, such in relation to order and hierarchy.

The value set expansion returned by this query should be treated as a transient result that will change over time (whether it does or not depends on how the value set is specified), so applications should repeat the query each time the value set is used.

6.13.9 Value Set Validation

An application may offer to provide code validation services for other applications. In this case, the standard way for an application to ask for validation is to perform a query on the value set with _query=validate:

  GET [service-url]/ValueSet/?_query=validate&id=:valueSet&system=:system&version=:version&code=:code&...

The values for system, version, and code are those from the Coding data type. Version is optional, and code and system are mandatory. Additionally, the parameter "coding" or "codeableconcept" can be used - the value of these parameters is a URL encoded XML or JSON representation of the two data types respectively. An additional boolean parameter "extensible" can be provided to specify whether the applicable binding is extensible or not.

The result of this query is an Operation Outcome. If there are no errors in the outcome (OperationOutcome.issue.severity), then the code is considered to be valid.

6.13.10 Search Parameters

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