View raw Markdown
type: valuesetvalueset: notes

ValueSet: notes

Narrative

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:

Compose

The rules for the content of the value set are found in the ValueSet.compose element, which are analogous to the Content Logical Definition (CLD) as defined by the VSD Project. The ValueSet compose is a set of instructions for what codes are in the ValueSet, and defined by the author consistent with the ValueSet.description

The ValueSet composition can be defined in a number of ways:

The first approach - listing codes explicitly - is called an 'extensional' definition; all the other ways are called 'intensional' definitions.

Filters

Mapping from VSD to ValueSet.compose

VSD ScenarioFHIR Implementation
When the ValueSet.compose is an expression (ValueSet.expression), declare the type of expression here

| | When the ValueSet.compose describes Concepts to include based on CodeSystem properties |

compose.include.filter.property = "property name"

Either the Value or Expression must be provided

Value:

Expression:

| | When the ValueSet.compose defines the types of relationships between concepts to include in the ValueSet Expansion |

compose.filter.property = "RelationshipType"

(note: filter property is a string in VSD, code in FHIR)

Example:

to find all concepts in SNOMED CT with the SNOMED CT laterality qualifier relationship to the SNOMED CT concept "left":

|

Using Filter Values

The element compose.include.filter.value is a string. The actual format of the value depends on the value of compose.include.filter.op and/or the definitions of the underlying CodeSystem. The following rules apply (in order).

The format of compose.include.filter.value for Code System Properties depends on the property type:

stringUse the string directly
integerUse the integer value directly
booleanUse true or false
dateTimeUse ISO 8601 format, following the precision rules for the dateTime data type
decimalUse the decimal value directly
codeUse the code directly
CodingUse the format system(

For the ordered data types (integer, decimal and dateTime), the search prefixes can be used (eq, ne, gt, lt, ge, le, sa, eb, ap). Note that the Coding syntax is not the search syntax.

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

HL7 Terminology defines filters for various published code systems:

Union and Intersection

ValueSet.compose may reference other ValueSets.

Intersection:

Union:

For expansion guidance, and how to manage exclude, see Value Set Expansion

When a ValueSet definition includes other ValueSets, use the ValueSet.valueset-compose-include-ValueSetTitle extension to provide the human readable name of the included Value Set.

Referencing CodeSystem Fragments

The VSD Partition aligns with FHIR CodeSystem Fragments.

Code System fragments are a unique and identifiable distinct segment of an overall Code System namespace. While most Code Systems are in essence one fragment and, therefore, do not have identifiable fragments, some Code Systems can be made up of a collection of distinct segments. SNOMED CT is an example of such a Code System. The SNOMED CT International Edition is the base fragment and can be used alone, but there are many distinct additional fragments that can be added to the international core to create what is known as a SNOMED CT Edition.

The CodeSystem referenced in a ValueSet.compose may reference a CodeSystem fragment.

ValueSet Alignment with VSD

Author and Publisher

Author, Steward and Publisher are roles associated with a Value Set Definition.

ValueSet Author is the person or organization that creates and may modify the ValueSet. The Steward is the person or organization responsible for the content, maintenance and life cycle of the ValueSet. The Publisher is the person or organization that makes the ValueSet available. The publisher or a terminology server might provide the ValueSet expansions.

In FHIR, ValueSet.publisher satisfies the requirements for both publisher and steward.

Scope and Description

Description and Purpose are standard elements that appear in many FHIR resources. Neither fully supports the intent of the VSD Scope element, however ValueSet.description does support Focus as defined in VSD.

When a ValueSet definition includes other ValueSets, use ValueSet.description to provide information about the included value sets in context of the parent value set.

Purpose may be used for the ValueSet.author to describe why the ValueSet was created. ValueSet.description may be used to provide the ValueSet Focus as described in VSD.

Example:

Value Set NameDescription
Body Site Value SetAll SNOMED CT anatomic structures, locations, abnormal structures that can be considered to describe an anatomical site.
Familial HypercholesterolemiaThis value set contains terms defining familial hypercholesterolemia, regardless of genetic origin.

Name and Title

The VSD element Name aligns with ValueSet.title which does not support preference or language. Use the ValueSet.valueset-otherTitle extension when a language or preference is necessary. ValueSet.title or ValueSet.valueset-otherTitle must be valued.

Include Active Concepts Only

VSD and FHIR support the constraining the $expand operation to return only active concepts as defined by the CodeSystem.

The VSD element ActiveOnly equal to TRUE is equivalent to ValueSet.compose.inactive equal to FALSE.

Status

The ValueSet resource defines a Value Set Definition and a Value Set Expansion. VSD describes only the characteristics of the Value Set Definition.

The VSD element ActivityStatus aligns with ValueSet.status, which is the status of the entire ValueSet resource with the exception of the ValueSet.expansion. This aligns with VSD using the word definition to mean the Content Logical Definition plus all the other non-expansion metadata. A Value Set Expansion is stateless.

Note: ValueSet.status is bound with required binding strength to the PublicationStatus value set. The following table shows how the ActivityStatus values in VSD align with the values in the PublicationStatus Value Set Expansion.

VSD Activity Status ValueFHIR Publication Status Value
PreliminaryDraft
ActiveActive
InactiveRetired
*Unknown
Deleted*

*There is no equivalent value in either VSD or the PublicationStatus Value Set.

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:

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.

As an example, the LOINC code 55423-8 has a display value of "Number of steps in unspecified time Pedometer". A value set for a pick list in a patient generated data form might choose a simpler name:

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

The expansion generated by a terminology server will have this:

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

The expansion display is taken from the value set, and this is what is displayed in the pick list. Once the user picks the code, it will appear in the Observation.code like this:

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

Note that the correct value for the display is not in the expansion above. The client can either omit the display, look it up using $lookup, or the server might pre-populate it in the expansion:

{ "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" }] }] } }

