STU 3 Ballot

This page is part of the FHIR Specification (v1.6.0: STU 3 Ballot 4). 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

4.7 Resource ValueSet - Content

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

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

4.7.1 Scope and Usage

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

  • CodeSystem - defines a set of codes with meanings (also known as enumeration, terminology, classification, and/or ontology) - e.g. define which codes (symbols and/or expressions) exist, and how they are understood
  • ValueSet - selects a set of codes from those defined by one or more code systems to specify which codes can be used in a particular context

Value sets have 2 aspects:

  • .compose: A definition of what codes are in intended to be in the value set ("intension")
  • .expansion: The list of codes that are actually in the value set under a given set of conditions ("extension")

The ValueSet resource can carry either the .compose or the .expansion, or both. There is an "$expand" operation which can be used to ask a server to generation an expansion given the composition rules.

4.7.2 Boundaries and Relationships

  • Value sets use CodeSystem resources by referring to them via their canonical URLs
  • Value sets are used in ElementDefinition and Questionnaire resources to specify the allowable contents for coded elements
  • Concept Maps describe mappings between value sets
  • The ValueSet resource design is based on 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".

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

4.7.3.1 ValueSet Identification

A value set has 3 identifiers:

  • ValueSet.id: the logical id on the system that holds the value set - 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 canonical url that never changes for this value set - it is the same in every copy. Ideally, the URL should also be the location of the master version of the value set, though this is not always possible
  • 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 regarding resource identification, see Resource Identity.

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

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

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

This resource is referenced by ConceptMap, OperationDefinition and Questionnaire

4.7.4 Resource Content

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. ValueSet IDomainResourceA set of codes drawn from one or more code systems
A value set with only one import SHALL also have an include and/or an exclude
Value set SHALL contain at least one of a a compose, or an expansion element
... url Σ0..1uriGlobally unique logical identifier for value set
... identifier Σ0..*IdentifierAdditional identifier for the value set (e.g. HL7 v2 / CDA)
... version Σ0..1stringLogical identifier for this version of the value set
... name Σ0..1stringInformal name for this value set
... status ?!Σ1..1codedraft | active | retired
ConformanceResourceStatus (Required)
... experimental Σ0..1booleanIf for testing purposes, not real usage
... publisher Σ0..1stringName of the publisher (organization or individual)
... contact Σ0..*BackboneElementContact details of the publisher
.... name Σ0..1stringName of an individual to contact
.... telecom Σ0..*ContactPointContact details for individual or publisher
... date Σ0..1dateTimeDate for given status
... lockedDate Σ0..1dateFixed date for all referenced code systems and value sets
... description Σ0..1markdownHuman language description of the value set
... useContext Σ0..*CodeableConceptContent intends to support these contexts
Context of Use ValueSet (Extensible)
... immutable Σ0..1booleanIndicates whether or not any change to the content logical definition may occur
... requirements 0..1markdownWhy needed
... copyright 0..1stringUse and/or publishing restrictions
... extensible Σ0..1booleanWhether this is intended to be used with an extensible binding
... compose I0..1BackboneElementWhen 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..*BackboneElementInclude one or more codes from a code system
Cannot have both concept and filter
..... system Σ1..1uriThe system the codes come from
..... version Σ0..1stringSpecific version of the code system referred to
..... concept I0..*BackboneElementA concept defined in the system
...... code 1..1codeCode or expression from system
...... display 0..1stringText to display for this code for this value set
...... designation 0..*BackboneElementAdditional representations for this valueset
....... language 0..1codeHuman language of the designation
Common Languages (Extensible but limited to All Languages)
....... use 0..1CodingDetails how this designation would be used
Designation Use (Extensible)
....... value 1..1stringThe text value for this designation
..... filter I0..*BackboneElementSelect 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 | generalizes
FilterOperator (Required)
...... value 1..1codeCode from the system, or regex criteria
.... exclude I0..*see includeExplicitly exclude codes
... expansion I0..1BackboneElementUsed when the value set is "expanded"
.... identifier 1..1uriUniquely identifies this expansion
.... timestamp 1..1dateTimeTime ValueSet expansion happened
.... total 0..1integerTotal number of codes in the expansion
.... offset 0..1integerOffset at which this resource starts
.... parameter 0..*BackboneElementParameter that controlled the expansion process
..... name 1..1stringName as assigned by the server
..... value[x] 0..1Value of the named parameter
...... valueStringstring
...... valueBooleanboolean
...... valueIntegerinteger
...... valueDecimaldecimal
...... valueUriuri
...... valueCodecode
.... contains I0..*BackboneElementCodes in the value set
SHALL have a code or a display
Must have a code if not abstract
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 selectable code
..... display I0..1stringUser display for the concept
..... contains 0..*see containsCodes contained under this entry

