• 主要内容
• 示例
• 详细介绍
• 映射
• 配置 & 扩展
• 操作
• R3区别

4.9 ValueSet 资源 - 主要内容

工作组: Vocabulary

成熟度: N

Normative (from v4.0.0)

Security Category: Anonymous

Compartments: Not linked to any defined compartments

ValueSet资源从一个或多个编码系统中提取一组编码作为一个值域集的实例，用于特定场景中。 值域集将编码系统的定义和使用(详见在资源中使用编码)关联起来。

此资源由以下资源引用： DataRequirement, ElementDefinition, CodeSystem, ConceptMap, ObservationDefinition, OperationDefinition, Questionnaire, ResearchElementDefinition and itself

4.9.4 资源内容

• 结构
• UML
• XML
• JSON
• Turtle
• R3区别
• 所有

结构

名称	标志	基数	类型	描述 & 约束
ValueSet	IN		DomainResource	A set of codes drawn from one or more code systems + Warning: Name should be usable as an identifier for the module by machine processing applications such as code generation Elements defined in Ancestors: id, meta, implicitRules, language, text, contained, extension, modifierExtension
url	Σ	0..1	uri	Canonical identifier for this value set, represented as a URI (globally unique)
identifier	Σ	0..*	Identifier	Additional identifier for the value set (business identifier)
version	Σ	0..1	string	Business version of the value set
name	ΣI	0..1	string	Name for this value set (computer friendly)
title	Σ	0..1	string	Name for this value set (human friendly)
status	?!Σ	1..1	code	draft | active | retired | unknown PublicationStatus (Required)
experimental	Σ	0..1	boolean	For testing purposes, not real usage
date	Σ	0..1	dateTime	Date last changed
publisher	Σ	0..1	string	Name of the publisher (organization or individual)
contact	Σ	0..*	ContactDetail	Contact details for the publisher
description		0..1	markdown	Natural language description of the value set
useContext	ΣTU	0..*	UsageContext	The context that the content is intended to support
jurisdiction	Σ	0..*	CodeableConcept	Intended jurisdiction for value set (if applicable) Jurisdiction (Extensible)
immutable	Σ	0..1	boolean	Indicates whether or not any change to the content logical definition may occur
purpose		0..1	markdown	Why this value set is defined
copyright		0..1	markdown	Use and/or publishing restrictions
compose		0..1	BackboneElement	Content logical definition of the value set (CLD)
lockedDate	Σ	0..1	date	Fixed date for references with no specified version (transitive)
inactive	Σ	0..1	boolean	Whether inactive codes are in the value set
include	ΣI	1..*	BackboneElement	Include one or more codes from a code system or other value set(s) + Rule: A value set include/exclude SHALL have a value set or a system + Rule: A value set with concepts or filters SHALL include a system + Rule: Cannot have both concept and filter
system	ΣI	0..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	Text to display for this code for this value set in this valueset
designation		0..*	BackboneElement	Additional representations for this concept
language		0..1	code	Human language of the designation Common Languages (Preferred but limited to AllLanguages)
use		0..1	Coding	Types of uses of designations Designation Use (Extensible)
value		1..1	string	The text value for this designation
filter	ΣI	0..*	BackboneElement	Select codes/concepts by their properties (including relationships)
property	Σ	1..1	code	A property/filter defined by the code system
op	Σ	1..1	code	= | is-a | descendent-of | is-not-a | regex | in | not-in | generalizes | exists FilterOperator (Required)
value	Σ	1..1	string	Code from the system, or regex criteria, or boolean value for exists
valueSet	ΣI	0..*	canonical(ValueSet)	选择此值域集中包含的内容
exclude	I	0..*	see include	Explicitly exclude codes from a code system or other value sets
expansion		0..1	BackboneElement	Used when the value set is "expanded"
identifier		0..1	uri	Identifies the value set expansion (business identifier)
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 client or server
value[x]		0..1		Value of the named parameter
valueString			string
valueBoolean			boolean
valueInteger			integer
valueDecimal			decimal
valueUri			uri
valueCode			code
valueDateTime			dateTime
contains	I	0..*	BackboneElement	Codes in the value set + Rule: SHALL have a code or a display + Rule: Must have a code if not abstract + Rule: 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
inactive		0..1	boolean	If concept is inactive in the code system
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
designation		0..*	see designation	Additional representations for this item
contains		0..*	see contains	Codes contained under this entry
Documentation for this format

UML Diagram (Legend)

XML Template

