2nd DSTU Draft For Comment

This page is part of the FHIR Specification (v0.4.0: DSTU 2 Draft). 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

6.23 Resource ValueSet - Content

This resource maintained by the Vocabulary Work Group

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

6.23.1 Scope and Usage

The FHIR terminology specification is based two key concepts, originally defined in HL7 v3 Core Principles:

  • code system - defines a set of codes with meanings (also known as enumeration, terminology, classification, and/or ontology)
  • value set - selects a set of codes from those defined by one or more code systems

Code systems define which codes (symbols and/or expressions) exist, and how they are understood. Value Sets specify which codes can be used in a particular context.

Value sets may be constructed in one of two ways:

  • A value set can define its own codes (e.g. an in-line simple code system definition), and/or
  • A value set can be composed of codes defined in other code systems, either by listing the codes or by providing a set of selection criteria

A value set can also be "expanded", where the value set is turned into a simple collection of enumerated codes. This operation is performed to produce a collection of codes that are ready to use for data entry or validation. An expanded value set may also contain the original definition as well.

Value sets that define their own codes are effectlvely providing inline code system definitions. These are intended for small, simple code systems that are found throughout the implementation context (e.g. lists of wards, status codes, enumerations). The inline code system definition is not intended to represent large publically defined terminologies such as LOINC etc - these have their own distributions formats .

6.23.2 Boundaries and Relationships

  • Value sets are used in Profiles, and Questionnaires to specify the allowable contents for coded elements
  • In addition, a specific Coding can reference the value set it was picked from
  • Concept Maps describe mappings between value sets
  • The ValueSet resource design is based on the functionality described in the OMG CTS 2 specification. Value set resources can be converted to CTS2 value set and code system resources

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

Each value set has 2 different URLs that can be used to reference it, it's logical identifier, and it's location.

The location of the value set is a URL by which it may be retrieved, usually from a FHIR server, and is often a relative reference to a value set on the same server. The logical identifier is in the value set itself, in ValueSet.identifier. This is the logical identity (sometimes called the canonical URL) that refers to this value set across all systems. Ideally, the URL should also be the location of the master version of the value set, though this is not always possible.

For example, the value sets published as part of FHIR all have a logical URL which is also a location by which they may be accessed in the FHIR specification itself. However, 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 FHIR specification.

Because it is common practice to copy (cache) value sets locally, most references to value sets can either be logical or literal URL.

This resource is referenced by ConceptMap, DataElement and Questionnaire

6.23.4 Resource Content

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. ValueSet IDomainResourceA set of codes drawn from one or more code systems
A defined code system (if present) SHALL have a different identifier to the value set itself
Value set SHALL contain either a define, a compose, or an expansion element
A value set with only one import SHALL also have an include and/or an exclude unless the value set defines its own codes
... url Σ0..1uriGlobally unique logical id for value set
... identifier Σ0..1IdentifierAdditional identifier for the value set (v2 / CDA)
... version Σ0..1stringLogical id for this version of the value set
... name Σ0..1stringInformal name for this value set
... immutable 0..1booleanIndicates whether or not any change to the content logical definition may occur
... publisher Σ0..1stringName of the publisher (Organization or individual)
... contact Σ0..*ElementContact details of the publisher
.... name Σ0..1stringName of a individual to contact
.... telecom Σ0..*ContactPointContact details for individual or publisher
... description Σ0..1stringHuman language description of the value set
... requirements 0..1stringWhy is this needed?
... copyright 0..1stringUse and/or Publishing restrictions
... status M Σ1..1codedraft | active | retired
ValueSetStatus (Required)
... experimental Σ0..1booleanIf for testing purposes, not real usage
... extensible 0..1booleanWhether this is intended to be used with an extensible binding
... date Σ0..1dateTimeDate for given status
... stableDate 0..1dateFixed date for the version of all referenced code systems and value sets
... define Σ I0..1ElementWhen value set defines its own codes
Codes must be unique
Within a code system definition, all the codes SHALL be unique
.... system Σ1..1uriURI to identify the code system
.... version Σ0..1stringVersion of this system
.... caseSensitive Σ0..1booleanIf code comparison is case sensitive
.... concept 0..*ElementConcepts in the code system
..... code 1..1codeCode that identifies concept
..... abstract 0..1booleanIf this code is not for use as a real concept
..... display 0..1stringText to Display to the user
..... definition 0..1stringFormal Definition
..... designation 0..*ElementAdditional representations for the concept
...... language 0..1codeLanguage of the designation
Language (Required)
...... use 0..1CodingDetails how this designation would be used
ConceptDesignationUse (Incomplete)
...... value 1..1stringThe text value for this designation
..... concept 0..*see conceptChild Concepts (is-a / contains)
... compose I0..1ElementWhen value set includes codes from elsewhere
A value set composition SHALL have an include or an import
.... import Σ I0..*uriImport the contents of another value set
.... include Σ I0..*ElementInclude one or more codes from a code system
..... system Σ1..1uriThe system the codes come from
..... version Σ0..1stringSpecific version of the code system referred to
..... concept 0..*ElementA concept defined in the system
...... code 1..1codeCode or expression from system
...... display 0..1stringTest to display for this code for this value set
...... designation 0..*see designationAdditional representations for this valueset
..... filter 0..*ElementSelect codes/concepts by their properties (including relationships)
...... property 1..1codeA property defined by the code system
...... op 1..1code= | is-a | is-not-a | regex | in | not-in
FilterOperator (Required)
...... value 1..1codeCode from the system, or regex criteria
.... exclude I0..*see includeExplicitly exclude codes
... expansion I0..1ElementUsed when the value set is "expanded"
.... identifier 0..1IdentifierUniquely identifies this expansion
.... timestamp 1..1dateTimeTime valueset expansion happened
.... contains I0..*ElementCodes in the value set
Must have a code if not abstract
SHALL have a code or a display
Must have a system if a code is present
..... system 0..1uriSystem value for the code
..... abstract 0..1booleanIf user cannot select this entry
..... version 0..1stringVersion in which this code / display is defined
..... code I0..1codeCode - if blank, this is not a choosable code
..... display I0..1stringUser display for the concept
..... contains 0..*see containsCodes contained in this concept

