View raw Markdown
type: valuesetvalueset: introduction

ValueSet: introduction

Narrative

Scope and Usage

The FHIR terminology specification is based on the concepts of code system and value set originally defined in HL7 v3 Core Principles:

Value sets have 2 aspects:

The ValueSet resource can carry either the .compose or the .expansion, both of them, or neither of them (if only the metadata is being represented). There is an "$expand" operation which can be used to ask a server to generate an expansion given the composition rules, in a particular context, and a "$validate-code" operation which can be used to ask a server to check whether a given code or concept is in the value set in a particular context.

Boundaries and Relationships

Value Sets are used by many resources:

For a full list of uses, see below.

The Characteristics of the ValueSet resource are derived from Formal Value Set Definitions:

Background and Context

When using value sets, proper differentiation between a code system and a value set is important. This is one very common area where significant clinical safety risks occur in practice. Implementers should be familiar with the content in Using Codes in Resources.

ValueSet Identification

A value set has 3 identifiers:

In addition, any expansion for the value set also has ValueSet.expansion.identifier which uniquely identifies each expansion. For further information regarding resource identification, see Resource Identity.

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

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

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

Intensional vs Extensional

A value set may be described as intensional or extensional. The terms intensional and extensional come from the fields of mathematical logic and set theory.

An intensionally defined value set may be algorithmically defined e.g. all codes with the word diabetes in the description. A key benefit of intensionally defined value sets is that their expansion can be dynamically updated without changing the value set definition. This helps healthcare organizations keep current for example, when new drugs (and their associated codes) become available or codes for diseases and other clinical concepts are added.

Extensional value sets, meanwhile, are enumerated lists of codes where each code is listed individually. This gives the author and user of the value set more control over the which codes are in the value set, but there is a greater maintenance burden to ensure that the value set is kept up to date.

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">

<div>
<a name="scope"></a>
<h2>Scope and Usage</h2>
<p>
The FHIR terminology specification is based on the concepts of code system and value set originally defined in <a href="http://www.hl7.org/documentcenter/public/standards/V3/core_principles/infrastructure/coreprinciples/v3modelcoreprinciples.html">HL7 v3 Core Principles</a>:
</p>
<p>
Value sets have 2 aspects:
</p>
<ul>
 <li><code><a href="valueset-definitions.html#ValueSet.compose">.compose</a></code>: A definition of which codes are intended to be in the value set ("intension")</li>
 <li><code><a href="valueset-definitions.html#ValueSet.expansion">.expansion</a></code>: The list of codes that are actually in the value set under a given set of conditions ("extension") - see <a href="valueset.html#expansion">Value Set Expansion</a></li>
</ul>
<p>
The <code>ValueSet</code> resource can carry either the <code>.compose</code> or the <code>.expansion</code>,
both of them, or neither of them (if only the metadata is being represented). There is an <a href="valueset-operation-expand.html">"$expand" operation</a> which can be used to ask a server to generate
an expansion given the composition rules, in a particular context, and a <a href="valueset-operation-validate-code.html">"$validate-code" operation</a> which can be used to ask a server to 
check whether a given code or concept is in the value set in a particular context.
</p>
</div>

<div>
<a name="relationships"></a>
<h2>Boundaries and Relationships</h2>
<p>
Value Sets are used by many resources:
</p>
<ul>
 <li>Value sets use <a href="codesystem.html">CodeSystem</a> resources by referring to them via their canonical reference.</li>
 <li>Value sets are used in <a href="structuredefinition.html">StructureDefinition</a>,  
   <a href="operationdefinition.html#OperationDefinition">OperationDefinition</a>, <a href="questionnaire.html">Questionnaire</a>, and other resources 
   to specify the allowable contents for coded elements, or business rules for data processing</li>
 <li><a href="conceptmap.html">ConceptMap resources</a> describe mappings between value sets</li>
 <li><a href="metadatatypes.html#DataRequirement">DataRequirement</a> data types to specify data processing conditions</li>