<ValueSet xmlns="http://hl7.org/fhir"> 
 <!-- from Resource: id, meta, implicitRules, and language -->
 <!-- from DomainResource: text, contained, extension, and modifierExtension -->
 <url value="[uri]"/><!-- 0..1 Canonical identifier for this value set, represented as a URI (globally unique) -->
 <identifier><!-- 0..* Identifier Additional identifier for the value set (business identifier) --></identifier>
 <version value="[string]"/><!-- 0..1 Business version of the value set -->
 <name value="[string]"/><!--  0..1 Name for this value set (computer friendly) -->
 <title value="[string]"/><!-- 0..1 Name for this value set (human friendly) -->
 <status value="[code]"/><!-- 1..1 draft | active | retired | unknown -->
 <experimental value="[boolean]"/><!-- 0..1 For testing purposes, not real usage -->
 <date value="[dateTime]"/><!-- 0..1 Date last changed -->
 <publisher value="[string]"/><!-- 0..1 Name of the publisher (organization or individual) -->
 <contact><!-- 0..* ContactDetail Contact details for the publisher --></contact>
 <description value="[markdown]"/><!-- 0..1 Natural language description of the value set -->
 <useContext><!-- 0..* UsageContext The context that the content is intended to support --></useContext>
 <jurisdiction><!-- 0..* CodeableConcept Intended jurisdiction for value set (if applicable) --></jurisdiction>
 <immutable value="[boolean]"/><!-- 0..1 Indicates whether or not any change to the content logical definition may occur -->
 <purpose value="[markdown]"/><!-- 0..1 Why this value set is defined -->
 <copyright value="[markdown]"/><!-- 0..1 Use and/or publishing restrictions -->
 <compose>  <!-- 0..1 Content logical definition of the value set (CLD) -->
  <lockedDate value="[date]"/><!-- 0..1 Fixed date for references with no specified version (transitive) -->
  <inactive value="[boolean]"/><!-- 0..1 Whether inactive codes are in the value set -->
  <include>  <!-- 1..* Include one or more codes from a code system or other value set(s) -->
   <system value="[uri]"/><!--  0..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 in this valueset -->
    <designation>  <!-- 0..* Additional representations for this concept -->
     <language value="[code]"/><!-- 0..1 Human language of the designation -->
     <use><!-- 0..1 Coding Types of uses of designations --></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/filter defined by the code system -->
    <op value="[code]"/><!-- 1..1 = | is-a | descendent-of | is-not-a | regex | in | not-in | generalizes | exists -->
    <value value="[string]"/><!-- 1..1 Code from the system, or regex criteria, or boolean value for exists -->
   </filter>
   <valueSet><!--  0..* canonical(ValueSet) 选择此值域集中包含的内容 --></valueSet>
  </include>
  <exclude><!--  0..* Content as for ValueSet.compose.include Explicitly exclude codes from a code system or other value sets --></exclude>
 </compose>
 <expansion>  <!-- 0..1 Used when the value set is "expanded" -->
  <identifier value="[uri]"/><!-- 0..1 Identifies the value set expansion (business identifier) -->
  <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 client or server -->
   <value[x]><!-- 0..1 string|boolean|integer|decimal|uri|code|dateTime 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 -->
   <inactive value="[boolean]"/><!-- 0..1 If concept is inactive in the code system -->
   <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 -->
   <designation><!-- 0..* Content as for ValueSet.compose.include.concept.designation Additional representations for this item --></designation>
   <contains><!-- 0..* Content as for ValueSet.expansion.contains Codes contained under this entry --></contains>
  </contains>
 </expansion>
</ValueSet>

JSON Template

{
  "resourceType" : "ValueSet",
  // from Resource: id, meta, implicitRules, and language
  // from DomainResource: text, contained, extension, and modifierExtension
  "url" : "<uri>", // Canonical identifier for this value set, represented as a URI (globally unique)
  "identifier" : [{ Identifier }], // Additional identifier for the value set (business identifier)
  "version" : "<string>", // Business version of the value set
  "name" : "<string>", // C? Name for this value set (computer friendly)
  "title" : "<string>", // Name for this value set (human friendly)
  "status" : "<code>", // R!  draft | active | retired | unknown
  "experimental" : <boolean>, // For testing purposes, not real usage
  "date" : "<dateTime>", // Date last changed
  "publisher" : "<string>", // Name of the publisher (organization or individual)
  "contact" : [{ ContactDetail }], // Contact details for the publisher
  "description" : "<markdown>", // Natural language description of the value set
  "useContext" : [{ UsageContext }], // The context that the content is intended to support
  "jurisdiction" : [{ CodeableConcept }], // Intended jurisdiction for value set (if applicable)
  "immutable" : <boolean>, // Indicates whether or not any change to the content logical definition may occur
  "purpose" : "<markdown>", // Why this value set is defined
  "copyright" : "<markdown>", // Use and/or publishing restrictions
  "compose" : { // Content logical definition of the value set (CLD)
    "lockedDate" : "<date>", // Fixed date for references with no specified version (transitive)
    "inactive" : <boolean>, // Whether inactive codes are in the value set
    "include" : [{ // R!  Include one or more codes from a code system or other value set(s)
      "system" : "<uri>", // C? 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 in this valueset
        "designation" : [{ // Additional representations for this concept
          "language" : "<code>", // Human language of the designation
          "use" : { Coding }, // Types of uses of designations
          "value" : "<string>" // R!  The text value for this designation
        }]
      }],
      "filter" : [{ // C? Select codes/concepts by their properties (including relationships)
        "property" : "<code>", // R!  A property/filter defined by the code system
        "op" : "<code>", // R!  = | is-a | descendent-of | is-not-a | regex | in | not-in | generalizes | exists
        "value" : "<string>" // R!  Code from the system, or regex criteria, or boolean value for exists
      }],
      "valueSet" : [{ canonical(ValueSet) }] // C? 选择此值域集中包含的内容
    }],
    "exclude" : [{ Content as for ValueSet.compose.include }] // C? Explicitly exclude codes from a code system or other value sets
  },
  "expansion" : { // Used when the value set is "expanded"
    "identifier" : "<uri>", // Identifies the value set expansion (business identifier)
    "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 client or server
      // value[x]: Value of the named parameter. One of these 7:
      "valueString" : "<string>"
      "valueBoolean" : <boolean>
      "valueInteger" : <integer>
      "valueDecimal" : <decimal>
      "valueUri" : "<uri>"
      "valueCode" : "<code>"
      "valueDateTime" : "<dateTime>"
    }],
    "contains" : [{ // Codes in the value set
      "system" : "<uri>", // System value for the code
      "abstract" : <boolean>, // If user cannot select this entry
      "inactive" : <boolean>, // If concept is inactive in the code system
      "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
      "designation" : [{ Content as for ValueSet.compose.include.concept.designation }], // Additional representations for this item
      "contains" : [{ Content as for ValueSet.expansion.contains }] // Codes contained under this entry
    }]
  }
}