Irrespective of this, the display in the expansion always goes in CodeableConcept.text.

ValueSet XML

<div xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.w3.org/1999/xhtml ../../schema/fhir-xhtml.xsd" xmlns="http://www.w3.org/1999/xhtml">

<a name="compositions"></a>
<h2>Composition Rules</h2>

<p>
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 <a href="codesystem.html">code system</a>. For these value sets:
</p>
<ul>
 <li>Multiple <code>include</code> statements are cumulative - e.g. the value set contains the union of all the includes</li>
 <li>Within an <code>include</code>, all the criterion apply -e.g. the value set contains the intersection of the criterion</li>
 <li>Within an <code>include</code>, a single system with selection criteria may be listed, and/or one or more value sets may be listed</li>
 <li><b><code>valueSet</code>(s) only</b>: Codes are 'selected' for inclusion if they are in all the referenced value sets</li>
 <li>If a <b><code>System</code> only</b> is specified, the following rules apply: 
    <ul>
     <li><b>no <code>concept</code> or <code>filter</code></b>: All codes defined by the code system, independent of code status, are included</li>
     <li><b><code>concept</code></b>: Only the enumerated codes are selected</li>
     <li><b><code>filter</code></b>: Any codes meeting the filter criteria are selected</li>
    </ul>
 </li>
 <li><b><code>valueSet</code> and <code>System</code></b>: Codes are 'selected' for inclusion if they are selected by the code system selection 
   (after checking for <code>concept</code> and <code>filter</code>) and if they are in all the referenced value sets</li>
 <li>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</li>
 <li>The version reference may be the special value '<code>*</code>', which indicates that the value set includes codes from all versions of the code system.
     how to handle provision of the required versions and generation of expansions is at server discretion, including for poorly behaved code systems where 
         a code changes in meaning). 
    [%impl-note%]     
       <span class="warning">Use of this capability is subject to future clarification and conformance requirements based on implementation experience</span>.
    [%end-note%]     
 </li>
 <li>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</li>
 <li>In addition to include rules, codes may be excluded. Rules for interpretation of exclude statements match those for includes, but codes in the exclude statements are never in the value set</li>
 <li>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.</li>
 <li>Any compose.exclude SHALL be processed such that excluded codes are not found in the expansion</li>
 <li>Any compose.include SHALL NOT reference a CodeSystem supplement.</li>
 <li>Any compose.exclude SHALL NOT reference a CodeSystem supplement.</li>
 <li>Required CodeSystem supplements SHALL be declared using either the valueset-supplement extension, or the useSupplement $expand input parameter.</li>
</ul>

<a name="compose"></a>
<h3>Compose</h3>
<p>
The rules for the content of the value set are found in the <code>ValueSet.compose</code> element, which are 
analogous to the Content Logical Definition (CLD) as defined by the <a href="https://confluence.hl7.org/display/VOC/Characteristics+of+a+Value+Set+Definition+%28VSD%29+Project">VSD Project</a>.
The ValueSet compose is a set of instructions for what codes are in the ValueSet, and defined by the author consistent with the <code>ValueSet.description</code>
</p>
<p>
The ValueSet composition can be defined in a number of ways:
</p>
<ul>
 <li>By listing the codes that are in the ValueSet explicitly using <code>ValueSet.compose.include.concept</code></li>
 <li>By specifying the codes for inclusion using filter expressions in <code>ValueSet.compose.include.filter</code></li>
 <li>If the language in filter cannot be used, using the <a href="[%extensions-location%]StructureDefinition-valueset-expression.html">Extension ValueSet.valueset-expression</a> 
  to define some alternative expression, though this can only be evaluated by a system that understands the syntax used in the expression</li>
  <li>For a few value sets, there is no formal expression, and the rules are expressed using the <a href="[%extensions-location%]StructureDefinition-valueset-rules-text.html">Extension ValueSet.valueset-rules-text</a>
    that is not computable and is meant to be interpreted by a human. Such value sets are rare</li>