UML Diagram

ValueSet (DomainResource)The uri that is used to identify this value set when it is referenced in a specification, model, design or an instance (should be globally unique URI, and an be urn:uuid: or urn:oid:)url : uri 0..1Formal identifier that is used to identify this value set when it is represented in other formats, or referenced in a specification, model, design or an instanceidentifier : Identifier 0..1The identifier that is used to identify this version of the value set when it is referenced in a specification, model, design or instance. This is an arbitrary value managed by the profile author manually and the value should be a timestampversion : string 0..1A free text natural language name describing the value setname : string 0..1If this is set to 'true', then no new versions of the content logical definition can be created. Note: Other metadata might still changeimmutable : boolean 0..1The name of the individual or organization that published the value setpublisher : string 0..1A free text natural language description of the use of the value set - reason for definition, "the semantic space" to be included in the value set, conditions of use, etc. The description may include a list of expected usages for the value set and can also describe the approach taken to build the value setdescription : string 0..1Explains why this value set is needed and why it's been constrained as it hasrequirements : string 0..1A copyright statement relating to the value set and/or its contents. Copyright statements are generally legal restrictions on the use and publishing of the value setcopyright : string 0..1The status of the value set (this element modifies the meaning of other elements)status : code 1..1 « The lifecycle status of a Value Set or Concept MapValueSetStatus »This valueset was authored for testing purposes (or education/evaluation/marketing), and is not intended to be used for genuine usageexperimental : boolean 0..1Whether this is intended to be used with an extensible binding or notextensible : boolean 0..1The date that the value set status was last changeddate : dateTime 0..1If a Stability Date is expanded by evaluating the Content Logical Definition using the current version of all referenced code system(s) and value sets as of the Stability DatestableDate : date 0..1ContactThe name of an individual to contact regarding the value setname : string 0..1Contact details for individual (if a name was provided) or the publishertelecom : ContactPoint 0..*DefineURI to identify the code systemsystem : uri 1..1The version of this code system that defines the codes. Note that the version is optional because a well maintained code system does not suffer from versioning, and therefore the version does not need to be maintained. However many code systems are not well maintained, and the version needs to be defined and trackedversion : string 0..1If code comparison is case sensitive when codes within this system are compared to each othercaseSensitive : boolean 0..1ConceptDefinitionCode that identifies conceptcode : code 1..1If this code is not for use as a real conceptabstract : boolean 0..1Text to Display to the userdisplay : string 0..1The formal definition of the concept. Formal definitions are not required, because of the prevalence of legacy systems without them, but they are highly recommended, as without them there is no formal meaning associated with the conceptdefinition : string 0..1DesignationThe language this designation is defined forlanguage : code 0..1 « A human languageLanguage »A code that details how this designation would be useduse : Coding 0..1 « Details of how a designation would be usedConceptDesignationUse+ »The text value for this designationvalue : string 1..1ComposeIncludes the contents of the referenced value set as a part of the contents of this value setimport : uri 0..*ConceptSetThe code system from which the selected codes come fromsystem : uri 1..1The version of the code system that the codes are selected fromversion : string 0..1ConceptReferenceSpecifies a code for the concept to be included or excludedcode : code 1..1The text to display to the user for this concept in the context of this valueset. If no display is provided, then applications using the value set use the display specified for the code by the systemdisplay : string 0..1FilterA code that identifies a property defined in the code systemproperty : code 1..1The kind of operation to perform as a part of the filter criteriaop : code 1..1 « The kind of operation to perform as a part of a property based filterFilterOperator »The match value may be either a code defined by the system, or a string value which is used a regex match on the literal string of the property valuevalue : code 1..1ExpansionAn identifier that uniquely identifies this expansion of the valueset. Systems may re-use the same identifier as long as the expansion and the definition remain the same, but are not required to do soidentifier : Identifier 0..1The time at which the expansion was produced by the expanding systemtimestamp : dateTime 1..1ContainsThe system in which the code for this item in the expansion is definedsystem : uri 0..1If true, this entry is included in the expansion for navigational purposes, and the user cannot select the code directly as a proper valueabstract : boolean 0..1The version of this code system that defined this code and/or display. This should only be used with code systems that do not enforce concept permanenceversion : string 0..1Code - if blank, this is not a choosable codecode : code 0..1User display for the conceptdisplay : string 0..1Contacts to assist a user in finding and communicating with the publishercontact0..*Additional representations for the concept - other languages, aliases, specialised purposes, used for particular purposes, etcdesignation0..*Child Concepts (is-a / contains)concept0..*Concepts in the code systemconcept0..*When value set defines its own codesdefine0..1Additional representations for this concept when used in this value set - other languages, aliases, specialised purposes, used for particular purposes, etcdesignation0..*Specifies a concept to be included or excludedconcept0..*Select concepts by specify a matching criteria based on the properties (including relationships) defined by the system. If multiple filters are specified, they SHALL all be truefilter0..*Include one or more codes from a code systeminclude0..*Exclude one or more codes from the value setexclude0..*When value set includes codes from elsewherecompose0..1Codes contained in this conceptcontains0..*The codes that are contained in the value set expansioncontains0..*A value set can also be "expanded", where the value set is turned into a simple collection of enumerated codes. This element holds the expansion, if it has been performedexpansion0..1

