DSTU2

This page is part of the FHIR Specification (v0.0.82: (v1.0.2: DSTU 1). 2). 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.13 6.21 Resource ValueSet - Content

Vocabulary Work Group Maturity Level : 3 Compartments : Not linked to any defined compartments

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

6.13.1 6.21.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 select a set of codes from one or more code systems to specify which codes can be used in a particular context.

Value sets may be constructed in one of two ways:

  • A value set can contain an in-line define its own codes, codeSystem , 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.

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

6.13.2 6.21.2 Boundaries and Relationships

  • Value sets are used in Profiles , StructureDefinition and Questionnaires Questionnaire resources 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
    • 6.13.3 Background and Context
  • The ValueSet resource design is based on the fundamental definitions found in the HL7 v3 Core Principles document and the functionality described in the OMG CTS 2 specification, along with metadata in the HL7 Value Set Definition specification. Value set resources can be converted to CTS2 value set and code system resources.
  • The value set resource is aligned with the Value Set Definition (VSD) project. Not all of the elements defined by the VSD are part of the base resource - some are defined as part of the ValueSet Extensions . In the ValueSet resource, the lockedDate , compose and codeSystem elements make up the VSD Content Logical definition.

6.13.4 6.21.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 - its logical identifier, and its 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.url . 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 be either a logical or a literal URL.

6.21.3.1 ValueSet Identification

A value set has 3 identifiers:

  • ValueSet.id: the local identifier on the system that holds it - this changes as it moves from server to server (this id, with the server address prepended, is called the 'literal identity' of the resource)
  • ValueSet.url: the master identifier that never changes for this value set - it is the same in every copy (this is called the 'logical identity' of the resource)
  • ValueSet.identifier: A system/value pair that is used to identify the value set in other contexts (such as an OID in an HL7 v3 specification)

For further information, see Resource Identity .

This resource is referenced by ConceptMap , OperationDefinition and Questionnaire

6.21.4 Resource Content

Structure

Name Flags Card. Type Description & Constraints doco
.. ValueSet I DomainResource A set of codes drawn from one or more code systems
A defined code system (if present) SHALL have a different url than the value set url
Value set SHALL contain at least one of a codeSystem, 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 includes and inline code system
... url Σ 0..1 uri Globally unique logical identifier for value set
... identifier Σ 0..1 Identifier Additional identifier for the value set (e.g. HL7 v2 / CDA)
... version Σ 0..1 string Logical identifier for this version of the value set
... name Σ 0..1 string Informal name for this value set
... status ?! Σ 1..1 code draft | active | retired
ConformanceResourceStatus ( Required )
... experimental Σ 0..1 boolean If for testing purposes, not real usage
... publisher Σ 0..1 string Name of the publisher (organization or individual)
... contact Σ 0..* BackboneElement Contact details of the publisher
.... name Σ 0..1 string Name of an individual to contact
.... telecom Σ 0..* ContactPoint Contact details for individual or publisher
... date Σ 0..1 dateTime Date for given status
... lockedDate Σ 0..1 date Fixed date for all referenced code systems and value sets
... description Σ 0..1 string Human language description of the value set
... useContext Σ 0..* CodeableConcept Content intends to support these contexts
Context of Use ValueSet ( Extensible )
... immutable Σ 0..1 boolean Indicates whether or not any change to the content logical definition may occur
... requirements 0..1 string Why needed
... copyright 0..1 string Use and/or publishing restrictions
... extensible Σ 0..1 boolean Whether this is intended to be used with an extensible binding
... codeSystem Σ I 0..1 BackboneElement An inline code system, which is part of this value set
Codes must be unique
Within a code system definition, all the codes SHALL be unique
.... system Σ 1..1 uri URI to identify the code system (e.g. in Coding.system)
.... version Σ 0..1 string Version (for use in Coding.version)
.... caseSensitive Σ 0..1 boolean If code comparison is case sensitive
.... concept 1..* BackboneElement Concepts in the code system
..... code 1..1 code Code that identifies concept
..... abstract 0..1 boolean If this code is not for use as a real concept
..... display 0..1 string Text to display to the user
..... definition 0..1 string Formal definition
..... designation 0..* BackboneElement Additional representations for the concept
...... language 0..1 code Human language of the designation
Language ( Required )
...... use 0..1 Coding Details how this designation would be used
Designation Use ( Extensible )
...... value 1..1 string The text value for this designation
..... concept 0..* see concept Child Concepts (is-a/contains/categorizes)
... compose I 0..1 BackboneElement When value set includes codes from elsewhere
A value set composition SHALL have an include or an import
.... import Σ I 0..* uri Import the contents of another value set
.... include Σ I 0..* BackboneElement Include one or more codes from a code system
Cannot have both concept and filter
..... system Σ 1..1 uri The system the codes come from
..... version Σ 0..1 string Specific version of the code system referred to
..... concept I 0..* BackboneElement A concept defined in the system
...... code 1..1 code Code or expression from system
...... display 0..1 string Test to display for this code for this value set
...... designation 0..* see designation Additional representations for this valueset
..... filter I 0..* BackboneElement Select codes/concepts by their properties (including relationships)
...... property 1..1 code A property defined by the code system
...... op 1..1 code = | is-a | is-not-a | regex | in | not-in
FilterOperator ( Required )
...... value 1..1 code Code from the system, or regex criteria
.... exclude I 0..* see include Explicitly exclude codes
... expansion I 0..1 BackboneElement Used when the value set is "expanded"
.... identifier 1..1 uri Uniquely identifies this expansion
.... timestamp 1..1 dateTime Time ValueSet expansion happened
.... total 0..1 integer Total number of codes in the expansion
.... offset 0..1 integer Offset at which this resource starts
.... parameter 0..* BackboneElement Parameter that controlled the expansion process
..... name 1..1 string Name as assigned by the server
..... value[x] 0..1 Value of the named parameter
...... valueString string
...... valueBoolean boolean
...... valueInteger integer
...... valueDecimal decimal
...... valueUri uri
...... valueCode code
.... contains I 0..* BackboneElement Codes 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..1 uri System value for the code
..... abstract 0..1 boolean If user cannot select this entry
..... version 0..1 string Version in which this code/display is defined
..... code I 0..1 code Code - if blank, this is not a selectable code
..... display I 0..1 string User display for the concept
..... contains 0..* see contains Codes contained under this entry