</ul> 
<p>
The first approach - listing codes explicitly - is called an 'extensional' definition; all the other ways are called 'intensional' definitions.
</p>

<a name="filters"></a>
<h3>Filters</h3>

<p><b>Mapping from VSD to <code>ValueSet.compose</code></b></p>

<table class="grid">
 <tr>
  <td>VSD Scenario</td>
  <td>FHIR Implementation</td>
 </tr>
 <tr>
  <td>When the <code>ValueSet.compose</code> is an expression (<code>ValueSet.expression</code>), declare the type of expression here</td>
  <td>
   <ul>
    <li><code>compose.include.filter.op</code> = "property"</li>
    <li><code>compose.include.filter.op</code> = regex</li>
    <li><code>compose.include.filter.value</code> = "property value"</li>
  </ul>
  </td>
 </tr>
 <tr>
  <td>When the <code>ValueSet.compose</code> describes Concepts to include based on CodeSystem properties</td>
  <td>
   <p><code>compose.include.filter.property</code> = "property name"</p>
   <p>Either the Value or Expression must be provided</p>
   <p>Value:</p>
   <ul>
    <li><code>compose.include.filter.op</code> = "="</li>
    <li><code>compose.include.filter.value</code> =<em>the value</em></li>
   </ul>
   <p>Expression:</p>
   <ul>
    <li><code>compose.include.filter.op</code> = "regex"</li>
    <li><code>compose.include.filter.value</code> =<em>the Expression</em></li>
   </ul>
  </td>
 </tr>
 <tr>
  <td>When the <code>ValueSet.compose</code> defines the types of relationships between concepts to include in the ValueSet Expansion</td>
  <td>
   <p><code>compose.filter.property</code> = "RelationshipType"</p>
   <p>(note: filter property is a string in VSD, code in FHIR)</p>
   <ul>
    <li><code>compose.filter.property.op</code> = "="</li>
    <li><code>compose.filter.property.value</code> = a code defined by the CodeSystem</li>
   </ul>
   <p>Example:</p>
   <p>to find all concepts in SNOMED CT with the SNOMED CT laterality qualifier relationship to the SNOMED CT concept "left":</p>
   <ul>
    <li><code>filter.property.name</code> = '272741003'</li>
    <li><code>filter.property.op</code> = '='</li>
    <li><code>filter.property.value</code> = '7771000'</li>
   </ul>
  </td>
 </tr>
</table>

<a name="filter-values"></a>
<h3>Using Filter Values</h3>
<p>
The element <code>compose.include.filter.value</code> is a string. The actual format of the value depends on the 
value of <code>compose.include.filter.op</code> and/or the definitions of the underlying CodeSystem. The following
rules apply (in order).
</p>
<ul>
 <li>If the <code>op</code> is <code>regex</code>, the format is a regex expression</li>
 <li>If the <code>op</code> is <code>exists</code>, the format is a <a href="datatypes.html#boolean">boolean</a> (<code>true</code> or <code>false</code>)</li>
 <li>If the <code>op</code> is <code>in</code> or <code>not-in</code>, the format is either a comma-separated list of <a href="datatypes.html#code">code</a> values, or an absolute <a href="datatypes.html#uri">uri</a>, which is a canonical reference to a ValueSet.
   If the value is a code or list of codes, the interpretation of the codes is subject to the CodeSystem e.g. for SNOMED-CT reference sets. If the value is a valueSet uri, then commas and percents should be percent encoded</li>
 <li>If the <code>property</code> is <code>concept</code>, the format is a <a href="datatypes.html#code">code</a></li>
 <li>If the name in <code>property</code> refers to a <a href="codesystem.html#filters">CodeSystem filter</a>, the format is as defined in the filter table on the CodeSystem page, or as described in the applicable <code>CodeSystem.filter.value</code></li> 
 <li>If the name in <code>property</code> refers to a <a href="codesystem.html#defined-props">CodeSystem property</a>, the format is as defined in the following table</li>