XML Template

<ValueSet xmlns="http://hl7.org/fhir"> doco
 <!-- from Resource: id, meta, implicitRules, and language -->
 <!-- from DomainResource: text, contained, extension, and modifierExtension -->
 <url value="[uri]"/><!-- 0..1 Globally unique logical id for  value set -->
 <identifier><!-- 0..1 Identifier Additional identifier for the value set (v2 / CDA) --></identifier>
 <version value="[string]"/><!-- 0..1 Logical id for this version of the value set -->
 <name value="[string]"/><!-- 0..1 Informal name for this value set -->
 <immutable value="[boolean]"/><!-- 0..1 Indicates whether or not any change to the content logical definition may occur -->
 <publisher value="[string]"/><!-- 0..1 Name of the publisher (Organization or individual) -->
 <contact>  <!-- 0..* Contact details of the publisher -->
  <name value="[string]"/><!-- 0..1 Name of a individual to contact -->
  <telecom><!-- 0..* ContactPoint Contact details for individual or publisher --></telecom>
 </contact>
 <description value="[string]"/><!-- 0..1 Human language description of the value set -->
 <requirements value="[string]"/><!-- 0..1 Why is this needed? -->
 <copyright value="[string]"/><!-- 0..1 Use and/or Publishing restrictions -->
 <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 -->
 <stableDate value="[date]"/><!-- 0..1 Fixed date for the version of all referenced code systems and value sets -->
 <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 -->
   <designation>  <!-- 0..* Additional representations for the concept -->
    <language value="[code]"/><!-- 0..1 Language of the designation -->
    <use><!-- 0..1 Coding Details how this designation would be used --></use>
    <value value="[string]"/><!-- 1..1 The text value for this designation -->
   </designation>
   <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 -->
   <concept>  <!-- 0..* A concept defined in the system -->
    <code value="[code]"/><!-- 1..1 Code or expression from system -->
    <display value="[string]"/><!-- 0..1 Test to display for this code for this value set -->
    <designation><!-- 0..* Content as for ValueSet.define.concept.designation Additional representations for this valueset --></designation>
   </concept>
   <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 Used when the value set is "expanded" -->
  <identifier><!-- 0..1 Identifier Uniquely identifies this expansion --></identifier>
  <timestamp value="[dateTime]"/><!-- 1..1 Time valueset expansion happened -->
  <contains>  <!-- 0..* Codes in the value set -->
   <system value="[uri]"/><!-- 0..1 System value for the code -->
   <abstract value="[boolean]"/><!-- 0..1 If user cannot select this entry -->
   <version value="[string]"/><!-- 0..1 Version in which this code / display is defined -->
   <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>