Turtle Template

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


[ 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 Canonical identifier for this value set, represented as a URI (globally unique)
  fhir:ValueSet.identifier [ Identifier ], ... ; # 0..* Additional identifier for the value set (business identifier)
  fhir:ValueSet.version [ string ]; # 0..1 Business version of the value set
  fhir:ValueSet.name [ string ]; # 0..1 Name for this value set (computer friendly)
  fhir:ValueSet.title [ string ]; # 0..1 Name for this value set (human friendly)
  fhir:ValueSet.status [ code ]; # 1..1 draft | active | retired | unknown
  fhir:ValueSet.experimental [ boolean ]; # 0..1 For testing purposes, not real usage
  fhir:ValueSet.date [ dateTime ]; # 0..1 Date last changed
  fhir:ValueSet.publisher [ string ]; # 0..1 Name of the publisher (organization or individual)
  fhir:ValueSet.contact [ ContactDetail ], ... ; # 0..* Contact details for the publisher
  fhir:ValueSet.description [ markdown ]; # 0..1 Natural language description of the value set
  fhir:ValueSet.useContext [ UsageContext ], ... ; # 0..* The context that the content is intended to support
  fhir:ValueSet.jurisdiction [ CodeableConcept ], ... ; # 0..* Intended jurisdiction for value set (if applicable)
  fhir:ValueSet.immutable [ boolean ]; # 0..1 Indicates whether or not any change to the content logical definition may occur
  fhir:ValueSet.purpose [ markdown ]; # 0..1 Why this value set is defined
  fhir:ValueSet.copyright [ markdown ]; # 0..1 Use and/or publishing restrictions
  fhir:ValueSet.compose [ # 0..1 Content logical definition of the value set (CLD)
    fhir:ValueSet.compose.lockedDate [ date ]; # 0..1 Fixed date for references with no specified version (transitive)
    fhir:ValueSet.compose.inactive [ boolean ]; # 0..1 Whether inactive codes are in the value set
    fhir:ValueSet.compose.include [ # 1..* Include one or more codes from a code system or other value set(s)
      fhir:ValueSet.compose.include.system [ uri ]; # 0..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 in this valueset
        fhir:ValueSet.compose.include.concept.designation [ # 0..* Additional representations for this concept
          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 Types of uses of designations
          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/filter defined by the code system
        fhir:ValueSet.compose.include.filter.op [ code ]; # 1..1 = | is-a | descendent-of | is-not-a | regex | in | not-in | generalizes | exists
        fhir:ValueSet.compose.include.filter.value [ string ]; # 1..1 Code from the system, or regex criteria, or boolean value for exists
      ], ...;
      fhir:ValueSet.compose.include.valueSet [ canonical(ValueSet) ], ... ; # 0..* 选择此值域集中包含的内容
    ], ...;
    fhir:ValueSet.compose.exclude [ See ValueSet.compose.include ], ... ; # 0..* Explicitly exclude codes from a code system or other value sets
  ];
  fhir:ValueSet.expansion [ # 0..1 Used when the value set is "expanded"
    fhir:ValueSet.expansion.identifier [ uri ]; # 0..1 Identifies the value set expansion (business identifier)
    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 client or server
      # ValueSet.expansion.parameter.value[x] : 0..1 Value of the named parameter. One of these 7
        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.parameter.valueDateTime [ dateTime ]
    ], ...;
    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.inactive [ boolean ]; # 0..1 If concept is inactive in the code system
      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.designation [ See ValueSet.compose.include.concept.designation ], ... ; # 0..* Additional representations for this item
      fhir:ValueSet.expansion.contains.contains [ See ValueSet.expansion.contains ], ... ; # 0..* Codes contained under this entry
    ], ...;
  ];
]

Changes since R3

ValueSet
ValueSet.status	Change value set from http://hl7.org/fhir/ValueSet/publication-status to http://hl7.org/fhir/ValueSet/publication-status|4.0.0
ValueSet.experimental	No longer marked as Modifier
ValueSet.compose.include.concept.designation.language	Change binding strength from extensible to preferred
ValueSet.compose.include.filter	No longer marked as Modifier
ValueSet.compose.include.filter.op	Change value set from http://hl7.org/fhir/ValueSet/filter-operator to http://hl7.org/fhir/ValueSet/filter-operator|4.0.0
ValueSet.compose.include.filter.value	Type changed from code to string
ValueSet.compose.include.valueSet	Type changed from uri to canonical(ValueSet)
ValueSet.expansion.identifier	Min Cardinality changed from 1 to 0
ValueSet.expansion.parameter.value[x]	Add Type dateTime
ValueSet.expansion.contains.abstract	Default Value "false" removed
ValueSet.expansion.contains.inactive	Default Value "false" removed
ValueSet.extensible	deleted

See the Full Difference for further information