</ul>
<p>
The format of <code>compose.include.filter.value</code> for Code System Properties depends on the property type:
</p>
<table class="grid">
 <tr><td>string</td><td>Use the string directly</td></tr>
 <tr><td>integer</td><td>Use the integer value directly</td></tr>
 <tr><td>boolean</td><td>Use <code>true</code> or <code>false</code></td></tr>
 <tr><td>dateTime</td><td>Use ISO 8601 format, following the precision rules for the <a href="datatypes.html#dateTime">dateTime</a> data type</td></tr>
 <tr><td>decimal</td><td>Use the decimal value directly</td></tr>
 <tr><td>code</td><td>Use the code directly</td></tr>
 <tr><td>Coding</td><td>Use the format <code>system</code>(|<code>version</code>)#<code>code</code>, 
 which is effectively a <a href="datatypes.html#canonical">canonical</a> reference to the CodeSystem, followed by # and then the code in the CodeSystem. There is no way to specify the display</td></tr>
</table> 
<p>
For the ordered data types (integer, decimal and dateTime), the <a href="search.html#prefix">search prefixes</a> can be used (eq, ne, gt, lt, ge, le, sa, eb, ap).
Note that the Coding syntax is <b>not</b> the search syntax.
</p>

<a name="csnote"></a>
<h4>Code Systems Note</h4>
<p>
Each <a href="codesystem.html">Code System</a> defines which filters can be 
used in <code>ValueSet.compose.include.filter</code>. All code systems have
<a href="codesystem.html#filter">base filters</a> and any additional 
filters defined in (<a href="codesystem-definitions.html#CodeSystem.filter">CodeSystem.filter)</a>.
</p>
<p>
HL7 Terminology defines filters for various published code systems:
</p>
<ul>
 <li><a href="https://terminology.hl7.org/LOINC.html">LOINC</a></li>
 <li><a href="https://terminology.hl7.org/SNOMEDCT.html">SNOMED CT</a></li>
 <li><a href="https://terminology.hl7.org/RxNorm.html">RxNorm</a></li>
 <li><a href="https://terminology.hl7.org/UCUM.html">UCUM</a></li>
 <li><a href="https://terminology.hl7.org/CPT.html">CPT</a></li>
 <li><a href="https://terminology.hl7.org/NDFRT.html">NDF-RT</a></li>
</ul>

<a name="union-intersection"></a>
<h3>Union and Intersection</h3>
<p>
<code>ValueSet.compose</code> may reference other ValueSets.
</p>
<p>
Intersection:
</p>
<ul>
    <li>If the ValueSet definition contains references to multiple ValueSets within a single <code>ValueSet.compose.include</code></li>
    <ul>
        <li>The resulting expansion includes only those concepts that are in each expansion of the included ValueSets</li>
    </ul>
</ul>
<p>
Union:
</p>
<ul>
    <li>If the ValueSet definition contains references to ValueSets using multiple <code>ValueSet.compose.include</code> elements</li>
    <ul>
        <li>The resulting expansion includes all concepts from the ValueSet expansions</li>
    </ul>
</ul>
<p>
For expansion guidance, and how to manage <em>exclude</em>, see <a href="valueset.html#expansion">Value Set Expansion</a>
</p>
<p>
When a ValueSet definition includes other ValueSets, use the <a href="[%extensions-location%]StructureDefinition-valueset-compose-include-valueSetTitle.html">ValueSet.valueset-compose-include-ValueSetTitle</a> extension to provide the human readable name of the included Value Set.
</p>

<a name="fragments"></a>
<h3>Referencing CodeSystem Fragments</h3>
<p>
The VSD Partition aligns with FHIR <a href="codesystem.html#fragments">CodeSystem Fragments</a>.
</p>
<p>
Code System fragments are a unique and identifiable distinct segment of an overall Code System namespace. While most Code Systems are in essence one fragment and, therefore, do not have identifiable fragments, some Code Systems can be made up of a collection of distinct segments. SNOMED CT is an example of such a Code System. The SNOMED CT International Edition is the base fragment and can be used alone, but there are many distinct additional fragments that can be added to the international core to create what is known as a SNOMED CT Edition.
</p>
<p>
The CodeSystem referenced in a <code>ValueSet.compose</code> may reference a CodeSystem fragment.
</p>

<a name="vsd"></a>
<h2>ValueSet Alignment with VSD</h2>

<a name="author-publisher"></a>
<h3>Author and Publisher</h3>
<p>
Author, Steward and Publisher are roles associated with a Value Set Definition.
</p>
<p>
ValueSet Author is the person or organization that creates and may modify the ValueSet. The Steward is the person or organization responsible for the content, maintenance and life cycle of the ValueSet. The Publisher is the person or organization that makes the ValueSet available. The publisher or a terminology server might provide the ValueSet expansions.  
</p>
<p>
In FHIR, <code>ValueSet.publisher</code> satisfies the requirements for both publisher and steward. 
</p>