JSON Template

{doco
  "resourceType" : "ValueSet",
  // from Resource: id, meta, implicitRules, and language
  // from DomainResource: text, contained, extension, and modifierExtension
  "url" : "<uri>", // Globally unique logical id for  value set
  "identifier" : { Identifier }, // Additional identifier for the value set (v2 / CDA)
  "version" : "<string>", // Logical id for this version of the value set
  "name" : "<string>", // Informal name for this value set
  "immutable" : <boolean>, // Indicates whether or not any change to the content logical definition may occur
  "publisher" : "<string>", // Name of the publisher (Organization or individual)
  "contact" : [{ // Contact details of the publisher
    "name" : "<string>", // Name of a individual to contact
    "telecom" : [{ ContactPoint }] // Contact details for individual or publisher
  }],
  "description" : "<string>", // Human language description of the value set
  "requirements" : "<string>", // Why is this needed?
  "copyright" : "<string>", // Use and/or Publishing restrictions
  "status" : "<code>", // R! draft | active | retired
  "experimental" : <boolean>, // If for testing purposes, not real usage
  "extensible" : <boolean>, // Whether this is intended to be used with an extensible binding
  "date" : "<dateTime>", // Date for given status
  "stableDate" : "<date>", // Fixed date for the version of all referenced code systems and value sets
  "define" : { // C? When value set defines its own codes
    "system" : "<uri>", // R! URI to identify the code system
    "version" : "<string>", // Version of this system
    "caseSensitive" : <boolean>, // If code comparison is case sensitive
    "concept" : [{ // Concepts in the code system
      "code" : "<code>", // R! Code that identifies concept
      "abstract" : <boolean>, // If this code is not for use as a real concept
      "display" : "<string>", // Text to Display to the user
      "definition" : "<string>", // Formal Definition
      "designation" : [{ // Additional representations for the concept
        "language" : "<code>", // Language of the designation
        "use" : { Coding }, // Details how this designation would be used
        "value" : "<string>" // R! The text value for this designation
      }],
      "concept" : [{ Content as for ValueSet.define.concept }] // Child Concepts (is-a / contains)
    }]
  },
  "compose" : { // C? When value set includes codes from elsewhere
    "import" : ["<uri>"], // C? Import the contents of another value set
    "include" : [{ // C? Include one or more codes from a code system
      "system" : "<uri>", // R! The system the codes come from
      "version" : "<string>", // Specific version of the code system referred to
      "concept" : [{ // A concept defined in the system
        "code" : "<code>", // R! Code or expression from system
        "display" : "<string>", // Test to display for this code for this value set
        "designation" : [{ Content as for ValueSet.define.concept.designation }] // Additional representations for this valueset
      }],
      "filter" : [{ // Select codes/concepts by their properties (including relationships)
        "property" : "<code>", // R! A property defined by the code system
        "op" : "<code>", // R! = | is-a | is-not-a | regex | in | not-in
        "value" : "<code>" // R! Code from the system, or regex criteria
      }]
    }],
    "exclude" : [{ Content as for ValueSet.compose.include }] // C? Explicitly exclude codes
  },
  "expansion" : { // C? Used when the value set is "expanded"
    "identifier" : { Identifier }, // Uniquely identifies this expansion
    "timestamp" : "<dateTime>", // R! Time valueset expansion happened
    "contains" : [{ // Codes in the value set
      "system" : "<uri>", // System value for the code
      "abstract" : <boolean>, // If user cannot select this entry
      "version" : "<string>", // Version in which this code / display is defined
      "code" : "<code>", // C? Code - if blank, this is not a choosable code
      "display" : "<string>", // C? User display for the concept
      "contains" : [{ Content as for ValueSet.expansion.contains }] // Codes contained in this concept
    }]
  }
}

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. ValueSet IDomainResourceA set of codes drawn from one or more code systems
A defined code system (if present) SHALL have a different identifier to the value set itself
Value set SHALL contain either a define, a compose, or an expansion element
A value set with only one import SHALL also have an include and/or an exclude unless the value set defines its own codes
... url Σ0..1uriGlobally unique logical id for value set
... identifier Σ0..1IdentifierAdditional identifier for the value set (v2 / CDA)
... version Σ0..1stringLogical id for this version of the value set
... name Σ0..1stringInformal name for this value set
... immutable 0..1booleanIndicates whether or not any change to the content logical definition may occur
... publisher Σ0..1stringName of the publisher (Organization or individual)
... contact Σ0..*ElementContact details of the publisher
.... name Σ0..1stringName of a individual to contact
.... telecom Σ0..*ContactPointContact details for individual or publisher
... description Σ0..1stringHuman language description of the value set
... requirements 0..1stringWhy is this needed?
... copyright 0..1stringUse and/or Publishing restrictions
... status M Σ1..1codedraft | active | retired
ValueSetStatus (Required)
... experimental Σ0..1booleanIf for testing purposes, not real usage
... extensible 0..1booleanWhether this is intended to be used with an extensible binding
... date Σ0..1dateTimeDate for given status
... stableDate 0..1dateFixed date for the version of all referenced code systems and value sets
... define Σ I0..1ElementWhen value set defines its own codes
Codes must be unique
Within a code system definition, all the codes SHALL be unique
.... system Σ1..1uriURI to identify the code system
.... version Σ0..1stringVersion of this system
.... caseSensitive Σ0..1booleanIf code comparison is case sensitive
.... concept 0..*ElementConcepts in the code system
..... code 1..1codeCode that identifies concept
..... abstract 0..1booleanIf this code is not for use as a real concept
..... display 0..1stringText to Display to the user
..... definition 0..1stringFormal Definition
..... designation 0..*ElementAdditional representations for the concept
...... language 0..1codeLanguage of the designation
Language (Required)
...... use 0..1CodingDetails how this designation would be used
ConceptDesignationUse (Incomplete)
...... value 1..1stringThe text value for this designation
..... concept 0..*see conceptChild Concepts (is-a / contains)
... compose I0..1ElementWhen value set includes codes from elsewhere
A value set composition SHALL have an include or an import
.... import Σ I0..*uriImport the contents of another value set
.... include Σ I0..*ElementInclude one or more codes from a code system
..... system Σ1..1uriThe system the codes come from
..... version Σ0..1stringSpecific version of the code system referred to
..... concept 0..*ElementA concept defined in the system
...... code 1..1codeCode or expression from system
...... display 0..1stringTest to display for this code for this value set
...... designation 0..*see designationAdditional representations for this valueset
..... filter 0..*ElementSelect codes/concepts by their properties (including relationships)
...... property 1..1codeA property defined by the code system
...... op 1..1code= | is-a | is-not-a | regex | in | not-in
FilterOperator (Required)
...... value 1..1codeCode from the system, or regex criteria
.... exclude I0..*see includeExplicitly exclude codes
... expansion I0..1ElementUsed when the value set is "expanded"
.... identifier 0..1IdentifierUniquely identifies this expansion
.... timestamp 1..1dateTimeTime valueset expansion happened
.... contains I0..*ElementCodes in the value set
Must have a code if not abstract
SHALL have a code or a display
Must have a system if a code is present
..... system 0..1uriSystem value for the code
..... abstract 0..1booleanIf user cannot select this entry
..... version 0..1stringVersion in which this code / display is defined
..... code I0..1codeCode - if blank, this is not a choosable code
..... display I0..1stringUser display for the concept
..... contains 0..*see containsCodes contained in this concept