doco Documentation for this format

UML Diagram

ValueSet ( Resource DomainResource ) The identifier An absolute URL that is used to identify this value set when it is referenced in a specification, model, design or an instance (should instance. This SHALL be a URL, SHOULD be globally unique OID, UUID, or URI) unique, and SHOULD be an address at which this value set is (or will be) published identifier url : string uri 0..1 [0..1] The Formal 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 instance identifier : Identifier [0..1] 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 timestamp version : string 0..1 [0..1] A free text natural language name describing the value set name : string 1..1 [0..1] The 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 Map. (Strength=Required) ConformanceResourceStatus ! » This valueset was authored for testing purposes (or education/evaluation/marketing), and is not intended to be used for genuine usage experimental : boolean [0..1] The name of the individual or organization that published the value set publisher : string 0..1 [0..1] Contacts The date that the value set status was last changed. The date must change when the business version changes, if it does, and it must change if the status code changes. In addition, it should change when the substantive content of the publisher to assist implementation guide changes (e.g. the 'content logical definition') date : dateTime [0..1] If a user in finding locked date is defined, then the Content Logical Definition must be evaluated using the current version of all referenced code system(s) and communicating with value set instances as of the publisher locked date telecom lockedDate : Contact date 0..* [0..1] A 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 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 set description : string 1..1 [0..1] The content was developed with a focus and intent of supporting the contexts that are listed. These terms may be used to assist with indexing and searching of value set definitions useContext : CodeableConcept [0..*] « Indicates the countries, regions, disciplines and other aspects of use within which this artifact is targeted for use. (Strength=Extensible) Context of Use ValueSet + » If this is set to 'true', then no new versions of the content logical definition can be created. Note: Other metadata might still change immutable : boolean [0..1] Explains why this value set is needed and why it has been constrained as it has requirements : string [0..1] A copyright statement relating to the value set and/or its contents contents. Copyright statements are generally legal restrictions on the use and publishing of the value set copyright : string [0..1] Whether this is intended to be used with an extensible binding or not extensible : boolean [0..1] Contact The name of an individual to contact regarding the value set name : string [0..1] Contact details for individual (if a name was provided) or the publisher telecom : ContactPoint [0..*] CodeSystem An absolute URI that is used to reference this code system, including in [Coding]{datatypes.html#Coding}.system system : uri [1..1] The 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 tracked version : string [0..1] If code comparison is case sensitive when codes within this system are compared to each other caseSensitive : boolean [0..1] ConceptDefinition A code - a text symbol - that uniquely identifies the concept within the code system code : code [1..1] If this code is not for use as a real concept abstract : boolean [0..1] A human readable string that is the recommended default way to present this concept to a user display : string [0..1] The formal definition of the concept. The value set resource does not make formal definitions required, because of the prevalence of legacy systems. However, they are highly recommended, as without them there is no formal meaning associated with the concept definition : string [0..1] Designation The language this designation is defined for language : code [0..1] « A human language. (Strength=Required) Language ! » A code that details how this designation would be used use : Coding [0..1] « Details of how a designation would be used. (Strength=Extensible) Designation Use + » The text value for this designation value : string [1..1] Compose Includes the contents of the referenced value set as a part of the contents of this value set. This is an absolute URI that is a reference to ValueSet.uri import : uri [0..*] ConceptSet An absolute URI which is the code system from which the selected codes come from system : uri [1..1] The version of the code system that the codes are selected from version : string [0..1] ConceptReference Specifies a code for the concept to be included or excluded code : code [1..1] The 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 system display : string [0..1] Filter A code that identifies a property defined in the code system property : code [1..1] The kind of operation to perform as a part of the filter criteria op : code [1..1] « The kind of operation to perform as a part of a property based filter. (Strength=Required) FilterOperator ! » The match value may be either a code defined by the system, or a string value, which is a regex match on the literal string of the property value value : code [1..1] Expansion An 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 so identifier : uri [1..1] The time at which the expansion was produced by the expanding system timestamp : dateTime [1..1] The total number of concepts in the expansion. If the number of concept nodes in this resource is less than the stated number, then the server can return more using the offset parameter total : integer [0..1] If paging is being used, the offset at which this resource starts. I.e. this resource is a partial view into the expansion. If paging is not being used, this element SHALL not be present offset : integer [0..1] Parameter The name of the parameter name : string [1..1] The value of the parameter value[x] : Type [0..1] « string | boolean | integer | decimal | uri | code » Contains An absolute URI which is the code system in which the code for this item in the expansion is defined system : uri [0..1] If true, this entry is included in the expansion for navigational purposes, and the user cannot select the code directly as a proper value abstract : boolean [0..1] The 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 permanence version : string [0..1] The code for this item in the expansion hierarchy. If this code is missing the entry in the hierarchy is a place holder (abstract) and does not represent a valid code in the value set code : code [0..1] The recommended display for this item in the expansion display : string [0..1] Contacts to assist a user in finding and communicating with the publisher contact [0..*] Additional representations for the concept - other languages, aliases, specialized purposes, used for particular purposes, etc designation [0..*] Defines children of a concept to produce a hierarchy of concepts. The nature of the relationships is variable (is-a/contains/categorizes) and can only be determined by examining the definitions of the concepts concept [0..*] Concepts that are in the code system. The concept definitions are inherently hierarchical, but the definitions must be consulted to determine what the meaning of the hierarchical relationships are concept [1..*] A definition of a code system, inlined into the value set (as a packaging convenience). Note that the inline code system may be used from other value sets by referring to its (codeSystem.system) directly codeSystem [0..1] Additional representations for this concept when used in this value set - other languages, aliases, specialized purposes, used for particular purposes, etc designation [0..*] Specifies a concept to be included or excluded concept [0..*] 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 true filter [0..*] Include one or more codes from a code system include [0..*] Exclude one or more codes from the value set exclude [0..*] A set of criteria that provide the content logical definition of the value set by including or excluding codes from outside this value set compose [0..1] A parameter that controlled the expansion process. These parameters may be used by users of expanded value sets to check whether the expansion is suitable for a particular purpose, or to pick the correct expansion parameter [0..*] Other codes and entries contained under this entry in the hierarchy contains [0..*] The codes that are contained in the value set expansion contains [0..*] 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 performed expansion [0..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 identifier for  value set -->
 <identifier><!-- 0..1 Identifier Additional identifier for the value set (e.g. HL7 v2 / CDA) --></identifier>
 <version value="[string]"/><!-- 0..1 Logical identifier for this version of the value set -->
 <name value="[string]"/><!-- 0..1 Informal name for this value set -->
 <status value="[code]"/><!-- 1..1 draft | active | retired -->
 <experimental value="[boolean]"/><!-- 0..1 If for testing purposes, not real usage -->
 <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 an individual to contact -->
  <telecom><!-- 0..* ContactPoint Contact details for individual or publisher --></telecom>
 </contact>
 <date value="[dateTime]"/><!-- 0..1 Date for given status -->
 <lockedDate value="[date]"/><!-- 0..1 Fixed date for all referenced code systems and value sets -->
 <description value="[string]"/><!-- 0..1 Human language description of the value set -->
 <useContext><!-- 0..* CodeableConcept Content intends to support these contexts --></useContext>
 <immutable value="[boolean]"/><!-- 0..1 Indicates whether or not any change to the content logical definition may occur -->
 <requirements value="[string]"/><!-- 0..1 Why needed -->
 <copyright value="[string]"/><!-- 0..1 Use and/or publishing restrictions -->
 <extensible value="[boolean]"/><!-- 0..1 Whether this is intended to be used with an extensible binding -->
 <codeSystem>  <!-- ?? 0..1 An inline code system, which is part of this value set -->
  <system value="[uri]"/><!-- 1..1 URI to identify the code system (e.g. in Coding.system) -->
  <version value="[string]"/><!-- 0..1 Version (for use in Coding.version) -->
  <caseSensitive value="[boolean]"/><!-- 0..1 If code comparison is case sensitive -->
  <concept>  <!-- 1..* 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 Human 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.codeSystem.concept Child Concepts (is-a/contains/categorizes) --></concept>
  </concept>
 </codeSystem>
 <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.codeSystem.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 value="[uri]"/><!-- 1..1 Uniquely identifies this expansion -->
  <timestamp value="[dateTime]"/><!-- 1..1 Time ValueSet expansion happened -->
  <total value="[integer]"/><!-- 0..1 Total number of codes in the expansion -->
  <offset value="[integer]"/><!-- 0..1 Offset at which this resource starts -->
  <parameter>  <!-- 0..* Parameter that controlled the expansion process -->
   <name value="[string]"/><!-- 1..1 Name as assigned by the server -->
   <value[x]><!-- 0..1 string|boolean|integer|decimal|uri|code Value of the named parameter --></value[x]>
  </parameter>
  <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 selectable code -->
   <display value="[string]"/><!-- ?? 0..1 User display for the concept -->
   <contains><!-- 0..* Content as for ValueSet.expansion.contains Codes contained under this entry --></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 identifier for  value set
  "identifier" : { Identifier }, // Additional identifier for the value set (e.g. HL7 v2 / CDA)
  "version" : "<string>", // Logical identifier for this version of the value set
  "name" : "<string>", // Informal name for this value set
  "status" : "<code>", // R!  draft | active | retired
  "experimental" : <boolean>, // If for testing purposes, not real usage
  "publisher" : "<string>", // Name of the publisher (organization or individual)
  "contact" : [{ // Contact details of the publisher
    "name" : "<string>", // Name of an individual to contact
    "telecom" : [{ ContactPoint }] // Contact details for individual or publisher
  }],
  "date" : "<dateTime>", // Date for given status
  "lockedDate" : "<date>", // Fixed date for all referenced code systems and value sets
  "description" : "<string>", // Human language description of the value set
  "useContext" : [{ CodeableConcept }], // Content intends to support these contexts
  "immutable" : <boolean>, // Indicates whether or not any change to the content logical definition may occur
  "requirements" : "<string>", // Why needed
  "copyright" : "<string>", // Use and/or publishing restrictions
  "extensible" : <boolean>, // Whether this is intended to be used with an extensible binding
  "codeSystem" : { // C? An inline code system, which is part of this value set
    "system" : "<uri>", // R!  URI to identify the code system (e.g. in Coding.system)
    "version" : "<string>", // Version (for use in Coding.version)
    "caseSensitive" : <boolean>, // If code comparison is case sensitive
    "concept" : [{ // R!  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>", // Human 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.codeSystem.concept }] // Child Concepts (is-a/contains/categorizes)
    }]
  },
  "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" : [{ // C? 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.codeSystem.concept.designation }] // Additional representations for this valueset
      }],
      "filter" : [{ // C? 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" : "<uri>", // R!  Uniquely identifies this expansion
    "timestamp" : "<dateTime>", // R!  Time ValueSet expansion happened
    "total" : <integer>, // Total number of codes in the expansion
    "offset" : <integer>, // Offset at which this resource starts
    "parameter" : [{ // Parameter that controlled the expansion process
      "name" : "<string>", // R!  Name as assigned by the server
      // value[x]: Value of the named parameter. One of these 6:

      "valueString" : "<string>"
      "valueBoolean" : <boolean>
      "valueInteger" : <integer>
      "valueDecimal" : <decimal>
      "valueUri" : "<uri>"
      "valueCode" : "<code>"
    }],
    "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 selectable code
      "display" : "<string>", // C? User display for the concept
      "contains" : [{ Content as for ValueSet.expansion.contains }] // Codes contained under this entry
    }]
  }
}