<a name="scope-description"></a>
<h3>Scope and Description</h3>
<p>
Description and Purpose are standard elements that appear in many FHIR resources. Neither fully supports the intent of the VSD Scope element, however <code>ValueSet.description</code> does support Focus as defined in VSD.
</p>
<p>
When a ValueSet definition includes other ValueSets, use <code>ValueSet.description</code> to provide information about the included value sets in context of the parent value set.
</p>
<p>
Purpose may be used for the <code>ValueSet.author</code> to describe why the ValueSet was created. <code>ValueSet.description</code> may be used to provide the ValueSet Focus as described in VSD.  
</p>
<p>
Example: 
</p>
<table class="grid">
<tr>
<td>Value Set Name</td>
<td>Description</td>
</tr>
<tr>
<td>Body Site Value Set</td>
<td>All SNOMED CT anatomic structures, locations, abnormal structures that can be considered to describe an anatomical site.</td>
</tr>
<tr>
<td>Familial Hypercholesterolemia</td>
<td>This value set contains terms defining familial hypercholesterolemia, regardless of genetic origin.</td>
</tr>
</table>

<a name="name-title"></a>
<h3>Name and Title</h3>
<p>
The VSD element <em>Name</em> aligns with <code>ValueSet.title</code> which does not support preference or language. Use the <a href="[%extensions-location%]StructureDefinition-valueset-otherTitle.html">ValueSet.valueset-otherTitle extension</a> when a language or preference is necessary. <code>ValueSet.title</code> or <a href="[%extensions-location%]StructureDefinition-valueset-otherTitle.html">ValueSet.valueset-otherTitle</a> must be valued.
</p>

<a name="activeonly"></a>
<h3>Include Active Concepts Only</h3>
<p>
VSD and FHIR support the constraining the $expand operation to return only active concepts as defined by the CodeSystem.
</p>
<p>
The VSD element <em>ActiveOnly</em> equal to TRUE is equivalent to <code>ValueSet.compose.inactive</code> equal to FALSE.
</p>

<a name="status"></a>
<h3>Status</h3>
<p>
The ValueSet resource defines a Value Set Definition <em>and</em> a Value Set Expansion. VSD describes only the characteristics of the Value Set Definition.
</p>
<p>
The VSD element <em>ActivityStatus</em> aligns with <code>ValueSet.status</code>, which is the status of the entire ValueSet resource <em>with the exception of the</em> <code>ValueSet.expansion</code>. This aligns with VSD using the word <em>definition</em> to mean the Content Logical Definition <em>plus</em> all the other non-expansion metadata. A Value Set Expansion is stateless. 
</p>
<p>
Note: <code>ValueSet.status</code> is bound with <em>required</em> binding strength to the <a href="valueset-publication-status.html">PublicationStatus</a> value set. The following table shows how the ActivityStatus values in VSD align with the values in the PublicationStatus Value Set Expansion.
</p>
<table class="grid">
<tr>
<td>VSD Activity Status Value</td>
<td>FHIR Publication Status Value</td>
</tr>
<tr>
<td>Preliminary</td>
<td>Draft</td>
</tr>
<tr>
<td>Active</td>
<td>Active</td>
</tr>
<tr>
<td>Inactive</td>
<td>Retired</td>
</tr>
<tr>
<td>*</td>
<td>Unknown</td>
</tr>
<tr>
<td>Deleted</td>
<td>*</td>
</tr>
</table>
<p>
*There is no equivalent value in either VSD or the PublicationStatus Value Set. 
</p>

<a name="designations"></a>
<h2>Display and Designations</h2>
<p>
Concepts used in ValueSets can have a <code>display</code>, 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 
<a href="codesystem.html#designations">display from the code system</a> (which is the preferred approach,
because overriding the display can lead to very unsafe outcomes).
</p>
<p>
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:
</p>
<ul>
 <li>The system that defines the code or expression doesn't provide a display for this code (or any codes).</li>
 <li>The system that defines the code or expression defines multiple choices for display.</li>
 <li>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.</li>