This analysis is available as XML or JSON.

See R3 <--> R4 Conversion Maps (status = 8 tests that all execute ok. All tests pass round-trip testing and 8 r3 resources are invalid (0 errors).)

Structure

Name	Flags	Card.	Type	Description & Constraints
ValueSet	IN		DomainResource	A set of codes drawn from one or more code systems + Warning: Name should be usable as an identifier for the module by machine processing applications such as code generation Elements defined in Ancestors: id, meta, implicitRules, language, text, contained, extension, modifierExtension
url	Σ	0..1	uri	Canonical identifier for this value set, represented as a URI (globally unique)
identifier	Σ	0..*	Identifier	Additional identifier for the value set (business identifier)
version	Σ	0..1	string	Business version of the value set
name	ΣI	0..1	string	Name for this value set (computer friendly)
title	Σ	0..1	string	Name for this value set (human friendly)
status	?!Σ	1..1	code	draft | active | retired | unknown PublicationStatus (Required)
experimental	Σ	0..1	boolean	For testing purposes, not real usage
date	Σ	0..1	dateTime	Date last changed
publisher	Σ	0..1	string	Name of the publisher (organization or individual)
contact	Σ	0..*	ContactDetail	Contact details for the publisher
description		0..1	markdown	Natural language description of the value set
useContext	ΣTU	0..*	UsageContext	The context that the content is intended to support
jurisdiction	Σ	0..*	CodeableConcept	Intended jurisdiction for value set (if applicable) Jurisdiction (Extensible)
immutable	Σ	0..1	boolean	Indicates whether or not any change to the content logical definition may occur
purpose		0..1	markdown	Why this value set is defined
copyright		0..1	markdown	Use and/or publishing restrictions
compose		0..1	BackboneElement	Content logical definition of the value set (CLD)
lockedDate	Σ	0..1	date	Fixed date for references with no specified version (transitive)
inactive	Σ	0..1	boolean	Whether inactive codes are in the value set
include	ΣI	1..*	BackboneElement	Include one or more codes from a code system or other value set(s) + Rule: A value set include/exclude SHALL have a value set or a system + Rule: A value set with concepts or filters SHALL include a system + Rule: Cannot have both concept and filter
system	ΣI	0..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	Text to display for this code for this value set in this valueset
designation		0..*	BackboneElement	Additional representations for this concept
language		0..1	code	Human language of the designation Common Languages (Preferred but limited to AllLanguages)
use		0..1	Coding	Types of uses of designations Designation Use (Extensible)
value		1..1	string	The text value for this designation
filter	ΣI	0..*	BackboneElement	Select codes/concepts by their properties (including relationships)
property	Σ	1..1	code	A property/filter defined by the code system
op	Σ	1..1	code	= | is-a | descendent-of | is-not-a | regex | in | not-in | generalizes | exists FilterOperator (Required)
value	Σ	1..1	string	Code from the system, or regex criteria, or boolean value for exists
valueSet	ΣI	0..*	canonical(ValueSet)	选择此值域集中包含的内容
exclude	I	0..*	see include	Explicitly exclude codes from a code system or other value sets
expansion		0..1	BackboneElement	Used when the value set is "expanded"
identifier		0..1	uri	Identifies the value set expansion (business identifier)
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 client or server
value[x]		0..1		Value of the named parameter
valueString			string
valueBoolean			boolean
valueInteger			integer
valueDecimal			decimal
valueUri			uri
valueCode			code
valueDateTime			dateTime
contains	I	0..*	BackboneElement	Codes in the value set + Rule: SHALL have a code or a display + Rule: Must have a code if not abstract + Rule: 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
inactive		0..1	boolean	If concept is inactive in the code system
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
designation		0..*	see designation	Additional representations for this item
contains		0..*	see contains	Codes contained under this entry
Documentation for this format

UML Diagram (Legend)

XML Template