Structure

Name Flags Card. Type Description & Constraints doco
.. ValueSet I DomainResource A set of codes drawn from one or more code systems
A defined code system (if present) SHALL have a different url than the value set url
Value set SHALL contain at least one of a codeSystem, 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 includes and inline code system
... url Σ 0..1 uri Globally unique logical identifier for value set
... identifier Σ 0..1 Identifier Additional identifier for the value set (e.g. HL7 v2 / CDA)
... version Σ 0..1 string Logical identifier for this version of the value set
... name Σ 0..1 string Informal name for this value set
... status ?! Σ 1..1 code draft | active | retired
ConformanceResourceStatus ( Required )
... experimental Σ 0..1 boolean If for testing purposes, not real usage
... publisher Σ 0..1 string Name of the publisher (organization or individual)
... contact Σ 0..* BackboneElement Contact details of the publisher
.... name Σ 0..1 string Name of an individual to contact
.... telecom Σ 0..* ContactPoint Contact details for individual or publisher
... date Σ 0..1 dateTime Date for given status
... lockedDate Σ 0..1 date Fixed date for all referenced code systems and value sets
... description Σ 0..1 string Human language description of the value set
... useContext Σ 0..* CodeableConcept Content intends to support these contexts
Context of Use ValueSet ( Extensible )
... immutable Σ 0..1 boolean Indicates whether or not any change to the content logical definition may occur
... requirements 0..1 string Why needed
... copyright 0..1 string Use and/or publishing restrictions
... extensible Σ 0..1 boolean Whether this is intended to be used with an extensible binding
... codeSystem Σ I 0..1 BackboneElement An inline code system, which is part of this value set
Codes must be unique
Within a code system definition, all the codes SHALL be unique
.... system Σ 1..1 uri URI to identify the code system (e.g. in Coding.system)
.... version Σ 0..1 string Version (for use in Coding.version)
.... caseSensitive Σ 0..1 boolean If code comparison is case sensitive
.... concept 1..* BackboneElement Concepts in the code system
..... code 1..1 code Code that identifies concept
..... abstract 0..1 boolean If this code is not for use as a real concept
..... display 0..1 string Text to display to the user
..... definition 0..1 string Formal definition
..... designation 0..* BackboneElement Additional representations for the concept
...... language 0..1 code Human language of the designation
Language ( Required )
...... use 0..1 Coding Details how this designation would be used
Designation Use ( Extensible )
...... value 1..1 string The text value for this designation
..... concept 0..* see concept Child Concepts (is-a/contains/categorizes)
... compose I 0..1 BackboneElement When value set includes codes from elsewhere
A value set composition SHALL have an include or an import
.... import Σ I 0..* uri Import the contents of another value set
.... include Σ I 0..* BackboneElement Include one or more codes from a code system
Cannot have both concept and filter
..... system Σ 1..1 uri The system the codes come from
..... version Σ 0..1 string Specific version of the code system referred to
..... concept I 0..* BackboneElement A concept defined in the system
...... code 1..1 code Code or expression from system
...... display 0..1 string Test to display for this code for this value set
...... designation 0..* see designation Additional representations for this valueset
..... filter I 0..* BackboneElement Select codes/concepts by their properties (including relationships)
...... property 1..1 code A property defined by the code system
...... op 1..1 code = | is-a | is-not-a | regex | in | not-in
FilterOperator ( Required )
...... value 1..1 code Code from the system, or regex criteria
.... exclude I 0..* see include Explicitly exclude codes
... expansion I 0..1 BackboneElement Used when the value set is "expanded"
.... identifier 1..1 uri Uniquely identifies this expansion
.... timestamp 1..1 dateTime Time ValueSet expansion happened
.... total 0..1 integer Total number of codes in the expansion
.... offset 0..1 integer Offset at which this resource starts
.... parameter 0..* BackboneElement Parameter that controlled the expansion process
..... name 1..1 string Name as assigned by the server
..... value[x] 0..1 Value of the named parameter
...... valueString string
...... valueBoolean boolean
...... valueInteger integer
...... valueDecimal decimal
...... valueUri uri
...... valueCode code
.... contains I 0..* BackboneElement Codes 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..1 uri System value for the code
..... abstract 0..1 boolean If user cannot select this entry
..... version 0..1 string Version in which this code/display is defined
..... code I 0..1 code Code - if blank, this is not a selectable code
..... display I 0..1 string User display for the concept
..... contains 0..* see contains Codes contained under this entry