UML Diagram

ValueSet (DomainResource)The uri that is used to identify this value set when it is referenced in a specification, model, design or an instance (should be globally unique URI, and an be urn:uuid: or urn:oid:)url : uri 0..1Formal identifier that is used to identify this value set when it is represented in other formats, or referenced in a specification, model, design or an instanceidentifier : Identifier 0..1The identifier that is used to identify this version of the value set when it is referenced in a specification, model, design or instance. This is an arbitrary value managed by the profile author manually and the value should be a timestampversion : string 0..1A free text natural language name describing the value setname : string 0..1If this is set to 'true', then no new versions of the content logical definition can be created. Note: Other metadata might still changeimmutable : boolean 0..1The name of the individual or organization that published the value setpublisher : string 0..1A free text natural language description of the use of the value set - reason for definition, "the semantic space" to be included in the value set, conditions of use, etc. The description may include a list of expected usages for the value set and can also describe the approach taken to build the value setdescription : string 0..1Explains why this value set is needed and why it's been constrained as it hasrequirements : string 0..1A copyright statement relating to the value set and/or its contents. Copyright statements are generally legal restrictions on the use and publishing of the value setcopyright : string 0..1The status of the value set (this element modifies the meaning of other elements)status : code 1..1 « The lifecycle status of a Value Set or Concept MapValueSetStatus »This valueset was authored for testing purposes (or education/evaluation/marketing), and is not intended to be used for genuine usageexperimental : boolean 0..1Whether this is intended to be used with an extensible binding or notextensible : boolean 0..1The date that the value set status was last changeddate : dateTime 0..1If a Stability Date is expanded by evaluating the Content Logical Definition using the current version of all referenced code system(s) and value sets as of the Stability DatestableDate : date 0..1ContactThe name of an individual to contact regarding the value setname : string 0..1Contact details for individual (if a name was provided) or the publishertelecom : ContactPoint 0..*DefineURI to identify the code systemsystem : uri 1..1The version of this code system that defines the codes. Note that the version is optional because a well maintained code system does not suffer from versioning, and therefore the version does not need to be maintained. However many code systems are not well maintained, and the version needs to be defined and trackedversion : string 0..1If code comparison is case sensitive when codes within this system are compared to each othercaseSensitive : boolean 0..1ConceptDefinitionCode that identifies conceptcode : code 1..1If this code is not for use as a real conceptabstract : boolean 0..1Text to Display to the userdisplay : string 0..1The formal definition of the concept. Formal definitions are not required, because of the prevalence of legacy systems without them, but they are highly recommended, as without them there is no formal meaning associated with the conceptdefinition : string 0..1DesignationThe language this designation is defined forlanguage : code 0..1 « A human languageLanguage »A code that details how this designation would be useduse : Coding 0..1 « Details of how a designation would be usedConceptDesignationUse+ »The text value for this designationvalue : string 1..1ComposeIncludes the contents of the referenced value set as a part of the contents of this value setimport : uri 0..*ConceptSetThe code system from which the selected codes come fromsystem : uri 1..1The version of the code system that the codes are selected fromversion : string 0..1ConceptReferenceSpecifies a code for the concept to be included or excludedcode : code 1..1The text to display to the user for this concept in the context of this valueset. If no display is provided, then applications using the value set use the display specified for the code by the systemdisplay : string 0..1FilterA code that identifies a property defined in the code systemproperty : code 1..1The kind of operation to perform as a part of the filter criteriaop : code 1..1 « The kind of operation to perform as a part of a property based filterFilterOperator »The match value may be either a code defined by the system, or a string value which is used a regex match on the literal string of the property valuevalue : code 1..1ExpansionAn identifier that uniquely identifies this expansion of the valueset. Systems may re-use the same identifier as long as the expansion and the definition remain the same, but are not required to do soidentifier : Identifier 0..1The time at which the expansion was produced by the expanding systemtimestamp : dateTime 1..1ContainsThe system in which the code for this item in the expansion is definedsystem : uri 0..1If true, this entry is included in the expansion for navigational purposes, and the user cannot select the code directly as a proper valueabstract : boolean 0..1The version of this code system that defined this code and/or display. This should only be used with code systems that do not enforce concept permanenceversion : string 0..1Code - if blank, this is not a choosable codecode : code 0..1User display for the conceptdisplay : string 0..1Contacts to assist a user in finding and communicating with the publishercontact0..*Additional representations for the concept - other languages, aliases, specialised purposes, used for particular purposes, etcdesignation0..*Child Concepts (is-a / contains)concept0..*Concepts in the code systemconcept0..*When value set defines its own codesdefine0..1Additional representations for this concept when used in this value set - other languages, aliases, specialised purposes, used for particular purposes, etcdesignation0..*Specifies a concept to be included or excludedconcept0..*Select concepts by specify a matching criteria based on the properties (including relationships) defined by the system. If multiple filters are specified, they SHALL all be truefilter0..*Include one or more codes from a code systeminclude0..*Exclude one or more codes from the value setexclude0..*When value set includes codes from elsewherecompose0..1Codes contained in this conceptcontains0..*The codes that are contained in the value set expansioncontains0..*A value set can also be "expanded", where the value set is turned into a simple collection of enumerated codes. This element holds the expansion, if it has been performedexpansion0..1