<ValueSet xmlns="http://hl7.org/fhir"> 
 <!-- from Resource: id, meta, implicitRules, and language -->
 <!-- from DomainResource: text, contained, extension, and modifierExtension -->
 <url value="[uri]"/><!-- 0..1 Canonical identifier for this value set, represented as a URI (globally unique) -->
 <identifier><!-- 0..* Identifier Additional identifier for the value set (business identifier) --></identifier>
 <version value="[string]"/><!-- 0..1 Business version of the value set -->
 <name value="[string]"/><!--  0..1 Name for this value set (computer friendly) -->
 <title value="[string]"/><!-- 0..1 Name for this value set (human friendly) -->
 <status value="[code]"/><!-- 1..1 draft | active | retired | unknown -->
 <experimental value="[boolean]"/><!-- 0..1 For testing purposes, not real usage -->
 <date value="[dateTime]"/><!-- 0..1 Date last changed -->
 <publisher value="[string]"/><!-- 0..1 Name of the publisher (organization or individual) -->
 <contact><!-- 0..* ContactDetail Contact details for the publisher --></contact>
 <description value="[markdown]"/><!-- 0..1 Natural language description of the value set -->
 <useContext><!-- 0..* UsageContext The context that the content is intended to support --></useContext>
 <jurisdiction><!-- 0..* CodeableConcept Intended jurisdiction for value set (if applicable) --></jurisdiction>
 <immutable value="[boolean]"/><!-- 0..1 Indicates whether or not any change to the content logical definition may occur -->
 <purpose value="[markdown]"/><!-- 0..1 Why this value set is defined -->
 <copyright value="[markdown]"/><!-- 0..1 Use and/or publishing restrictions -->
 <compose>  <!-- 0..1 Content logical definition of the value set (CLD) -->
  <lockedDate value="[date]"/><!-- 0..1 Fixed date for references with no specified version (transitive) -->
  <inactive value="[boolean]"/><!-- 0..1 Whether inactive codes are in the value set -->
  <include>  <!-- 1..* Include one or more codes from a code system or other value set(s) -->
   <system value="[uri]"/><!--  0..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 in this valueset -->
    <designation>  <!-- 0..* Additional representations for this concept -->
     <language value="[code]"/><!-- 0..1 Human language of the designation -->
     <use><!-- 0..1 Coding Types of uses of designations --></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/filter defined by the code system -->
    <op value="[code]"/><!-- 1..1 = | is-a | descendent-of | is-not-a | regex | in | not-in | generalizes | exists -->
    <value value="[string]"/><!-- 1..1 Code from the system, or regex criteria, or boolean value for exists -->
   </filter>
   <valueSet><!--  0..* canonical(ValueSet) 选择此值域集中包含的内容 --></valueSet>
  </include>
  <exclude><!--  0..* Content as for ValueSet.compose.include Explicitly exclude codes from a code system or other value sets --></exclude>
 </compose>
 <expansion>  <!-- 0..1 Used when the value set is "expanded" -->
  <identifier value="[uri]"/><!-- 0..1 Identifies the value set expansion (business identifier) -->
  <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 client or server -->
   <value[x]><!-- 0..1 string|boolean|integer|decimal|uri|code|dateTime 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 -->
   <inactive value="[boolean]"/><!-- 0..1 If concept is inactive in the code system -->
   <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 -->
   <designation><!-- 0..* Content as for ValueSet.compose.include.concept.designation Additional representations for this item --></designation>
   <contains><!-- 0..* Content as for ValueSet.expansion.contains Codes contained under this entry --></contains>
  </contains>
 </expansion>
</ValueSet>

JSON Template

{
  "resourceType" : "ValueSet",
  // from Resource: id, meta, implicitRules, and language
  // from DomainResource: text, contained, extension, and modifierExtension
  "url" : "<uri>", // Canonical identifier for this value set, represented as a URI (globally unique)
  "identifier" : [{ Identifier }], // Additional identifier for the value set (business identifier)
  "version" : "<string>", // Business version of the value set
  "name" : "<string>", // C? Name for this value set (computer friendly)
  "title" : "<string>", // Name for this value set (human friendly)
  "status" : "<code>", // R!  draft | active | retired | unknown
  "experimental" : <boolean>, // For testing purposes, not real usage
  "date" : "<dateTime>", // Date last changed
  "publisher" : "<string>", // Name of the publisher (organization or individual)
  "contact" : [{ ContactDetail }], // Contact details for the publisher
  "description" : "<markdown>", // Natural language description of the value set
  "useContext" : [{ UsageContext }], // The context that the content is intended to support
  "jurisdiction" : [{ CodeableConcept }], // Intended jurisdiction for value set (if applicable)
  "immutable" : <boolean>, // Indicates whether or not any change to the content logical definition may occur
  "purpose" : "<markdown>", // Why this value set is defined
  "copyright" : "<markdown>", // Use and/or publishing restrictions
  "compose" : { // Content logical definition of the value set (CLD)
    "lockedDate" : "<date>", // Fixed date for references with no specified version (transitive)
    "inactive" : <boolean>, // Whether inactive codes are in the value set
    "include" : [{ // R!  Include one or more codes from a code system or other value set(s)
      "system" : "<uri>", // C? 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 in this valueset
        "designation" : [{ // Additional representations for this concept
          "language" : "<code>", // Human language of the designation
          "use" : { Coding }, // Types of uses of designations
          "value" : "<string>" // R!  The text value for this designation
        }]
      }],
      "filter" : [{ // C? Select codes/concepts by their properties (including relationships)
        "property" : "<code>", // R!  A property/filter defined by the code system
        "op" : "<code>", // R!  = | is-a | descendent-of | is-not-a | regex | in | not-in | generalizes | exists
        "value" : "<string>" // R!  Code from the system, or regex criteria, or boolean value for exists
      }],
      "valueSet" : [{ canonical(ValueSet) }] // C? 选择此值域集中包含的内容
    }],
    "exclude" : [{ Content as for ValueSet.compose.include }] // C? Explicitly exclude codes from a code system or other value sets
  },
  "expansion" : { // Used when the value set is "expanded"
    "identifier" : "<uri>", // Identifies the value set expansion (business identifier)
    "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 client or server
      // value[x]: Value of the named parameter. One of these 7:
      "valueString" : "<string>"
      "valueBoolean" : <boolean>
      "valueInteger" : <integer>
      "valueDecimal" : <decimal>
      "valueUri" : "<uri>"
      "valueCode" : "<code>"
      "valueDateTime" : "<dateTime>"
    }],
    "contains" : [{ // Codes in the value set
      "system" : "<uri>", // System value for the code
      "abstract" : <boolean>, // If user cannot select this entry
      "inactive" : <boolean>, // If concept is inactive in the code system
      "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
      "designation" : [{ Content as for ValueSet.compose.include.concept.designation }], // Additional representations for this item
      "contains" : [{ Content as for ValueSet.expansion.contains }] // Codes contained under this entry
    }]
  }
}