doco Documentation for this format

UML Diagram

ValueSet ( DomainResource ) An absolute URL that is used to identify this value set when it is referenced in a specification, model, design or an instance. This SHALL be a URL, SHOULD be globally unique, and SHOULD be an address at which this value set is (or will be) published url : uri [0..1] Formal 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 instance identifier : Identifier [0..1] 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 timestamp version : string [0..1] A free text natural language name describing the value set name : string [0..1] The status of the value set (this element modifies the meaning of other elements) status : code 1..1 << [1..1] « The lifecycle status of a Value Set or Concept Map Map. (Strength=Required) ValueSetStatus >> ConformanceResourceStatus ! » This valueset was authored for testing purposes (or education/evaluation/marketing), and is not intended to be used for genuine usage experimental : boolean 0..1 [0..1] The name of the individual or organization that published the value set publisher : string [0..1] The date that the value set status was last changed. The date must change when the business version changes, if it does, and it must change if the status code changes. In addition, it should change when the substantive content of the implementation guide changes (e.g. the 'content logical definition') date : dateTime [0..1] If a locked date is defined, then the Content Logical Definition must be evaluated using the current version of all referenced code system(s) and value set instances as of the locked date lockedDate : date [0..1] A 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 set description : string [0..1] The content was developed with a focus and intent of supporting the contexts that are listed. These terms may be used to assist with indexing and searching of value set definitions useContext : CodeableConcept [0..*] « Indicates the countries, regions, disciplines and other aspects of use within which this artifact is targeted for use. (Strength=Extensible) Context of Use ValueSet + » If this is set to 'true', then no new versions of the content logical definition can be created. Note: Other metadata might still change immutable : boolean [0..1] Explains why this value set is needed and why it has been constrained as it has requirements : string [0..1] A 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 set copyright : string [0..1] Whether this is intended to be used with an extensible binding or not extensible : boolean 0..1 [0..1] Contact The date that name of an individual to contact regarding the value set status name : string [0..1] Contact details for individual (if a name was last changed provided) or the publisher date telecom : dateTime ContactPoint 0..1 [0..*] Define CodeSystem An absolute URI that is used to identify the reference this code system system, including in [Coding]{datatypes.html#Coding}.system system : uri 1..1 [1..1] The 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 tracked version : string 0..1 [0..1] If code comparison is case sensitive when codes within this system are compared to each other caseSensitive : boolean 0..1 [0..1] Concept ConceptDefinition Code A code - a text symbol - that uniquely identifies the concept within the code system code : code 1..1 [1..1] If this code is not for use as a real concept abstract : boolean 0..1 [0..1] Text A human readable string that is the recommended default way to Display present this concept to the a user display : string 0..1 [0..1] The formal definition of the concept. Formal definitions are The value set resource does not make formal definitions required, because of the prevalence of legacy systems without them, but systems. However, they are highly recommended, as without them there is no formal meaning associated with the concept definition : string 0..1 [0..1] Designation The language this designation is defined for language : code [0..1] « A human language. (Strength=Required) Language ! » A code that details how this designation would be used use : Coding [0..1] « Details of how a designation would be used. (Strength=Extensible) Designation Use + » The text value for this designation value : string [1..1] Compose Includes the contents of the referenced value set as a part of the contents of this value set set. This is an absolute URI that is a reference to ValueSet.uri import : uri 0..* [0..*] ConceptSet The An absolute URI which is the code system from which the selected codes come from system : uri 1..1 [1..1] The version of the code system that the codes are selected from version : string 0..1 [0..1] ConceptReference Specifies a code or for the concept to be included or excluded. excluded code : code [1..1] The list text to display to the user for this concept in the context of codes this valueset. If no display is considered ordered, though provided, then applications using the value set use the display specified for the order may not have any particular significance code by the system display : code string 0..* [0..1] Filter A code that identifies a property defined in the code system property : code 1..1 [1..1] The kind of operation to perform as a part of the filter criteria op : code 1..1 << [1..1] « The kind of operation to perform as a part of a property based filter filter. (Strength=Required) FilterOperator >> ! » The match value may be either a code defined by the system, or a string value value, which is used a regex match on the literal string of the property value value : code 1..1 [1..1] Expansion An 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 so identifier : Identifier uri 0..1 [1..1] Time valueset The time at which the expansion happened was produced by the expanding system timestamp : instant dateTime 1..1 [1..1] The total number of concepts in the expansion. If the number of concept nodes in this resource is less than the stated number, then the server can return more using the offset parameter total : integer [0..1] If paging is being used, the offset at which this resource starts. I.e. this resource is a partial view into the expansion. If paging is not being used, this element SHALL not be present offset : integer [0..1] Parameter The name of the parameter name : string [1..1] The value of the parameter value[x] : Type [0..1] « string | boolean | integer | decimal | uri | code » Contains System value for An absolute URI which is the code system in which the code for this item in the expansion is defined system : uri 0..1 [0..1] If true, this entry is included in the expansion for navigational purposes, and the user cannot select the code directly as a proper value abstract : boolean [0..1] The 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 permanence version : string [0..1] Code - if blank, The code for this item in the expansion hierarchy. If this code is missing the entry in the hierarchy is a place holder (abstract) and does not represent a choosable valid code in the value set code : code 0..1 [0..1] User The recommended display for this item in the concept expansion display : string 0..1 [0..1] Child Concepts (is-a / contains) Contacts to assist a user in finding and communicating with the publisher contact [0..*] Additional representations for the concept - other languages, aliases, specialized purposes, used for particular purposes, etc designation 0..* [0..*] Defines children of a concept to produce a hierarchy of concepts. The nature of the relationships is variable (is-a/contains/categorizes) and can only be determined by examining the definitions of the concepts concept [0..*] Concepts that are in the code system system. The concept definitions are inherently hierarchical, but the definitions must be consulted to determine what the meaning of the hierarchical relationships are concept 0..* [1..*] When A definition of a code system, inlined into the value set defines (as a packaging convenience). Note that the inline code system may be used from other value sets by referring to its own codes (codeSystem.system) directly define codeSystem 0..1 [0..1] Additional representations for this concept when used in this value set - other languages, aliases, specialized purposes, used for particular purposes, etc designation [0..*] Specifies a concept to be included or excluded concept [0..*] 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 true filter 0..* [0..*] Include one or more codes from a code system include 0..* [0..*] Exclude one or more codes from the value set exclude 0..* [0..*] When A set of criteria that provide the content logical definition of the value set includes by including or excluding codes from elsewhere outside this value set compose 0..1 [0..1] A parameter that controlled the expansion process. These parameters may be used by users of expanded value sets to check whether the expansion is suitable for a particular purpose, or to pick the correct expansion parameter [0..*] Codes Other codes and entries contained in under this concept entry in the hierarchy contains 0..* [0..*] Codes The codes that are contained in the value set expansion contains 0..* [0..*] When A value set can also be "expanded", where the value set is an expansion turned into a simple collection of enumerated codes. This element holds the expansion, if it has been performed expansion 0..1 [0..1] This resource is referenced by ConceptMap , Profile and Questionnaire

XML Template

< <!-- from --> < < < < <</telecom> < < < < < < < < < < < < < < < <</concept> 
<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 identifier for  value set -->
 <identifier><!-- 0..1 Identifier Additional identifier for the value set (e.g. HL7 v2 / CDA) --></identifier>
 <version value="[string]"/><!-- 0..1 Logical identifier for this version of the value set -->
 <name value="[string]"/><!-- 0..1 Informal name for this value set -->
 <status value="[code]"/><!-- 1..1 draft | active | retired -->
 <experimental value="[boolean]"/><!-- 0..1 If for testing purposes, not real usage -->
 <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 an individual to contact -->
  <telecom><!-- 0..* ContactPoint Contact details for individual or publisher --></telecom>
 </contact>
 <date value="[dateTime]"/><!-- 0..1 Date for given status -->
 <lockedDate value="[date]"/><!-- 0..1 Fixed date for all referenced code systems and value sets -->
 <description value="[string]"/><!-- 0..1 Human language description of the value set -->
 <useContext><!-- 0..* CodeableConcept Content intends to support these contexts --></useContext>
 <immutable value="[boolean]"/><!-- 0..1 Indicates whether or not any change to the content logical definition may occur -->
 <requirements value="[string]"/><!-- 0..1 Why needed -->
 <copyright value="[string]"/><!-- 0..1 Use and/or publishing restrictions -->
 <extensible value="[boolean]"/><!-- 0..1 Whether this is intended to be used with an extensible binding -->
 <codeSystem>  <!-- ?? 0..1 An inline code system, which is part of this value set -->
  <system value="[uri]"/><!-- 1..1 URI to identify the code system (e.g. in Coding.system) -->
  <version value="[string]"/><!-- 0..1 Version (for use in Coding.version) -->
  <caseSensitive value="[boolean]"/><!-- 0..1 If code comparison is case sensitive -->
  <concept>  <!-- 1..* 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 Human 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.codeSystem.concept Child Concepts (is-a/contains/categorizes) --></concept>

  </concept>
 </define>
 <
  <
  <
   <
   <
   <
   <
    <
    <
    <

 </codeSystem>
 <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.codeSystem.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>

  <exclude><!-- ?? 0..* Content as for ValueSet.compose.include Explicitly exclude codes --></exclude>

 </compose>
 <
  <</identifier>
  <
  <
   <
   <
   <
   <</contains>

 <expansion>  <!-- ?? 0..1 Used when the value set is "expanded" -->
  <identifier value="[uri]"/><!-- 1..1 Uniquely identifies this expansion -->
  <timestamp value="[dateTime]"/><!-- 1..1 Time ValueSet expansion happened -->
  <total value="[integer]"/><!-- 0..1 Total number of codes in the expansion -->
  <offset value="[integer]"/><!-- 0..1 Offset at which this resource starts -->
  <parameter>  <!-- 0..* Parameter that controlled the expansion process -->
   <name value="[string]"/><!-- 1..1 Name as assigned by the server -->
   <value[x]><!-- 0..1 string|boolean|integer|decimal|uri|code Value of the named parameter --></value[x]>
  </parameter>
  <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 selectable code -->
   <display value="[string]"/><!-- ?? 0..1 User display for the concept -->
   <contains><!-- 0..* Content as for ValueSet.expansion.contains Codes contained under this entry --></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 identifier for  value set
  "identifier" : { Identifier }, // Additional identifier for the value set (e.g. HL7 v2 / CDA)
  "version" : "<string>", // Logical identifier for this version of the value set
  "name" : "<string>", // Informal name for this value set
  "status" : "<code>", // R!  draft | active | retired
  "experimental" : <boolean>, // If for testing purposes, not real usage
  "publisher" : "<string>", // Name of the publisher (organization or individual)
  "contact" : [{ // Contact details of the publisher
    "name" : "<string>", // Name of an individual to contact
    "telecom" : [{ ContactPoint }] // Contact details for individual or publisher
  }],
  "date" : "<dateTime>", // Date for given status
  "lockedDate" : "<date>", // Fixed date for all referenced code systems and value sets
  "description" : "<string>", // Human language description of the value set
  "useContext" : [{ CodeableConcept }], // Content intends to support these contexts
  "immutable" : <boolean>, // Indicates whether or not any change to the content logical definition may occur
  "requirements" : "<string>", // Why needed
  "copyright" : "<string>", // Use and/or publishing restrictions
  "extensible" : <boolean>, // Whether this is intended to be used with an extensible binding
  "codeSystem" : { // C? An inline code system, which is part of this value set
    "system" : "<uri>", // R!  URI to identify the code system (e.g. in Coding.system)
    "version" : "<string>", // Version (for use in Coding.version)
    "caseSensitive" : <boolean>, // If code comparison is case sensitive
    "concept" : [{ // R!  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>", // Human 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.codeSystem.concept }] // Child Concepts (is-a/contains/categorizes)
    }]
  },
  "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" : [{ // C? 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.codeSystem.concept.designation }] // Additional representations for this valueset
      }],
      "filter" : [{ // C? 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" : "<uri>", // R!  Uniquely identifies this expansion
    "timestamp" : "<dateTime>", // R!  Time ValueSet expansion happened
    "total" : <integer>, // Total number of codes in the expansion
    "offset" : <integer>, // Offset at which this resource starts
    "parameter" : [{ // Parameter that controlled the expansion process
      "name" : "<string>", // R!  Name as assigned by the server
      // value[x]: Value of the named parameter. One of these 6:

      "valueString" : "<string>"
      "valueBoolean" : <boolean>
      "valueInteger" : <integer>
      "valueDecimal" : <decimal>
      "valueUri" : "<uri>"
      "valueCode" : "<code>"
    }],
    "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 selectable code
      "display" : "<string>", // C? User display for the concept
      "contains" : [{ Content as for ValueSet.expansion.contains }] // Codes contained under this entry
    }]
  }
}

 

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