</ul>
<p>
For a full list of uses, see below.
</p>
<p>
The Characteristics of the <code>ValueSet</code> resource are derived from Formal Value Set Definitions:
</p>
<ul> 
 <li>The ValueSet resource design is based on the functionality described in the <a href="http://www.omg.org/spec/CTS2/1.0/">OMG CTS 2</a> specification, along 
 with metadata in the HL7 Value Set Definition specification. Value set resources can be converted to CTS2 
 value set or code system instances.</li>
 <li>The value set resource is aligned with the <a href="https://confluence.hl7.org/display/VOC/Characteristics+of+a+Value+Set+Definition+%28VSD%29+Project">Value Set Definition</a> (VSD) project. 
 Not all of the elements defined by the VSD are part of the base resource - some are defined as part of the <a href="valueset-core.html">ValueSet Extensions</a>.
 In the ValueSet resource, the <code>compose</code> element is the VSD "Content Logical definition".</li>
</ul>
</div>

<div>
<a name="context"></a>
<h2>Background and Context</h2>

<p>
When using value sets, proper differentiation between a code system and a value set is important. 
This is one very common area where significant clinical safety risks occur in practice. Implementers
should be familiar with the content in <a href="terminologies.html">Using Codes in Resources</a>.
</p>

<a name="ident"></a>
<h3>ValueSet Identification</h3>
<p>
A value set has 3 identifiers:
</p>
<ul>
 <li><code>ValueSet.id</code>: the <a href="resource.html#id">logical id</a> on the system that holds the value set - this changes as it moves from server to server (this id, with the server address prepended, is called the 'literal identity' of the resource)</li>
 <li><code>ValueSet.url</code>: the canonical URL that never changes for this value set - it is the same in every copy. The element is named <code>url</code> rather than <code>uri</code> for legacy reasons and to strongly encourage providing a resolvable URL as the identifier whenever possible. Ideally, it should be a literal URL that is the location of the master version of the value set, though this is not always possible</li>
 <li><code>ValueSet.identifier</code>: A system/value pair that is used to identify the value set in other contexts (such as an OID in an <a href="https://www.hl7.org/implement/standards/product_brief.cfm?product_id=186">HL7 v3</a> specification)</li>
</ul>
<p>
In addition, any expansion for the value set also has <code>ValueSet.expansion.identifier</code> which uniquely identifies each expansion.
For further information regarding resource identification, see <a href="resource.html#id">Resource Identity</a>.
</p>

<p>
This means that each value set has 2 different URLs that can be used to reference it - its canonical URL (the <code>url</code> element), and its local location from which it may be retrieved (which includes the <code>id</code> element). Because it is common practice to copy (cache) value sets locally, most references to value sets use the canonical URL. 
</p>
<blockquote>
<p>
For example, the value sets published as part of FHIR all have a location ("literal") URI which is the URL where they may be accessed in the FHIR specification itself. Note, though, that while a new version of the FHIR Specification is being prepared, value sets that are published in the drafts will not be found in the current published FHIR specification at their canonical URL. 
</p>
</blockquote>

<p>
Alternatively, the <code>identifier</code> and <code>version</code> elements may be used to reference this value set in a 
design, a profile, a <a href="http://www.hl7.org/implement/standards/product_brief.cfm?product_id=7">CDA</a> template 
or <a href="https://www.hl7.org/implement/standards/product_brief.cfm?product_id=186">HL7 v3</a> message (in the CD data 
type valueSet and valueSetVersion properties). These different contexts may make additional restrictions on the 
possible values of these elements.  The <code>identifier</code> is generally not needed when using value sets in
a FHIR context, where the canonical URL is always the focus.
</p>

<a name="int-ext"></a>
<h3>Intensional vs Extensional</h3>
<p>
A value set may be described as intensional or extensional. The terms intensional and extensional come from the fields of mathematical logic and set theory. 
</p>
<p>
An intensionally defined value set may be algorithmically defined e.g. all codes with the word diabetes in 
the description. A key benefit of intensionally defined value sets is that their expansion can be dynamically 
updated without changing the value set definition. This helps healthcare organizations keep current for example, 
when new drugs (and their associated codes) become available or codes for diseases and other clinical concepts 
are added.
</p>
<p>
Extensional value sets, meanwhile, are enumerated lists of codes where each code is listed individually. This gives the author and user of the value set 
more control over the which codes are in the value set, but there is a greater maintenance burden to ensure that the value set is kept up to date.
</p>

</div>

</div>