Turtle Template

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


[ 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 Canonical identifier for this value set, represented as a URI (globally unique)
  fhir:ValueSet.identifier [ Identifier ], ... ; # 0..* Additional identifier for the value set (business identifier)
  fhir:ValueSet.version [ string ]; # 0..1 Business version of the value set
  fhir:ValueSet.name [ string ]; # 0..1 Name for this value set (computer friendly)
  fhir:ValueSet.title [ string ]; # 0..1 Name for this value set (human friendly)
  fhir:ValueSet.status [ code ]; # 1..1 draft | active | retired | unknown
  fhir:ValueSet.experimental [ boolean ]; # 0..1 For testing purposes, not real usage
  fhir:ValueSet.date [ dateTime ]; # 0..1 Date last changed
  fhir:ValueSet.publisher [ string ]; # 0..1 Name of the publisher (organization or individual)
  fhir:ValueSet.contact [ ContactDetail ], ... ; # 0..* Contact details for the publisher
  fhir:ValueSet.description [ markdown ]; # 0..1 Natural language description of the value set
  fhir:ValueSet.useContext [ UsageContext ], ... ; # 0..* The context that the content is intended to support
  fhir:ValueSet.jurisdiction [ CodeableConcept ], ... ; # 0..* Intended jurisdiction for value set (if applicable)
  fhir:ValueSet.immutable [ boolean ]; # 0..1 Indicates whether or not any change to the content logical definition may occur
  fhir:ValueSet.purpose [ markdown ]; # 0..1 Why this value set is defined
  fhir:ValueSet.copyright [ markdown ]; # 0..1 Use and/or publishing restrictions
  fhir:ValueSet.compose [ # 0..1 Content logical definition of the value set (CLD)
    fhir:ValueSet.compose.lockedDate [ date ]; # 0..1 Fixed date for references with no specified version (transitive)
    fhir:ValueSet.compose.inactive [ boolean ]; # 0..1 Whether inactive codes are in the value set
    fhir:ValueSet.compose.include [ # 1..* Include one or more codes from a code system or other value set(s)
      fhir:ValueSet.compose.include.system [ uri ]; # 0..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 in this valueset
        fhir:ValueSet.compose.include.concept.designation [ # 0..* Additional representations for this concept
          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 Types of uses of designations
          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/filter defined by the code system
        fhir:ValueSet.compose.include.filter.op [ code ]; # 1..1 = | is-a | descendent-of | is-not-a | regex | in | not-in | generalizes | exists
        fhir:ValueSet.compose.include.filter.value [ string ]; # 1..1 Code from the system, or regex criteria, or boolean value for exists
      ], ...;
      fhir:ValueSet.compose.include.valueSet [ canonical(ValueSet) ], ... ; # 0..* 选择此值域集中包含的内容
    ], ...;
    fhir:ValueSet.compose.exclude [ See ValueSet.compose.include ], ... ; # 0..* Explicitly exclude codes from a code system or other value sets
  ];
  fhir:ValueSet.expansion [ # 0..1 Used when the value set is "expanded"
    fhir:ValueSet.expansion.identifier [ uri ]; # 0..1 Identifies the value set expansion (business identifier)
    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 client or server
      # ValueSet.expansion.parameter.value[x] : 0..1 Value of the named parameter. One of these 7
        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.parameter.valueDateTime [ dateTime ]
    ], ...;
    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.inactive [ boolean ]; # 0..1 If concept is inactive in the code system
      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.designation [ See ValueSet.compose.include.concept.designation ], ... ; # 0..* Additional representations for this item
      fhir:ValueSet.expansion.contains.contains [ See ValueSet.expansion.contains ], ... ; # 0..* Codes contained under this entry
    ], ...;
  ];
]

Changes since Release 3

ValueSet
ValueSet.status	Change value set from http://hl7.org/fhir/ValueSet/publication-status to http://hl7.org/fhir/ValueSet/publication-status|4.0.0
ValueSet.experimental	No longer marked as Modifier
ValueSet.compose.include.concept.designation.language	Change binding strength from extensible to preferred
ValueSet.compose.include.filter	No longer marked as Modifier
ValueSet.compose.include.filter.op	Change value set from http://hl7.org/fhir/ValueSet/filter-operator to http://hl7.org/fhir/ValueSet/filter-operator|4.0.0
ValueSet.compose.include.filter.value	Type changed from code to string
ValueSet.compose.include.valueSet	Type changed from uri to canonical(ValueSet)
ValueSet.expansion.identifier	Min Cardinality changed from 1 to 0
ValueSet.expansion.parameter.value[x]	Add Type dateTime
ValueSet.expansion.contains.abstract	Default Value "false" removed
ValueSet.expansion.contains.inactive	Default Value "false" removed
ValueSet.extensible	deleted

See the Full Difference for further information

This analysis is available as XML or JSON.

See R3 <--> R4 Conversion Maps (status = 8 tests that all execute ok. All tests pass round-trip testing and 8 r3 resources are invalid (0 errors).)

See the Profiles & Extensions and the alternate definitions: Master Definition XML + JSON, XML Schema/Schematron + JSON Schema, ShEx (for Turtle) + see the extensions & the dependency analysis

4.9.4.1 Terminology Bindings

4.9.4.2 Constraints

4.9.5 组合规则

值域集可以是包含编码的简单列表，也可以是利用编码系统特性表示的某种通用选择标准。选择标准规则如下：