6.13.4.1 6.21.4.1 Terminology Bindings

Path Definition Type Reference
ValueSet.status The lifecycle status of a Value Set or Concept Map Map. Fixed Required http://hl7.org/fhir/valueset-status ConformanceResourceStatus
ValueSet.useContext Indicates the countries, regions, disciplines and other aspects of use within which this artifact is targeted for use. 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 filter. Fixed Required http://hl7.org/fhir/filter-operator FilterOperator

6.13.4.2 6.21.4.2 Constraints

  • Inv-2 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 defines its own codes 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:define)) exists(f:codeSystem)) )
  • Inv-5 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 either at least one of a define, codeSystem, a compose, or an expansion element (xpath: exists(f:define) exists(f:codeSystem) or exists(f:compose) or exists(f:expansion) )
  • Inv-7 vsd-6 : A defined code system (if present) On ValueSet.expansion.contains: SHALL have a different identifier to the value set itself (xpath: code or a display (xpath on f:ValueSet/f:expansion/f:contains: not(exists(f:define)) exists(f:code) or (f:define/f:system/@value != f:identifier/@value) exists(f:display) )
  • Inv-3 vsd-7 : On ValueSet.define: Within a A defined code system definition, all the codes (if present) SHALL be unique (xpath on f:ValueSet/f:define: have a different url than the value set url (xpath: count(distinct-values(descendant::f:concept/f:code/@value))=count(descendant::f:concept) not(f:codeSystem/f:system/@value = f:url/@value) )
  • Inv-8 vsd-8 : On ValueSet.define: ValueSet.codeSystem: Codes must be unique (xpath on f:ValueSet/f:define: f:ValueSet/f:codeSystem: 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 vsd-9 : On ValueSet.expansion.contains: SHALL Must have a code or a display if not abstract (xpath on f:ValueSet/f:expansion/f:contains: exists(f:code) or exists(f:display) (f:abstract/@value = true()) )

6.13.5 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 HL7 v3 message (valueSet (in the CD data type valueSet and valueSetVersion). valueSetVersion properties). 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 implementations, as they can make use of the innate identifier and versioning mechanism associated with the resource resource.

6.13.6 6.21.6 Value Sets that define codes with In-line Code Systems

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

  • ValueSet.define.system 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 concept.
  • If concepts contain other concepts, then This specification does not fix the contained concepts are "subsumed" by meaning of the containing concept (there is an "is-a" 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 codes). 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 define their own codes contain inline code systems when they are not defined elsewhere, such as codes defined in SNOMED CT, LOINC, RxNorm etc. 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.13.6.1 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 changing the meaning of an existing code 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 SNOMED CT has re-defined the a complex version release framework, which may lead to variations in meaning of codes in the past, concepts, but there is only one identifier for LOINC. SNOMED CT.

For this reason, a code system MAY provide a version identifer identifier which can be specified in ValueSet.define.version 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 includes 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 as the version string the date (expressed in FHIR date format) on which the version of the code system that is being used was officially published.

6.13.7 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 sets, including human language. The value set can be a simple list of included codes codes, or it can be some kind of general selection criteria using the facilities provided by the code system. For these value sets:

  • Within an include or exclude criterion, multiple filters and concept selections are intersected. All of 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 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 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 content.
  • Using the property filters is only possible where the underlying code system defines appropriate properties. Note that in some cases, 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 systems.
    • 6.13.7.1 Code systems Note How filters
  • 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 with various 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 systems: 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:

System Property Name Operation Value Definition Example SNOMED CT
  • The system that defines the code or expression = [expression] doesn't provide a display for this code (or any codes).
  • The result of system that defines the filter code or expression defines multiple choices for display.
  • The system provides a very long display name that is unnecessary or inappropriate in the result context of executing 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 given SNOMED CT expression (see 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 draft SNOMED CT Query Language ) (no example yet) concept is-a [concept] Includes all concept ids by implying that have a transitive is-a relationship with it means something other than the explicit definition of the concept Id provided as in the value 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.

The SNOMED CT Query Language expression display name for this the code in the value set is DescendentsAndSelf([concept]) Administation Methods concept only used in [concept] Includes all concept ids that are the UI. The display in a Coding must be taken from the reference underlying system, even if a value set identified by is referenced explicitly in the concept Id provided as Coding. The alternative display specified in the value The SNOMED CT Query Language expression for this is MembersOf([concept]) Administation Methods set would go in CodeableConcept .text.

6.21.8 Value Sets with multiple code systems LOINC [property] = / regex [value] Includes all

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

Note that a value set always includes any codes where the named property has the given value. Valid Property Names are all the names listed in the "Field Name" column in LOINC Database Structure (Appendix 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 the LOINC manual). Of these, the 6 properties COMPONENT, PROPERTY, TIME_ASPCT, SYSTEM, SCALE_TYP, codes from elsewhere, and METHOD_TYP are most likely adding a few additional codes to be useful. In addition, cover cases not catered to by the following 5 property names are defined in included codes.

Best Practice Note: Mixing definitional systems offers the Document Ontology: Document.Kind, Document.TypeOfService, Document.Setting, Document.Role, potential for confusing, overlapping, and Document.SubjectMatterDomain. 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 Document Codes Type = Method All the LOINC codes for particular methods defined in

How filters are used with various code systems:

System Property Name Operation Value Definition Example
V3 HL7 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
HL7 v2 Tables (no filters defined)

6.13.8 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 children of 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 ( define codeSystem and compose elements). In addition addition, it has a an expansion element which contains the list of codes that constitute the value set expansion. If the expansion is heirarchical (codes contain other concepts), has nested contains elements, there is no implication about the logical relationship between them; this is guidance them, and the structure cannot be used for logical inferencing. The structure exists to provide navigational assistance for helping human user navigate the choice of codes that may or may not relate users to the logical definitions of the locate codes or concepts. in the expansion.

In general, When a request for an expansion is received (e.g., for the $expand operation), the following process should be followed when expanding a value set: followed:

  • for 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, set by ValueSet.url, expand that, that (e.g., using the $expand operation: GET [base]/ValueSet/$expand$identifier=[compose.import]), and add it to the result set set. This means that expansion across imports is a recursive process.
  • for For each compose.include , identify the correct version of the code system, and then:
    • if If there is are no codes or filters, add every code in the code system to the result set set.
    • if 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 If any filters are present, process them in order (as explained above), and add the intersection of their results to the result set set.
  • for For each compose.exclude , follow the same process as for compose.include , but remove any codes from the result set, instead of adding them them.
  • add Add any codes in the define codeSystem to the result set 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. 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 application MAY offer to expand value sets for other applications. In this case, expansion may include entries in the standard way to produce a value set expansion is that only serve an arbitrary grouping purpose, to perform make it easier for a query on human to use the list. These entries have no system or code, and must be marked as abstract. Note that the value set with _query=expand: 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.

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

This is a request to produce a value set The codes in the expansion for should be treated as case sensitive - implementers should use the value set with correct case. Implementers can consult the provided id which definition of the code system to determine whether the code system that defines the code is either a logical id, case sensitive or an absolute reference not.

Whether to a value set. The store expanded value set can be identified by other means, such as identifier and version. Servers can define sets, or simply to store their own additional parameters that influence 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 process, such in relation must be concerned with how to order and hierarchy. The value set determine whether the expansion returned by is still current, and this query should be treated as requires deep knowledge of how the expansion was created. A system with a transient result dedicated terminology server that will change over time (whether it does or not depends returns expansions on demand avoids this problem, but leaves open the question of how to audit the value set specific expansion that was used for a particular case. One solution to this is specified), so applications should repeat to use a dedicated terminology server, and have the query each time clients ask for expansions on demand based on the value set is used. 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.13.9 6.21.9.1 Code systems with detailed metadata Value Set Validation

An application Sometimes code systems may offer be used to provide represent more complex information than just code, display name and code validation services for other applications. 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 this case, FHIR, these are handled by splitting the standard way for an application concept into two distinct parts - the ValueSet resource is used to ask manage the codes, display names and relationships. A separate "detail" resource (e.g., Medication for validation 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 a query standard terminology operations on the value set code systems dealing with _query=validate: GET [service-url]/ValueSet/?_query=validate&id=:valueSet&system=:system&version=:version&code=:code&... The values for system, version, and complex structures - code are those from the Coding lookup, validation, subsumption testing, mapping and translation.
  • It allows information to be exchanged about individual medications, data type. Version elements and locations. Codes can't be retrieved individually in FHIR - it is optional, necessary to retrieve the entire resource. By packaging the detailed information in separate resources, independent retrieval and code update is possible.
  • It supports use-cases for sharing medication, location, observation type and system are mandatory. Additionally, similar information in circumstances where the parameter "coding" or "codeableconcept" can code may be used - the value of unknown, unavailable or occasionally non-existent (e.g., custom compounds, non-registered locations). Having a distinct resource supports these parameters capabilities, 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 URL encoded XML FHIR interface. Similarly, some systems may choose to only expose or JSON representation maintain one aspect of the two data such information types respectively. An additional boolean parameter "extensible" can be provided to specify whether (i.e. only the applicable binding is extensible discrete resource instances or not. only the value set).

The result of this query 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 Operation Outcome . If there are no errors in "identifier" element. This can be set to the outcome (OperationOutcome.issue.severity), then same value and namespace as the code code, but if the only identifier a resource has is considered to its defining code, it may be valid. better to omit the identifier entirely.

6.13.10 6.21.10 Search Parameters

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

Name Type Description Paths
_id code token The logical resource id associated with A code defined in the resource (must be supported by all servers) _language token value set The language of the resource ValueSet.codeSystem.concept.code
code context token A code defined in use context assigned to the value set ValueSet.define.concept.code 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 of 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 token 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 token uri The system for any codes defined by this value set ValueSet.define.system 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
var disqus_shortname = 'fhirdstu';(function() {var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true;dsq.src = '//' + disqus_shortname + '.disqus.com/embed.js';(document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq); })(); Please enable JavaScript to view the comments powered by Disqus. comments powered by Disqus var _gaq = _gaq || []; _gaq.push(['_setAccount', 'UA-676355-1']); _gaq.push(['_setDomainName', '.hl7.org']); _gaq.push(['_trackPageview']); (function()