</ul>
<p>
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.
</p>
<p>
Any display name for a concept provided in the value set is for display to a human user. 
The display in the <a href="datatypes.html#Coding">Coding</a> 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 
<a href="[%extensions-location%]StructureDefinition-valueset-reference.html">extension</a>). The correct display for a 
code can be determined by a <a href="codesystem-operation-lookup.html">$lookup operation</a>. 
Any alternative display specified in the value set would go in 
<a href="datatypes.html#CodeableConcept">CodeableConcept</a>.text, perhaps appended to 
the UI label for the matching data element.
</p>
<div class="example">
<p>
As an example, the <a href="http://loinc.org">LOINC</a> code <a href="https://s.details.loinc.org/LOINC/55423-8.html?sections=Comprehensive"><code>55423-8</code></a> 
has a display value of "Number of steps in unspecified time Pedometer". A value set for a pick list
in a patient generated data form might choose a simpler name:
</p>
<pre class="json" fragment="ValueSet">
{
  "resourceType" : "ValueSet",
  "compose" : {
    "include" : [{
      "system" : "http://loinc.org",
      "concept" : [{
        "code" : "55423-8",
        "display" : "Step Count"
      }]
    }]
  }
}
</pre>
<p>
The expansion generated by a terminology server will have this:
</p>
<pre class="json" fragment="ValueSet">
{
  "resourceType" : "ValueSet",
  "expansion" : {
    "contains" : [{
      "system" : "http://loinc.org",
      "code" : "55423-8",
      "display" : "Step Count"
    }]
  }
}
</pre>
<p>
The expansion display is taken from the value set, and this is what is displayed in the pick list.
Once the user picks the code, it will appear in the <a href="observation-definitions.html#Observation.code">Observation.code</a> like this:
</p>
<pre class="json" fragment="Observation">
{
  "resourceType" : "Observation",
  "code" : {
    "coding" : [{
      "system" : "http://loinc.org",
      "code" : "55423-8",
      "display" : "Number of steps in unspecified time Pedometer"
    }],
    "text" : "Step Count"
  }
}
</pre>
<p>
Note that the correct value for the display is not in the expansion above. 
The client can either omit the display, look it up using <a href="codesystem-operation-lookup.html">$lookup</a>, or the 
server might pre-populate it in the expansion:
</p>
<pre class="json" fragment="ValueSet">
{
  "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"
      }]
    }]
  }
}
</pre>
<p>
Irrespective of this, the display in the expansion always goes in <a href="datatypes-definitions.html#CodeableConcept.text">CodeableConcept.text</a>.
</p>
</div>
<p>
In addition to the display, a concept can have one or more <code>designation</code> elements. 
The display is equivalent to a special designation with an implied <code>designation.use</code> of "primary code" 
and a language equal to the <a href="resource.html#language">Resource Language</a>. The designations can provide 
additional displays for other languages, as well as designations for other purposes. 
When using concepts, applications use the <code>display</code> unless the language or usage in context provides a reason
to use one of the designations.
</p>

<a name="multiples"></a>
<h2>Value Sets with multiple code systems</h2> 
<p>
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). 
</p> 
<p>
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.
</p>
<p>
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.
</p>

<a name="expansion"></a>
<h2>Value Set Expansion</h2>
<p>
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 <a href="valueset-operation-expand.html">defined operation $expand</a> 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. 
</p>
<p>
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 (<code>.compose</code>). In 
addition, it has an <code>.expansion</code> element which contains
the list of codes that constitute the value set expansion. Each
contained code can include nested contained codes - see <a href="#hierarchy">below 
for further discussion</a>.
</p>
<p>
When a request for an expansion is received (e.g., for the <a href="valueset-operations.html#expand">$expand</a> operation),
the following process should be followed:
</p>
<ul>
 <li>If the value set already has an expansion (e.g., a stored expansion):
   <ul>
    <li>Check that the parameters associated with the <a href="valueset-operation-expand.html">$expand</a> operation are consistent with the parameters recorded in the expansion</li>
    <li>If the parameters are inconsistent, then either generate a new expansion, or, if there is no definition (<code>.compose</code>), return an error</li>
    <li>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).</li>
   </ul>
 </li>
 <li>Otherwise: For each <i>compose.include</i>:
  <ol>
   <li>If there is a system, identify the correct version of the <a href="codesystem.html">code system</a>, and then:
     <ul>
      <li>If there are no codes or filters, add every code in the code system to the result set.</li>   
      <li>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 <a href="valueset-operation-expand.html">$expand</a> operation may be used to control whether active codes are included).</li>
      <li>If any filters are present, process them in order (as explained above), and add the intersection of their results to the result set.</li>
   </ul></li>
   <li>For each <code>valueSet</code>, find the referenced value set by ValueSet.url, expand that (e.g., using the <a href="valueset-operations.html#expand">$expand</a> operation: GET [base]/ValueSet/$expand$url=[compose.include.valueSet]), to produce a collection of result sets. This means that expansion across imports is a recursive process.</li>
   <li>Add the intersection of the result set from the system (step 1) and all of the result sets from the value sets (step 2) to the expansion</li>
  </ol>
 </li>
 <li>For each <i>compose.exclude</i>, follow the same process as for <i>compose.include</i>, but remove codes from the expansion in step 3 instead of adding them.</li>
 <li>When available, ValueSet.status and ValueSet.version from the ValueSet resource instance which contains the definition SHALL be returned in the ValueSet resource instance which contains the expansion.</li>