• 若声明了多个include元素，则意味着累加所有编码，即，值域集将选取所有include的并集。
• 在同一个include中定义的所有标准都需要同时满足，例如，选取多个筛选器结果的交集
• 在同一个include中，可以同时指定一个编码系统（可指定选择条件）和多个值域集。
• 如果同时指定了System和ValueSet ，则选取编码系统中符合concept和filter标准的所有编码与所有值域集的所有编码的并集。
• 如果仅指定了ValueSet，则将所有指定的值域集中的所有编码都选取到此值域集中。
• 如果仅指定了System，则选取规则如下：
  • 未指定concept或filter：包括系统中的所有编码
  • 指定了concept:：仅选取列举出来的具体编码
  • 指定了filter: 选取所有符合筛选条件的编码
  • 不能同时指定concept和filter
• 如果引用的编码系统没有指定版本，并且提供了筛选器，则值域集的内容将是开放的，即：随着依赖的编码系统的更新而变化。
• 如果将版本指定为特殊值“*”，这表示该值域集包含编码系统所有版本编码的并集。至于如何处理指定的所需版本、生成哪些展开结果、如何处理不同版本之间编码意义发生改变的情况都是由服务器决定的。

  重要提示: 是否支持此能力需要参照服务器发布的实施指南中的符合性声明 .

• 使用属性筛选器的前提是在编码系统中先定义了相关属性。请注意，在某些情况下，底层编码系统仅定义了逻辑概念，而没有定义使用这些概念的文字，这些文字定义可能由第三方提供。
• 除了include规则外，还可以使用exclude来排除编码。exclude与include的使用规则相同，但意义相反，即满足exclude条件的编码不会选取到值域集里
• 值域集可以包括抽象编码，抽象编码可以通过枚举底层编码系统的编码或使用筛选器来指定，通常用于分组和搜索，而不会选取出来作为值域使用。
• 必须处理compose.exclude中的内容，以确保其排除的编码不会出现在值域集的展开结果中。

4.9.6 Display and Designations

Concepts used in ValueSets can have a display, which is a short text that represents the meaning of the concept to human users in the context of the value set (which often has narrower meaning and therefore is amenable to shorter displays. If a display is not provided, the value set uses the display from the code system (which is the preferred approach, because overriding the display can lead to very unsafe outcomes).

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.

Any display name for a concept provided in the value set is for display to a human user. The display in the Coding that results from a user selecting a concept from the expansion must be taken from the underlying code system definition, even if a value set is referenced explicitly in the Coding (e.g. by an extension). The correct display for a code can be determined by a $lookup operation. Any alternative display specified in the value set would go in CodeableConcept.text, perhaps appended to the UI label for the matching data element.

{
  "resourceType" : "ValueSet",
  "compose" : {
    "include" : [{
      "system" : "http://loinc.org",
      "concept" : [{
        "code" : "55423-8",
        "display" : "Step Count"
      }]
    }]
  }
}

{
  "resourceType" : "ValueSet",
  "expansion" : {
    "contains" : [{
      "system" : "http://loinc.org",
      "code" : "55423-8",
      "display" : "Step Count"
    }]
  }
}

{
  "resourceType" : "Observation",
  "code" : {
    "coding" : [{
      "system" : "http://loinc.org",
      "code" : "55423-8",
      "display" : "Number of steps in unspecified time Pedometer"
    }],
    "text" : "Step Count"
  }
}

{
  "resourceType" : "ValueSet",
  "expansion" : {
    "contains" : [{
      "system" : "http://loinc.org",
      "code" : "55423-8",
      "display" : "Step Count",
      "designation" : [{
        "use" : {
          "system" : "http://snomed.info/sct",
          "code" : "900000000000003001"
        },
        "value" : "Number of steps in unspecified time Pedometer"
      }]
    }]
  }
}

In addition to the display, a concept can have one or more designation elements. The display is equivalent to a special designation with an implied designation.use of "primary code" and a language equal to the Resource Language. The designations can provide additional displays for other languages, as well as designations for other purposes. When using concepts, applications use the display unless the language or usage in context provides a reason to use one of the designations.

4.9.7 Value Sets with multiple code systems

Value sets may select codes from multiple code systems - either by including codes from different systems, or 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.

Value sets should only include well differentiated concepts, but many value sets and code systems do not have well differentiated concepts because of various real world constraints.

4.9.7.1 Code systems Note

Each Code System defines which filters can be used in ValueSet.compose.include.filter. All code systems have base filters and any additional filters defined in (CodeSystem.filter).

This specification also defines filters for various published code systems:

• LOINC Filters
• Using CT Filters
• RxNorm Filters
• UCUM Filters
• Using Metathesaurus Filters
• CPT Filters
• NDF-RT Filters

4.9.8 Value Set Expansion

A value set can be "expanded", where the definition of the value set is used to create a simple collection of codes suitable for use for data entry or validation. There is a defined operation $expand to ask a server to perform this expansion. Expansions are 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. Each contained code can include nested contained codes - see below for further discussion.

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):
  • Check that the parameters associated with the $expand operation are consistent with the parameters recorded in the expansion
  • If the parameters are inconsistent, then either generate a new expansion, or, if there is no definition (.compose), return an error
  • Additional parameters may be applied to an existing expansion if the server has validated that the result will be the same as if the expansion was generated directly from the value set definition (e.g. text filter, designations included).