XML Template

<ValueSet xmlns="http://hl7.org/fhir"> doco
 <!-- from Resource: id, meta, implicitRules, and language -->
 <!-- from DomainResource: text, contained, extension, and modifierExtension -->
 <url value="[uri]"/><!-- 0..1 Globally unique logical id for  value set -->
 <identifier><!-- 0..1 Identifier Additional identifier for the value set (v2 / CDA) --></identifier>
 <version value="[string]"/><!-- 0..1 Logical id for this version of the value set -->
 <name value="[string]"/><!-- 0..1 Informal name for this value set -->
 <immutable value="[boolean]"/><!-- 0..1 Indicates whether or not any change to the content logical definition may occur -->
 <publisher value="[string]"/><!-- 0..1 Name of the publisher (Organization or individual) -->
 <contact>  <!-- 0..* Contact details of the publisher -->
  <name value="[string]"/><!-- 0..1 Name of a individual to contact -->
  <telecom><!-- 0..* ContactPoint Contact details for individual or publisher --></telecom>
 </contact>
 <description value="[string]"/><!-- 0..1 Human language description of the value set -->
 <requirements value="[string]"/><!-- 0..1 Why is this needed? -->
 <copyright value="[string]"/><!-- 0..1 Use and/or Publishing restrictions -->
 <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 -->
 <stableDate value="[date]"/><!-- 0..1 Fixed date for the version of all referenced code systems and value sets -->
 <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 -->
   <designation>  <!-- 0..* Additional representations for the concept -->
    <language value="[code]"/><!-- 0..1 Language of the designation -->
    <use><!-- 0..1 Coding Details how this designation would be used --></use>
    <value value="[string]"/><!-- 1..1 The text value for this designation -->
   </designation>
   <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 -->
   <concept>  <!-- 0..* A concept defined in the system -->
    <code value="[code]"/><!-- 1..1 Code or expression from system -->
    <display value="[string]"/><!-- 0..1 Test to display for this code for this value set -->
    <designation><!-- 0..* Content as for ValueSet.define.concept.designation Additional representations for this valueset --></designation>
   </concept>
   <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 Used when the value set is "expanded" -->
  <identifier><!-- 0..1 Identifier Uniquely identifies this expansion --></identifier>
  <timestamp value="[dateTime]"/><!-- 1..1 Time valueset expansion happened -->
  <contains>  <!-- 0..* Codes in the value set -->
   <system value="[uri]"/><!-- 0..1 System value for the code -->
   <abstract value="[boolean]"/><!-- 0..1 If user cannot select this entry -->
   <version value="[string]"/><!-- 0..1 Version in which this code / display is defined -->
   <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>