</ul>
<p>
The final "result set" is then represented in <i>expansion</i>.
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.
</p>
[%dragons-start%]
<p class="warning">
The impact of <a href="codesystem.html#supplements">Code System supplements</a> on <a href="valueset-operation-expand.html">value set expansion</a> - and 
therefore <a href="valueset-operation-validate-code.html">value set validation</a> - is 
subject to ongoing experimentation and implementation testing, and further clarification and additional
rules might be proposed in future versions of this specification.
</p>
[%dragons-end%]

<a name="hierarchy"></a>
<h3>Hierarchical Expansions</h3>
<p>
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 <code>contain</code> 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.
</p>
<p>
Note that the 
<code>CodeSystem</code> resource and <code>ValueSet.compose</code> offer no direct support for defining hierarchies and groups.
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.  
</p>

<a name="uniqueness"></a>
<h3>Uniqueness of Concepts in Expansions</h3>
<p>
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.
</p>
<p>
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. 
</p>

<a name="identifiers"></a>
<h3>Expansion Identifiers</h3>
<p>
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:
</p>
<ul>
 <li>The canonical URL for the expansion is the same as the value set it was expanded from</li>
 <li>Each expansion SHALL have a unique identifier in <code>ValueSet.expansion.identifier</code></li>
 <li>The result of an <a href="valueset-operation-expand.html">$expand</a> 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)</li>
</ul>

<a name="parameters"></a>
<h3>Expansion Parameters</h3>
<p>
The expansion contains a set of parameters in <code>ValueSet.expansion.parameter</code> 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 return in <code>ValueSet.expansion.parameter</code>, but at a minimum, the list SHOULD include:
</p>
<ul>
 <li>All input parameters defined by the <a href="valueset-operation-expand.html">$expand</a> operation and provided by the client and used by the server to generate the expansion</li>
 <li>All input parameters defined by the <a href="valueset-operation-expand.html">$expand</a> operation and their values for which the server provided default values </li>
 <li>Canonical or URI references (including version) for all CodeSystems, CodeSystem Supplements and ValueSets  used in the expansion </li>
</ul>
<p>
The following parameters are predefined by the <a href="valueset-operation-expand.html">$expand</a> operation, and are suitable for use in the
expansion parameters:
</p>
[%shortparameterlist ValueSet/$expand:filter,date,offset,count,includeDesignations,designation,includeDefinition,activeOnly,excludeNested,excludeNotForUI,excludePostCoordinated,displayLanguage,exclude-system,system-version,check-system-version,force-system-version%]
<p>
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.
</p>
<p>
Other parameters that servers may be required to use:
</p>
<table class="grid">
 <tr><td><code>[canonical]#CodeSystem.content</code></td><td>[content] : The content value for the <a href="codesystem.html">code system</a> for the canonical URL. 
   Applications generating expansions SHALL use this parameter if the CodeSystem.content value is "fragment"</td></tr>
 <tr><td><code>[canonical1]#supplement</code></td><td>[canonical2] : Indicates that the specified supplement (canonical2) contributed to the content
  of the expansion for the code system canonical1 (by influencing selection, or providing designations). Applications generating expansions SHALL use this parameter to record 
    that a supplement was used during the expansion process</td></tr>
</table>
<p>
There's also some parameters that only go in the response to an expand, so that the server can inform the 
consumer of the expansion which value sets, code systems and supplements were used as the basis for the 
expansion:
</p>
<table class="grid">
 <tr><td><code>used-system</code></td><td><a href="datatypes.html#uri">uri</a></td><td>The canonical URL (system | {version} if available) of a code system that was used during the expansion of the value set </td></tr>
 <tr><td><code>used-supplement</code></td><td><a href="datatypes.html#uri">uri</a></td><td>The canonical URL (system | {version} if available) of a code system supplement that was used during the expansion of the value set </td></tr>
 <tr><td><code>used-valueset</code></td><td><a href="datatypes.html#uri">uri</a></td><td>The canonical URL (system | {version} if available) of a different value set that was used during the expansion of the value set </td></tr>
</table>
<p>
Beyond all these parameters, 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. 
</p>
<p>
Servers can also create and store <a href="provenance.html">Provenance</a> statements about the expansion, or <a href="auditevent.html">AuditEvent</a> 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.
</p>

<a name="limitations"></a>
[%feedback-note%]
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.
</p>
<p>
Ongoing feedback is welcome at [link to be provided]
[%end-note%]

<a name="storage"></a>
<h3>Storing Expansions</h3>
<p>
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.  
</p>

<a name="search"></a>
<h3>Searching for codes in value sets</h3>
<p>
The search parameters defined on ValueSet include the <code>code</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 <a href="valueset-operation-expand.html">$expand</a> operation).
For this reason, the degree to which the search parameter is supported can be declared in the <a href="terminologycapabilities-definitions.html#TerminologyCapabilities.codeSearch">Terminology Capability</a>
statement. 
</p>