doco Documentation for this format

UML Diagram (Legend)

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) publishedurl : uri [0..1]A 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 instanceidentifier : Identifier [0..*]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..1]A free text natural language name describing the value setname : string [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 usageexperimental : boolean [0..1]The name of the individual or organization that published the value setpublisher : 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 datelockedDate : 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 setdescription : markdown [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 definitionsuseContext : 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 changeimmutable : boolean [0..1]Explains why this value set is needed and why it has been constrained as it hasrequirements : markdown [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 setcopyright : string [0..1]Whether this is intended to be used with an extensible binding or notextensible : boolean [0..1]ContactThe name of an individual to contact regarding the value setname : string [0..1]Contact details for individual (if a name was provided) or the publishertelecom : ContactPoint [0..*]ComposeIncludes 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.urlimport : uri [0..*]ConceptSetAn absolute URI which is the code system from which the selected codes come fromsystem : uri [1..1]The version of the code system that the codes are selected fromversion : string [0..1]ConceptReferenceSpecifies a code for the concept to be included or excludedcode : 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 systemdisplay : string [0..1]DesignationThe language this designation is defined forlanguage : code [0..1] « A human language. (Strength=Extensible)Common Languages+ »A code that details how this designation would be useduse : Coding [0..1] « Details of how a designation would be used. (Strength=Extensible)Designation Use+ »The text value for this designationvalue : string [1..1]FilterA code that identifies a property defined in the code systemproperty : code [1..1]The 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 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 valuevalue : code [1..1]ExpansionAn 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 : uri [1..1]The time at which the expansion was produced by the expanding systemtimestamp : 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 parametertotal : 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 presentoffset : integer [0..1]ParameterThe name of the parametername : string [1..1]The value of the parametervalue[x] : Type [0..1] « string|boolean|integer|decimal|uri|code »ContainsAn absolute URI which is the code system in which the code for this item in the expansion is definedsystem : 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 valueabstract : 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 permanenceversion : 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 setcode : code [0..1]The recommended display for this item in the expansiondisplay : string [0..1]Contacts to assist a user in finding and communicating with the publishercontact[0..*]Additional representations for this concept when used in this value set - other languages, aliases, specialized purposes, used for particular purposes, etcdesignation[0..*]Specifies a concept to be included or excludedconcept[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 truefilter[0..*]Include one or more codes from a code systeminclude[0..*]Exclude one or more codes from the value setexclude[0..*]A set of criteria that provide the content logical definition of the value set by including or excluding codes from outside this value setcompose[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 expansionparameter[0..*]Other codes and entries contained under this entry in the hierarchycontains[0..*]The codes that are contained in the value set expansioncontains[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 performedexpansion[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..* 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="[markdown]"/><!-- 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="[markdown]"/><!-- 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 -->
 <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 Text to display for this code for this value set -->
    <designation>  <!-- 0..* Additional representations for this valueset -->
     <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>
   <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 | generalizes -->
    <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" : "<markdown>", // 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" : "<markdown>", // Why needed
  "copyright" : "<string>", // Use and/or publishing restrictions
  "extensible" : <boolean>, // Whether this is intended to be used with an extensible binding
  "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>", // Text to display for this code for this value set
        "designation" : [{ // Additional representations for this valueset
          "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
        }]
      }],
      "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 | generalizes
        "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
    }]
  }
}

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .doco


[ a fhir:ValueSet;
  fhir:nodeRole fhir:treeRoot; # if this is the parser root

  # from Resource: .id, .meta, .implicitRules, and .language
  # from DomainResource: .text, .contained, .extension, and .modifierExtension
  fhir:ValueSet.url [ uri ]; # 0..1 Globally unique logical identifier for  value set
  fhir:ValueSet.identifier [ Identifier ], ... ; # 0..* Additional identifier for the value set (e.g. HL7 v2 / CDA)
  fhir:ValueSet.version [ string ]; # 0..1 Logical identifier for this version of the value set
  fhir:ValueSet.name [ string ]; # 0..1 Informal name for this value set
  fhir:ValueSet.status [ code ]; # 1..1 draft | active | retired
  fhir:ValueSet.experimental [ boolean ]; # 0..1 If for testing purposes, not real usage
  fhir:ValueSet.publisher [ string ]; # 0..1 Name of the publisher (organization or individual)
  fhir:ValueSet.contact [ # 0..* Contact details of the publisher
    fhir:ValueSet.contact.name [ string ]; # 0..1 Name of an individual to contact
    fhir:ValueSet.contact.telecom [ ContactPoint ], ... ; # 0..* Contact details for individual or publisher
  ], ...;
  fhir:ValueSet.date [ dateTime ]; # 0..1 Date for given status
  fhir:ValueSet.lockedDate [ date ]; # 0..1 Fixed date for all referenced code systems and value sets
  fhir:ValueSet.description [ markdown ]; # 0..1 Human language description of the value set
  fhir:ValueSet.useContext [ CodeableConcept ], ... ; # 0..* Content intends to support these contexts
  fhir:ValueSet.immutable [ boolean ]; # 0..1 Indicates whether or not any change to the content logical definition may occur
  fhir:ValueSet.requirements [ markdown ]; # 0..1 Why needed
  fhir:ValueSet.copyright [ string ]; # 0..1 Use and/or publishing restrictions
  fhir:ValueSet.extensible [ boolean ]; # 0..1 Whether this is intended to be used with an extensible binding
  fhir:ValueSet.compose [ # 0..1 When value set includes codes from elsewhere
    fhir:ValueSet.compose.import [ uri ], ... ; # 0..* Import the contents of another value set
    fhir:ValueSet.compose.include [ # 0..* Include one or more codes from a code system
      fhir:ValueSet.compose.include.system [ uri ]; # 1..1 The system the codes come from
      fhir:ValueSet.compose.include.version [ string ]; # 0..1 Specific version of the code system referred to
      fhir:ValueSet.compose.include.concept [ # 0..* A concept defined in the system
        fhir:ValueSet.compose.include.concept.code [ code ]; # 1..1 Code or expression from system
        fhir:ValueSet.compose.include.concept.display [ string ]; # 0..1 Text to display for this code for this value set
        fhir:ValueSet.compose.include.concept.designation [ # 0..* Additional representations for this valueset
          fhir:ValueSet.compose.include.concept.designation.language [ code ]; # 0..1 Human language of the designation
          fhir:ValueSet.compose.include.concept.designation.use [ Coding ]; # 0..1 Details how this designation would be used
          fhir:ValueSet.compose.include.concept.designation.value [ string ]; # 1..1 The text value for this designation
        ], ...;
      ], ...;
      fhir:ValueSet.compose.include.filter [ # 0..* Select codes/concepts by their properties (including relationships)
        fhir:ValueSet.compose.include.filter.property [ code ]; # 1..1 A property defined by the code system
        fhir:ValueSet.compose.include.filter.op [ code ]; # 1..1 = | is-a | is-not-a | regex | in | not-in | generalizes
        fhir:ValueSet.compose.include.filter.value [ code ]; # 1..1 Code from the system, or regex criteria
      ], ...;
    ], ...;
    fhir:ValueSet.compose.exclude [ See ValueSet.compose.include ], ... ; # 0..* Explicitly exclude codes
  ];
  fhir:ValueSet.expansion [ # 0..1 Used when the value set is "expanded"
    fhir:ValueSet.expansion.identifier [ uri ]; # 1..1 Uniquely identifies this expansion
    fhir:ValueSet.expansion.timestamp [ dateTime ]; # 1..1 Time ValueSet expansion happened
    fhir:ValueSet.expansion.total [ integer ]; # 0..1 Total number of codes in the expansion
    fhir:ValueSet.expansion.offset [ integer ]; # 0..1 Offset at which this resource starts
    fhir:ValueSet.expansion.parameter [ # 0..* Parameter that controlled the expansion process
      fhir:ValueSet.expansion.parameter.name [ string ]; # 1..1 Name as assigned by the server
      # ValueSet.expansion.parameter.value[x] : 0..1 Value of the named parameter. One of these 6
        fhir:ValueSet.expansion.parameter.valueString [ string ]
        fhir:ValueSet.expansion.parameter.valueBoolean [ boolean ]
        fhir:ValueSet.expansion.parameter.valueInteger [ integer ]
        fhir:ValueSet.expansion.parameter.valueDecimal [ decimal ]
        fhir:ValueSet.expansion.parameter.valueUri [ uri ]
        fhir:ValueSet.expansion.parameter.valueCode [ code ]
    ], ...;
    fhir:ValueSet.expansion.contains [ # 0..* Codes in the value set
      fhir:ValueSet.expansion.contains.system [ uri ]; # 0..1 System value for the code
      fhir:ValueSet.expansion.contains.abstract [ boolean ]; # 0..1 If user cannot select this entry
      fhir:ValueSet.expansion.contains.version [ string ]; # 0..1 Version in which this code/display is defined
      fhir:ValueSet.expansion.contains.code [ code ]; # 0..1 Code - if blank, this is not a selectable code
      fhir:ValueSet.expansion.contains.display [ string ]; # 0..1 User display for the concept
      fhir:ValueSet.expansion.contains.contains [ See ValueSet.expansion.contains ], ... ; # 0..* Codes contained under this entry
    ], ...;
  ];
]

Changes since DSTU2

ValueSet
ValueSet.identifier Max Cardinality changed from 1 to *
ValueSet.description Type changed from string to markdown
ValueSet.requirements Type changed from string to markdown
ValueSet.compose.include.concept.designation.language added
ValueSet.compose.include.concept.designation.use added
ValueSet.compose.include.concept.designation.value added
ValueSet.expansion.contains.abstract Default Value "false" added
ValueSet.codeSystem deleted

See the Full Difference for further information

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. ValueSet IDomainResourceA set of codes drawn from one or more code systems
A value set with only one import SHALL also have an include and/or an exclude
Value set SHALL contain at least one of a a compose, or an expansion element
... url Σ0..1uriGlobally unique logical identifier for value set
... identifier Σ0..*IdentifierAdditional identifier for the value set (e.g. HL7 v2 / CDA)
... version Σ0..1stringLogical identifier for this version of the value set
... name Σ0..1stringInformal name for this value set
... status ?!Σ1..1codedraft | active | retired
ConformanceResourceStatus (Required)
... experimental Σ0..1booleanIf for testing purposes, not real usage
... publisher Σ0..1stringName of the publisher (organization or individual)
... contact Σ0..*BackboneElementContact details of the publisher
.... name Σ0..1stringName of an individual to contact
.... telecom Σ0..*ContactPointContact details for individual or publisher
... date Σ0..1dateTimeDate for given status
... lockedDate Σ0..1dateFixed date for all referenced code systems and value sets
... description Σ0..1markdownHuman language description of the value set
... useContext Σ0..*CodeableConceptContent intends to support these contexts
Context of Use ValueSet (Extensible)
... immutable Σ0..1booleanIndicates whether or not any change to the content logical definition may occur
... requirements 0..1markdownWhy needed
... copyright 0..1stringUse and/or publishing restrictions
... extensible Σ0..1booleanWhether this is intended to be used with an extensible binding
... compose I0..1BackboneElementWhen 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..*BackboneElementInclude one or more codes from a code system
Cannot have both concept and filter
..... system Σ1..1uriThe system the codes come from
..... version Σ0..1stringSpecific version of the code system referred to
..... concept I0..*BackboneElementA concept defined in the system
...... code 1..1codeCode or expression from system
...... display 0..1stringText to display for this code for this value set
...... designation 0..*BackboneElementAdditional representations for this valueset
....... language 0..1codeHuman language of the designation
Common Languages (Extensible but limited to All Languages)
....... use 0..1CodingDetails how this designation would be used
Designation Use (Extensible)
....... value 1..1stringThe text value for this designation
..... filter I0..*BackboneElementSelect 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 | generalizes
FilterOperator (Required)
...... value 1..1codeCode from the system, or regex criteria
.... exclude I0..*see includeExplicitly exclude codes
... expansion I0..1BackboneElementUsed when the value set is "expanded"
.... identifier 1..1uriUniquely identifies this expansion
.... timestamp 1..1dateTimeTime ValueSet expansion happened
.... total 0..1integerTotal number of codes in the expansion
.... offset 0..1integerOffset at which this resource starts
.... parameter 0..*BackboneElementParameter that controlled the expansion process
..... name 1..1stringName as assigned by the server
..... value[x] 0..1Value of the named parameter
...... valueStringstring
...... valueBooleanboolean
...... valueIntegerinteger
...... valueDecimaldecimal
...... valueUriuri
...... valueCodecode
.... contains I0..*BackboneElementCodes in the value set
SHALL have a code or a display
Must have a code if not abstract
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 selectable code
..... display I0..1stringUser display for the concept
..... contains 0..*see containsCodes contained under this entry

doco Documentation for this format

UML Diagram (Legend)

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) publishedurl : uri [0..1]A 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 instanceidentifier : Identifier [0..*]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..1]A free text natural language name describing the value setname : string [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 usageexperimental : boolean [0..1]The name of the individual or organization that published the value setpublisher : 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 datelockedDate : 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 setdescription : markdown [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 definitionsuseContext : 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 changeimmutable : boolean [0..1]Explains why this value set is needed and why it has been constrained as it hasrequirements : markdown [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 setcopyright : string [0..1]Whether this is intended to be used with an extensible binding or notextensible : boolean [0..1]ContactThe name of an individual to contact regarding the value setname : string [0..1]Contact details for individual (if a name was provided) or the publishertelecom : ContactPoint [0..*]ComposeIncludes 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.urlimport : uri [0..*]ConceptSetAn absolute URI which is the code system from which the selected codes come fromsystem : uri [1..1]The version of the code system that the codes are selected fromversion : string [0..1]ConceptReferenceSpecifies a code for the concept to be included or excludedcode : 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 systemdisplay : string [0..1]DesignationThe language this designation is defined forlanguage : code [0..1] « A human language. (Strength=Extensible)Common Languages+ »A code that details how this designation would be useduse : Coding [0..1] « Details of how a designation would be used. (Strength=Extensible)Designation Use+ »The text value for this designationvalue : string [1..1]FilterA code that identifies a property defined in the code systemproperty : code [1..1]The 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 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 valuevalue : code [1..1]ExpansionAn 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 : uri [1..1]The time at which the expansion was produced by the expanding systemtimestamp : 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 parametertotal : 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 presentoffset : integer [0..1]ParameterThe name of the parametername : string [1..1]The value of the parametervalue[x] : Type [0..1] « string|boolean|integer|decimal|uri|code »ContainsAn absolute URI which is the code system in which the code for this item in the expansion is definedsystem : 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 valueabstract : 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 permanenceversion : 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 setcode : code [0..1]The recommended display for this item in the expansiondisplay : string [0..1]Contacts to assist a user in finding and communicating with the publishercontact[0..*]Additional representations for this concept when used in this value set - other languages, aliases, specialized purposes, used for particular purposes, etcdesignation[0..*]Specifies a concept to be included or excludedconcept[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 truefilter[0..*]Include one or more codes from a code systeminclude[0..*]Exclude one or more codes from the value setexclude[0..*]A set of criteria that provide the content logical definition of the value set by including or excluding codes from outside this value setcompose[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 expansionparameter[0..*]Other codes and entries contained under this entry in the hierarchycontains[0..*]The codes that are contained in the value set expansioncontains[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 performedexpansion[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..* 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="[markdown]"/><!-- 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="[markdown]"/><!-- 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 -->
 <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 Text to display for this code for this value set -->
    <designation>  <!-- 0..* Additional representations for this valueset -->
     <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>
   <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 | generalizes -->
    <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" : "<markdown>", // 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" : "<markdown>", // Why needed
  "copyright" : "<string>", // Use and/or publishing restrictions
  "extensible" : <boolean>, // Whether this is intended to be used with an extensible binding
  "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>", // Text to display for this code for this value set
        "designation" : [{ // Additional representations for this valueset
          "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
        }]
      }],
      "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 | generalizes
        "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
    }]
  }
}

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .doco


[ a fhir:ValueSet;
  fhir:nodeRole fhir:treeRoot; # if this is the parser root

  # from Resource: .id, .meta, .implicitRules, and .language
  # from DomainResource: .text, .contained, .extension, and .modifierExtension
  fhir:ValueSet.url [ uri ]; # 0..1 Globally unique logical identifier for  value set
  fhir:ValueSet.identifier [ Identifier ], ... ; # 0..* Additional identifier for the value set (e.g. HL7 v2 / CDA)
  fhir:ValueSet.version [ string ]; # 0..1 Logical identifier for this version of the value set
  fhir:ValueSet.name [ string ]; # 0..1 Informal name for this value set
  fhir:ValueSet.status [ code ]; # 1..1 draft | active | retired
  fhir:ValueSet.experimental [ boolean ]; # 0..1 If for testing purposes, not real usage
  fhir:ValueSet.publisher [ string ]; # 0..1 Name of the publisher (organization or individual)
  fhir:ValueSet.contact [ # 0..* Contact details of the publisher
    fhir:ValueSet.contact.name [ string ]; # 0..1 Name of an individual to contact
    fhir:ValueSet.contact.telecom [ ContactPoint ], ... ; # 0..* Contact details for individual or publisher
  ], ...;
  fhir:ValueSet.date [ dateTime ]; # 0..1 Date for given status
  fhir:ValueSet.lockedDate [ date ]; # 0..1 Fixed date for all referenced code systems and value sets
  fhir:ValueSet.description [ markdown ]; # 0..1 Human language description of the value set
  fhir:ValueSet.useContext [ CodeableConcept ], ... ; # 0..* Content intends to support these contexts
  fhir:ValueSet.immutable [ boolean ]; # 0..1 Indicates whether or not any change to the content logical definition may occur
  fhir:ValueSet.requirements [ markdown ]; # 0..1 Why needed
  fhir:ValueSet.copyright [ string ]; # 0..1 Use and/or publishing restrictions
  fhir:ValueSet.extensible [ boolean ]; # 0..1 Whether this is intended to be used with an extensible binding
  fhir:ValueSet.compose [ # 0..1 When value set includes codes from elsewhere
    fhir:ValueSet.compose.import [ uri ], ... ; # 0..* Import the contents of another value set
    fhir:ValueSet.compose.include [ # 0..* Include one or more codes from a code system
      fhir:ValueSet.compose.include.system [ uri ]; # 1..1 The system the codes come from
      fhir:ValueSet.compose.include.version [ string ]; # 0..1 Specific version of the code system referred to
      fhir:ValueSet.compose.include.concept [ # 0..* A concept defined in the system
        fhir:ValueSet.compose.include.concept.code [ code ]; # 1..1 Code or expression from system
        fhir:ValueSet.compose.include.concept.display [ string ]; # 0..1 Text to display for this code for this value set
        fhir:ValueSet.compose.include.concept.designation [ # 0..* Additional representations for this valueset
          fhir:ValueSet.compose.include.concept.designation.language [ code ]; # 0..1 Human language of the designation
          fhir:ValueSet.compose.include.concept.designation.use [ Coding ]; # 0..1 Details how this designation would be used
          fhir:ValueSet.compose.include.concept.designation.value [ string ]; # 1..1 The text value for this designation
        ], ...;
      ], ...;
      fhir:ValueSet.compose.include.filter [ # 0..* Select codes/concepts by their properties (including relationships)
        fhir:ValueSet.compose.include.filter.property [ code ]; # 1..1 A property defined by the code system
        fhir:ValueSet.compose.include.filter.op [ code ]; # 1..1 = | is-a | is-not-a | regex | in | not-in | generalizes
        fhir:ValueSet.compose.include.filter.value [ code ]; # 1..1 Code from the system, or regex criteria
      ], ...;
    ], ...;
    fhir:ValueSet.compose.exclude [ See ValueSet.compose.include ], ... ; # 0..* Explicitly exclude codes
  ];
  fhir:ValueSet.expansion [ # 0..1 Used when the value set is "expanded"
    fhir:ValueSet.expansion.identifier [ uri ]; # 1..1 Uniquely identifies this expansion
    fhir:ValueSet.expansion.timestamp [ dateTime ]; # 1..1 Time ValueSet expansion happened
    fhir:ValueSet.expansion.total [ integer ]; # 0..1 Total number of codes in the expansion
    fhir:ValueSet.expansion.offset [ integer ]; # 0..1 Offset at which this resource starts
    fhir:ValueSet.expansion.parameter [ # 0..* Parameter that controlled the expansion process
      fhir:ValueSet.expansion.parameter.name [ string ]; # 1..1 Name as assigned by the server
      # ValueSet.expansion.parameter.value[x] : 0..1 Value of the named parameter. One of these 6
        fhir:ValueSet.expansion.parameter.valueString [ string ]
        fhir:ValueSet.expansion.parameter.valueBoolean [ boolean ]
        fhir:ValueSet.expansion.parameter.valueInteger [ integer ]
        fhir:ValueSet.expansion.parameter.valueDecimal [ decimal ]
        fhir:ValueSet.expansion.parameter.valueUri [ uri ]
        fhir:ValueSet.expansion.parameter.valueCode [ code ]
    ], ...;
    fhir:ValueSet.expansion.contains [ # 0..* Codes in the value set
      fhir:ValueSet.expansion.contains.system [ uri ]; # 0..1 System value for the code
      fhir:ValueSet.expansion.contains.abstract [ boolean ]; # 0..1 If user cannot select this entry
      fhir:ValueSet.expansion.contains.version [ string ]; # 0..1 Version in which this code/display is defined
      fhir:ValueSet.expansion.contains.code [ code ]; # 0..1 Code - if blank, this is not a selectable code
      fhir:ValueSet.expansion.contains.display [ string ]; # 0..1 User display for the concept
      fhir:ValueSet.expansion.contains.contains [ See ValueSet.expansion.contains ], ... ; # 0..* Codes contained under this entry
    ], ...;
  ];
]

Changes since DSTU2

ValueSet
ValueSet.identifier Max Cardinality changed from 1 to *
ValueSet.description Type changed from string to markdown
ValueSet.requirements Type changed from string to markdown
ValueSet.compose.include.concept.designation.language added
ValueSet.compose.include.concept.designation.use added
ValueSet.compose.include.concept.designation.value added
ValueSet.expansion.contains.abstract Default Value "false" added
ValueSet.codeSystem deleted

See the Full Difference for further information

 

Alternate definitions: Master Definition (XML, JSON), XML Schema/Schematron (for ) + JSON Schema, ShEx (for Turtle)

4.7.4.1 Terminology Bindings

PathDefinitionTypeReference
ValueSet.status The lifecycle status of a Value Set or Concept Map.RequiredConformanceResourceStatus
ValueSet.useContext Indicates the countries, regions, disciplines and other aspects of use within which this artifact is targeted for use.ExtensibleContext of Use ValueSet
ValueSet.compose.include.concept.designation.language A human language.Extensible, but limited to All LanguagesCommon Languages
ValueSet.compose.include.concept.designation.use Details of how a designation would be used.ExtensibleDesignation Use
ValueSet.compose.include.filter.op The kind of operation to perform as a part of a property based filter.RequiredFilterOperator

4.7.4.2 Constraints

  • vsd-1: On ValueSet.compose: A value set composition SHALL have an include or an import (expression on ValueSet.compose: include.exists() or import.exists())
  • vsd-10: On ValueSet.expansion.contains: Must have a system if a code is present (expression on ValueSet.expansion.contains: code.empty() or system.exists())
  • vsd-11: On ValueSet.compose.include: Cannot have both concept and filter (expression on ValueSet.compose.include: concept.empty() or filter.empty())
  • vsd-2: A value set with only one import SHALL also have an include and/or an exclude (expression : compose.import.count() != 1 or compose.include.exists() or compose.exclude.exists())
  • vsd-5: Value set SHALL contain at least one of a a compose, or an expansion element (expression : compose.exists() or expansion.exists())
  • vsd-6: On ValueSet.expansion.contains: SHALL have a code or a display (expression on ValueSet.expansion.contains: code.exists() or display.exists())
  • vsd-9: On ValueSet.expansion.contains: Must have a code if not abstract (expression on ValueSet.expansion.contains: code.exists() or abstract = true)

4.7.5 Composition Rules

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

  • Within an include or exclude criterion, multiple filters and concept selections are intersected. All of the conditions specified SHALL be true.
  • An include statement consists of any enumerated codes and any codes that meet the filter criteria.
  • If the system reference is not version specific and filters are present, then the contents of the value set are open and change over time as the underlying code systems are updated.
  • The content of the value set is constructed by unioning of all the import and include statements and then eliminating any of the 'excluded' codes.
  • A value set needs to do something. It can't simply import an existing value set without also including additional content or excluding content.
  • Using the property filters is only possible where the code system in use defines the relevant 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
  • Value sets may include abstract codes - that is, codes designated by the underlying code system as not for use as a selectable concept in a particular context. 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 sometimes useful to define an alternative display for the code that is to be used wherever the value set is expanded and used in a UI. This facility is provided to cover the following circumstances:

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

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

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

4.7.6 Value Sets with multiple code systems

Value sets may select codes from multiple code systems - either by including codes from different systems, importing other value sets that include them. A typical use for crossing code systems is when including a set of codes, and adding a few additional codes to cover cases not catered to by the included codes (e.g. Data missing or workflow error codes).

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

4.7.6.1 Code systems Note

How filters are used with various code systems:

System Property Name Operation Value Definition Example
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)

4.7.7 Value Set Expansion

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

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

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

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

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

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

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

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

4.7.8 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
contexttokenA use context assigned to the value setValueSet.useContext
datedateThe value set publication dateValueSet.date
descriptionstringText search in the description of the value setValueSet.description
expansionuriUniquely identifies this expansionValueSet.expansion.identifier
identifiertokenThe identifier for the value setValueSet.identifier
namestringThe name of the value setValueSet.name
publisherstringName of the publisher of the value setValueSet.publisher
referenceuriA code system included or excluded in the value set or an imported value setValueSet.compose.include.system
statustokenThe status of the value setValueSet.status
urluriThe logical URL for the value setValueSet.url
versiontokenThe version identifier of the value setValueSet.version