JSON Template

{doco
  "resourceType" : "ValueSet",
  // from Resource: id, meta, implicitRules, and language
  // from DomainResource: text, contained, extension, and modifierExtension
  "url" : "<uri>", // Globally unique logical id for  value set
  "identifier" : { Identifier }, // Additional identifier for the value set (v2 / CDA)
  "version" : "<string>", // Logical id for this version of the value set
  "name" : "<string>", // Informal name for this value set
  "immutable" : <boolean>, // Indicates whether or not any change to the content logical definition may occur
  "publisher" : "<string>", // Name of the publisher (Organization or individual)
  "contact" : [{ // Contact details of the publisher
    "name" : "<string>", // Name of a individual to contact
    "telecom" : [{ ContactPoint }] // Contact details for individual or publisher
  }],
  "description" : "<string>", // Human language description of the value set
  "requirements" : "<string>", // Why is this needed?
  "copyright" : "<string>", // Use and/or Publishing restrictions
  "status" : "<code>", // R! draft | active | retired
  "experimental" : <boolean>, // If for testing purposes, not real usage
  "extensible" : <boolean>, // Whether this is intended to be used with an extensible binding
  "date" : "<dateTime>", // Date for given status
  "stableDate" : "<date>", // Fixed date for the version of all referenced code systems and value sets
  "define" : { // C? When value set defines its own codes
    "system" : "<uri>", // R! URI to identify the code system
    "version" : "<string>", // Version of this system
    "caseSensitive" : <boolean>, // If code comparison is case sensitive
    "concept" : [{ // Concepts in the code system
      "code" : "<code>", // R! Code that identifies concept
      "abstract" : <boolean>, // If this code is not for use as a real concept
      "display" : "<string>", // Text to Display to the user
      "definition" : "<string>", // Formal Definition
      "designation" : [{ // Additional representations for the concept
        "language" : "<code>", // Language of the designation
        "use" : { Coding }, // Details how this designation would be used
        "value" : "<string>" // R! The text value for this designation
      }],
      "concept" : [{ Content as for ValueSet.define.concept }] // Child Concepts (is-a / contains)
    }]
  },
  "compose" : { // C? When value set includes codes from elsewhere
    "import" : ["<uri>"], // C? Import the contents of another value set
    "include" : [{ // C? Include one or more codes from a code system
      "system" : "<uri>", // R! The system the codes come from
      "version" : "<string>", // Specific version of the code system referred to
      "concept" : [{ // A concept defined in the system
        "code" : "<code>", // R! Code or expression from system
        "display" : "<string>", // Test to display for this code for this value set
        "designation" : [{ Content as for ValueSet.define.concept.designation }] // Additional representations for this valueset
      }],
      "filter" : [{ // Select codes/concepts by their properties (including relationships)
        "property" : "<code>", // R! A property defined by the code system
        "op" : "<code>", // R! = | is-a | is-not-a | regex | in | not-in
        "value" : "<code>" // R! Code from the system, or regex criteria
      }]
    }],
    "exclude" : [{ Content as for ValueSet.compose.include }] // C? Explicitly exclude codes
  },
  "expansion" : { // C? Used when the value set is "expanded"
    "identifier" : { Identifier }, // Uniquely identifies this expansion
    "timestamp" : "<dateTime>", // R! Time valueset expansion happened
    "contains" : [{ // Codes in the value set
      "system" : "<uri>", // System value for the code
      "abstract" : <boolean>, // If user cannot select this entry
      "version" : "<string>", // Version in which this code / display is defined
      "code" : "<code>", // C? Code - if blank, this is not a choosable code
      "display" : "<string>", // C? User display for the concept
      "contains" : [{ Content as for ValueSet.expansion.contains }] // Codes contained in this concept
    }]
  }
}

 

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