<a name="combinations"></a>
<h2>Combinations of .compose and .expansion</h2>
<p>
Use cases for the different combinations:
</p>
<ul>
 <li><code><a href="valueset-definitions.html#ValueSet.compose">.compose</a></code> only:
 Provides the value set definition (CLD).  This is the expected format from the value set publisher. 
 </li>
 <li><code><a href="valueset-definitions.html#ValueSet.expansion">.expansion</a></code> only:
 Provides the value set expansion, which might or might not be persisted (see <a href="valueset.html#expansion">4.8.7 Value Set Expansion</a> above).
 The "expansion only" format may be returned in the <a href="valueset-operation-expand.html">$expand</a> operation output (at the terminology server's discretion). 
 </li>
 <li>Both <code><a href="valueset-definitions.html#ValueSet.compose">.compose</a></code> and <code><a href="valueset-definitions.html#ValueSet.expansion">.expansion</a></code>:
 The terminology server often may include the definition as well as the expansion in the <a href="valueset-operation-expand.html">$expand</a> operation output.  
 The resource instance including the expansion might or might not be persisted. 
 </li>
 <li>Neither <code><a href="valueset-definitions.html#ValueSet.compose">.compose</a></code> nor <code><a href="valueset-definitions.html#ValueSet.expansion">.expansion</a></code>:
 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).
 </li>
</ul>

<a name="implicit"></a>
<h2>Implicit Value Sets</h2>
<p>
Instead of a ValueSet resource as the definition, implicit value sets are defined in a specification which 
references the underlying code system structures and includes a prescribed URI pattern to identify the 
value set.  HL7 has defined implicit value set URI patterns for some key code systems.
</p>
<p>
Implicit value sets allow the URI to serve as the basis for ValueSet operations such as 
<a href="valueset-operation-expand.html">$expand</a> and <a href="valueset-operation-validate-code.html">$validate-code</a>
without the need to create a defining ValueSet resource instance.
</p>
<p>
Some advantages of using implicit value sets are that they may be used:
</p>
<ul>
<li>With read-only terminology servers because a ValueSet resource cannot be posted</li>
<li>With HTTP GET requests because they are cacheable</li>
<li>To enable text searches (google like) for concepts across the entirety of large code systems (e.g., SNOMED CT)</li>
<li>To provide a convenient way to reference all or parts of code systems in the definition of a ValueSet or ConceptMap</li>
</ul>
<p>
In some cases it is not possible to express a value set definition using ValueSet.compose - but 
it may be possible to express the value set definition with an implicit value set URI. An example 
of this scenario is all SNOMED CT concept IDs that identify reference sets. 
</p>
<p>
If there is an explicit value set resource with the same URI as a known implicit value set, 
it SHALL conform the pattern described in the definition of the implicit value set.
It is up to the discretion of the server how to handle explicit instances when it is 
also able to process requests for the implicit value set.
</p>
[%impl-note%]
If the relevant server(s) support implicit value sets, implementers are discouraged from creating their own explicit value sets with the same URI,
as their existence may create confusion.
[%end-note%]
<p>
Implementers SHOULD NOT 
create ValueSet resources where the ValueSet.url value matches the pattern of a known implicit value set. 
</p>
<p>
Implicit value set URIs can be used anywhere a value set URI can be used. Support for implicit value 
set URI patterns varies across terminology servers.
</p>
<p>
Some (but not all) code systems have implicit value set URI patterns defined by HL7 and documented 
for use with FHIR terminology services. Code system publishers may also define implicit value set 
URI patterns. FHIR terminology servers might or might not support any or all of these URI patterns. 
Caution should be exercised when using value set URI patterns that have not been defined by HL7 or 
the code system publisher. 
</p>

<p>
  The following links describe the currently defined FHIR implicit value set URL patterns for these listed code systems:
  <ul>
    <li><a href="https://terminology.hl7.org/SNOMEDCT.html#implicit">Using SNOMED CT with HL7 Standards: Implicit Value Sets</a> (SNOMED CT currently has the most extensive set of defined implicit value set URL patterns)<br/></li>
    <li><a href="https://terminology.hl7.org/LOINC.html#implicit">Using LOINC with HL7 Standards: Implicit Value Sets</a><br/></li>
    <li><a href="https://terminology.hl7.org/RxNorm.html#implicit">Using RxNorm with HL7 Standards: Implicit Value Sets</a><br/></li>
    <li><a href="https://terminology.hl7.org/UCUM.html#4.3.4.5">Using UCUM with HL7 Standards: Implicit Value Sets</a><br/></li>
    <li><a href="https://terminology.hl7.org/CPT.html#4.3.9.6">Using CPT with HL7 Standards: Implicit Value Sets</a><br/></li>
  </ul>
</p>
</div>