• Otherwise: For each compose.include:
  1. If there is a system, 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 parameters 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.
  2. For each valueSet, find the referenced value set by ValueSet.url, expand that (e.g., using the $expand operation: GET [base]/ValueSet/$expand$url=[compose.include.valueSet]), and add it to the result set. This means that expansion across imports is a recursive process.
  3. Add the intersection of the result set from the system and the result sets from the value sets to the expansion
• For each compose.exclude, follow the same process as for compose.include, but remove any codes from the result set, instead of adding them.

The final "result set" is then represented in expansion. Note that the expansion structure is inherently ordered; this specification does not fix the meaning of use of the order. The conceptual approach described should not be understood to prohibit any implementation approach in these regards. In addition, note that the method described above is a conceptual approach; individual servers may choose to follow alternative approaches that are more efficient, as long as the outcome is the same.

The impact of Code System supplements on value set expansion - and therefore value set validation - is subject to ongoing experimentation and implementation testing, and further clarification and additional rules might be proposed in future versions of this specification.

4.9.8.1 Hierarchical Expansions

The expansion MAY be hierarchical - that is, it may have contains element that contain their own sub-elements, to any level of depth. This specification does not fix the meaning of the hierarchy: there is no implication about the logical relationship between the nested contain elements, 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. There is an example of use of a hierarchical expansion.

Note that the CodeSystem resource and ValueSet.compose offer no direct support for defining hierarchies and groups; applications may want to take advantage of the expand-rules and expand-group extensions as an implementation feature. 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.

4.9.8.2 Uniqueness of Concepts in Expansions

Value set definitions may lead to more than one instruction to include a given concept in the value set across the includes and imports. No matter how many times the definitions include a concept, it is only present in the value set once, and will only appear once in a flat expansion of the value set. Note, however, that a concept may appear more than once in a nested hierarchy when the expansion is prepared for UI use (irrespective of how many times it is included in the definitions). Note that uniqueness is based on system/version/code; it is possible to include the same concept from different versions of a code system in the same expansion, though this is generally confusing for users and should be avoided.

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

4.9.8.3 Expansion Identifiers

It is important that expansions be identified properly. Any value set definition may produce an infinite number of expansions, depending on the operation parameters. Any expansions produced must be clearly identified so that there is no confusion. The following rules apply:

• The canonical URL for the expansion is the same as the value set it was expanded from
• Each expansion SHALL have a unique identifier in ValueSet.expansion.identifier
• The result of an $expand operation may use the same identifier in ValueSet.expansion.identifier as a previous expansion, but if it does, the canonical representation of the value set expansion SHALL be identical (e.g. a cached response)

4.9.8.4 Expansion Parameters

The expansion contains a set of parameters in ValueSet.expansion.parameter that record what 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. The server decides which parameters to include here, but at a minimum, the list SHOULD include all of the parameters that affect the $expand operation. If the expansion will be persisted all of these parameters SHALL be included. If the codeSystem on the server has a specified version then this version SHALL be provided as a parameter in the expansion (note that not all code systems have a version).

The following parameters are predefined by the $expand operation, and are suitable for use in the expansion parameters:

The count and offset parameters are important. If the expansion is a page out of the whole expansion, the offset and count parameters SHALL be populated. Clients can reliably use the count/offset parameters to determine whether the whole expansion is returned.

Other parameters that servers may be required to use:

Beyond this, servers MAY define their own parameters, though Terminology server authors are requested to bring additional parameters to HL7 (via 'Propose a change' link below) in the interests of interoperability.

Servers can also create and store Provenance statements about the expansion, or AuditEvent records of the expansion process if further transparency is required. These resources can contain considerable detail about the various inputs to the process, and any significant decisions by the expansion engine. Further details around this (and profiles on the relevant resources) may be provided in future versions of this specification or related implementation guides.

Request for Feedback: The existing set of parameters are intended to cover the vast majority of use cases, but there are some cases where the parameters do not provide enough control to a client, particularly with regard to combinations of parameters, and the interplay between code system versions and other parameters. Implementers may need to define their own value sets to meet these requirements.

Ongoing feedback is welcome at [link to be provided]

4.9.8.5 Storing Expansions

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). If expansions are shared, users need to be aware of how expansion identifiers (which may be server specific) work.

4.9.8.6 Searching for codes in value sets

The search parameters defined on ValueSet include the code parameter. This is intended to allow a consumer to find all the value sets that include a particular code. However, fully evaluating this search parameter is extremely onerous for a server. Further, whether a code is in a value set depends on the context in which expansions are performed (see the $expand operation). For this reason, the degree to which the search parameter is supported can be declared in the Terminology Capability statement.

4.9.9 Combinations of .compose and .expansion

Use cases for the different combinations:

• .compose only: Provides the value set definition (CLD). This is the expected format from the value set publisher.
• .expansion only: Provides the value set expansion, which might or might not be persisted (see 4.8.7 Value Set Expansion above). The "expansion only" format may be returned in the $expand operation output (at the terminology server's discretion).
• Both .compose and .expansion: The terminology server often may include the definition as well as the expansion in the $expand operation output. The resource instance including the expansion might or might not be persisted.
• Neither .compose nor .expansion: This is a valid format for ValueSet resource instances. A primary use case is the return from a summary search (i.e. _summary=true). This may be especially useful to reduce the performance overhead when returning a summary of extensionally defined value sets (which may include a large number of concepts in the value set definition).

4.9.10 Search Parameters

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