6.23.4.1 Terminology Bindings

PathDefinitionTypeReference
ValueSet.status The lifecycle status of a Value Set or Concept MapFixedhttp://hl7.org/fhir/valueset-status
ValueSet.define.concept.designation.language A human languageFixedIETF language tag
ValueSet.define.concept.designation.use Details of how a designation would be usedIncompletehttp://hl7.org/fhir/vs/designation-use
ValueSet.compose.include.filter.op The kind of operation to perform as a part of a property based filterFixedhttp://hl7.org/fhir/filter-operator

6.23.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-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)))
  • vsd-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))
  • vsd-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))
  • 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:define/f:system/@value = f:identifier/@value))
  • vsd-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)))
  • 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:display/@value = 'true'))

6.23.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.23.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
  • The set of codes defined SHALL not contain duplicate codes

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

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.23.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
  • 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 unnecssary or innappropriate 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.23.7.1 Code systems Note

How filters are used with various code systems:

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

6.23.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 are 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 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 define 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.

6.23.9 Search Parameters

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

NameTypeDescriptionPaths
codetokenA code defined in the value setValueSet.define.concept.code
datedateThe value set publication dateValueSet.date
descriptionstringText search in the description of the value setValueSet.description
identifiertokenThe identifier for the value setValueSet.identifier
namestringThe name of the value setValueSet.name
publisherstringName of the publisher of the value setValueSet.publisher
referencetokenA code system included or excluded in the value set or an imported value setValueSet.compose.include.system
statustokenThe status of the value setValueSet.status
systemtokenThe system for any codes defined by this value setValueSet.define.system
urltokenThe logical url for the value setValueSet.url
versiontokenThe version identifier of the value setValueSet.version