This is the Continuous Integration Build of FHIR (will be incorrect/inconsistent at times).
See the Directory of published versions
Terminology Infrastructure Work Group | Maturity Level: N | Normative (from v4.0.0) | Security Category: Anonymous | Compartments: No defined compartments |
A ValueSet resource instance specifies a set of codes drawn from one or more code systems, intended for use in a particular context. Value sets link between CodeSystem definitions and their use in coded elements.
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:
.compose
: A definition of which codes are intended to be in the value set ("intension").expansion
: The list of codes that are actually in the value set under a given set of conditions ("extension") - see Value Set Expansion
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.
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:
compose
element is the VSD "Content Logical definition".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.
A value set has 3 identifiers:
ValueSet.id
: the logical id on the system that holds the value set - this changes as it moves from server to server (this id, with the server address prepended, is called the 'literal identity' of the resource)ValueSet.url
: the canonical URL that never changes for this value set - it is the same in every copy. The element is named url
rather than uri
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 possibleValueSet.identifier
: A system/value pair that is used to identify the value set in other contexts (such as an OID in an HL7 v3 specification)
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.
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.
Structure
Name | Flags | Card. | Type | Description & Constraints | ||||
---|---|---|---|---|---|---|---|---|
ValueSet | N | 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 Interfaces Implemented: MetadataResource | |||||
url | ΣC | 0..1 | uri | Canonical identifier for this value set, represented as a URI (globally unique) + Warning: URL should not contain | or # - these characters make processing canonical references problematic | ||||
identifier | Σ | 0..* | Identifier | Additional identifier for the value set (business identifier) | ||||
version | Σ | 0..1 | string | Business version of the value set | ||||
versionAlgorithm[x] | ΣTU | 0..1 | How to compare versions Binding: Version Algorithm (Extensible) | |||||
versionAlgorithmString | string | |||||||
versionAlgorithmCoding | Coding | |||||||
name | ΣC | 0..1 | string | Name for this value set (computer friendly) | ||||
title | ΣT | 0..1 | string | Name for this value set (human friendly) | ||||
status | ?!Σ | 1..1 | code | draft | active | retired | unknown Binding: PublicationStatus (Required) | ||||
experimental | Σ | 0..1 | boolean | For testing purposes, not real usage | ||||
date | Σ | 0..1 | dateTime | Date last changed | ||||
publisher | ΣT | 0..1 | string | Name of the publisher/steward (organization or individual) | ||||
contact | Σ | 0..* | ContactDetail | Contact details for the publisher | ||||
description | T | 0..1 | markdown | Natural language description of the value set | ||||
useContext | ΣTU | 0..* | UsageContext | The context that the content is intended to support | ||||
jurisdiction | ΣXD | 0..* | CodeableConcept | Intended jurisdiction for value set (if applicable) Binding: Jurisdiction ValueSet (Extensible) | ||||
immutable | Σ | 0..1 | boolean | Indicates whether or not any change to the content logical definition may occur | ||||
purpose | T | 0..1 | markdown | Why this value set is defined | ||||
copyright | T | 0..1 | markdown | Use and/or publishing restrictions | ||||
copyrightLabel | TTU | 0..1 | string | Copyright holder and year(s) | ||||
approvalDate | TU | 0..1 | date | When the ValueSet was approved by publisher | ||||
lastReviewDate | TU | 0..1 | date | When the ValueSet was last reviewed by the publisher | ||||
effectivePeriod | ΣTU | 0..1 | Period | When the ValueSet is expected to be used | ||||
topic | XD | 0..* | CodeableConcept | E.g. Education, Treatment, Assessment, etc Binding: Definition Topic (Example) | ||||
author | TU | 0..* | ContactDetail | Who authored the ValueSet | ||||
editor | TU | 0..* | ContactDetail | Who edited the ValueSet | ||||
reviewer | TU | 0..* | ContactDetail | Who reviewed the ValueSet | ||||
endorser | TU | 0..* | ContactDetail | Who endorsed the ValueSet | ||||
relatedArtifact | TU | 0..* | RelatedArtifact | Additional documentation, citations, etc | ||||
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 | ΣC | 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 | ΣC | 0..1 | uri | The system the codes come from | ||||
version | Σ | 0..1 | string | Specific version of the code system referred to | ||||
concept | C | 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 | C | 0..* | BackboneElement | Additional representations for this concept + Rule: Must have a value for concept.designation.use if concept.designation.additionalUse is present | ||||
language | 0..1 | code | Human language of the designation Binding: All Languages (Required)
| |||||
use | C | 0..1 | Coding | Types of uses of designations Binding: Designation Use (Extensible) | ||||
additionalUse | CTU | 0..* | Coding | Additional ways how this designation would be used Binding: Designation Use (Extensible) | ||||
value | 1..1 | string | The text value for this designation | |||||
filter | ΣC | 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 | child-of | descendent-leaf | exists Binding: Filter Operator (Required) | ||||
value | Σ | 1..1 | string | Code from the system, or regex criteria, or boolean value for exists | ||||
valueSet | ΣC | 0..* | canonical(ValueSet) | Select the contents included in this value set | ||||
copyright | TU | 0..1 | markdown | A copyright statement for the specific code system included in the value set | ||||
exclude | 0..* | see include | Explicitly exclude codes from a code system or other value sets | |||||
property | TU | 0..* | string | Property to return if client doesn't override | ||||
expansion | 0..1 | BackboneElement | Used when the value set is "expanded" | |||||
identifier | 0..1 | uri | Identifies the value set expansion (business identifier) | |||||
next | TU | 0..1 | uri | Opaque urls for paging through expansion results | ||||
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 | |||||||
property | TU | 0..* | BackboneElement | Additional information supplied about each concept | ||||
code | 1..1 | code | Identifies the property on the concepts, and when referred to in operations | |||||
uri | 0..1 | uri | Formal identifier for the property | |||||
contains | C | 0..* | BackboneElement | Codes in the value set + Rule: SHALL have a code or a display + Rule: SHALL have a code if not abstract + Rule: SHALL have a system if a code is present | ||||
system | C | 0..1 | uri | System value for the code | ||||
abstract | C | 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 | C | 0..1 | code | Code - if blank, this is not a selectable code | ||||
display | C | 0..1 | string | User display for the concept | ||||
designation | 0..* | see designation | Additional representations for this item | |||||
property | TU | 0..* | BackboneElement | Property value for the concept | ||||
code | 1..1 | code | Reference to ValueSet.expansion.property.code | |||||
value[x] | 1..1 | Value of the property for this concept | ||||||
valueCode | code | |||||||
valueCoding | Coding | |||||||
valueString | string | |||||||
valueInteger | integer | |||||||
valueBoolean | boolean | |||||||
valueDateTime | dateTime | |||||||
valueDecimal | decimal | |||||||
subProperty | 0..* | BackboneElement | SubProperty value for the concept | |||||
code | 1..1 | code | Reference to ValueSet.expansion.property.code | |||||
value[x] | 1..1 | Value of the subproperty for this concept | ||||||
valueCode | code | |||||||
valueCoding | Coding | |||||||
valueString | string | |||||||
valueInteger | integer | |||||||
valueBoolean | boolean | |||||||
valueDateTime | dateTime | |||||||
valueDecimal | decimal | |||||||
contains | 0..* | see contains | Codes contained under this entry | |||||
scope | TU | 0..1 | BackboneElement | Description of the semantic space the Value Set Expansion is intended to cover and should further clarify the text in ValueSet.description | ||||
inclusionCriteria | 0..1 | markdown | Criteria describing which concepts or codes should be included and why | |||||
exclusionCriteria | 0..1 | markdown | Criteria describing which concepts or codes should be excluded and why | |||||
Documentation for this format |
See the Extensions for this resource
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 --> <versionAlgorithm[x]><!-- 0..1 string|Coding How to compare versions --></versionAlgorithm[x]> <name value="[string]"/><!-- I 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/steward (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 --> <copyrightLabel value="[string]"/><!-- 0..1 Copyright holder and year(s) --> <approvalDate value="[date]"/><!-- 0..1 When the ValueSet was approved by publisher --> <lastReviewDate value="[date]"/><!-- 0..1 When the ValueSet was last reviewed by the publisher --> <effectivePeriod><!-- 0..1 Period When the ValueSet is expected to be used --></effectivePeriod> <topic><!-- 0..* CodeableConcept E.g. Education, Treatment, Assessment, etc --></topic> <author><!-- 0..* ContactDetail Who authored the ValueSet --></author> <editor><!-- 0..* ContactDetail Who edited the ValueSet --></editor> <reviewer><!-- 0..* ContactDetail Who reviewed the ValueSet --></reviewer> <endorser><!-- 0..* ContactDetail Who endorsed the ValueSet --></endorser> <relatedArtifact><!-- 0..* RelatedArtifact Additional documentation, citations, etc --></relatedArtifact> <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]"/><!-- I 0..1 The system the codes come from --> <version value="[string]"/><!-- 0..1 Specific version of the code system referred to --> <concept> <!-- I 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><!-- I 0..1 Coding Types of uses of designations --></use> <additionalUse><!-- I 0..* Coding Additional ways how this designation would be used --></additionalUse> <value value="[string]"/><!-- 1..1 The text value for this designation --> </designation> </concept> <filter> <!-- I 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 | child-of | descendent-leaf | exists --> <value value="[string]"/><!-- 1..1 Code from the system, or regex criteria, or boolean value for exists --> </filter> <valueSet><!-- I 0..* canonical(ValueSet) Select the contents included in this value set --></valueSet> <copyright value="[markdown]"/><!-- 0..1 A copyright statement for the specific code system included in the value set --> </include> <exclude><!-- 0..* Content as for ValueSet.compose.include Explicitly exclude codes from a code system or other value sets --></exclude> <property value="[string]"/><!-- 0..* Property to return if client doesn't override --> </compose> <expansion> <!-- 0..1 Used when the value set is "expanded" --> <identifier value="[uri]"/><!-- 0..1 Identifies the value set expansion (business identifier) --> <next value="[uri]"/><!-- 0..1 Opaque urls for paging through expansion results --> <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> <property> <!-- 0..* Additional information supplied about each concept --> <code value="[code]"/><!-- 1..1 Identifies the property on the concepts, and when referred to in operations --> <uri value="[uri]"/><!-- 0..1 Formal identifier for the property --> </property> <contains> <!-- 0..* Codes in the value set --> <system value="[uri]"/><!-- I 0..1 System value for the code --> <abstract value="[boolean]"/><!-- I 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]"/><!-- I 0..1 Code - if blank, this is not a selectable code --> <display value="[string]"/><!-- I 0..1 User display for the concept --> <designation><!-- 0..* Content as for ValueSet.compose.include.concept.designation Additional representations for this item --></designation> <property> <!-- 0..* Property value for the concept --> <code value="[code]"/><!-- 1..1 Reference to ValueSet.expansion.property.code --> <value[x]><!-- 1..1 code|Coding|string|integer|boolean|dateTime|decimal Value of the property for this concept --></value[x]> <subProperty> <!-- 0..* SubProperty value for the concept --> <code value="[code]"/><!-- 1..1 Reference to ValueSet.expansion.property.code --> <value[x]><!-- 1..1 code|Coding|string|integer|boolean|dateTime|decimal Value of the subproperty for this concept --></value[x]> </subProperty> </property> <contains><!-- 0..* Content as for ValueSet.expansion.contains Codes contained under this entry --></contains> </contains> </expansion> <scope> <!-- 0..1 Description of the semantic space the Value Set Expansion is intended to cover and should further clarify the text in ValueSet.description --> <inclusionCriteria value="[markdown]"/><!-- 0..1 Criteria describing which concepts or codes should be included and why --> <exclusionCriteria value="[markdown]"/><!-- 0..1 Criteria describing which concepts or codes should be excluded and why --> </scope> </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 // versionAlgorithm[x]: How to compare versions. One of these 2: "versionAlgorithmString" : "<string>", "versionAlgorithmCoding" : { Coding }, "name" : "<string>", // I 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/steward (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 "copyrightLabel" : "<string>", // Copyright holder and year(s) "approvalDate" : "<date>", // When the ValueSet was approved by publisher "lastReviewDate" : "<date>", // When the ValueSet was last reviewed by the publisher "effectivePeriod" : { Period }, // When the ValueSet is expected to be used "topic" : [{ CodeableConcept }], // E.g. Education, Treatment, Assessment, etc "author" : [{ ContactDetail }], // Who authored the ValueSet "editor" : [{ ContactDetail }], // Who edited the ValueSet "reviewer" : [{ ContactDetail }], // Who reviewed the ValueSet "endorser" : [{ ContactDetail }], // Who endorsed the ValueSet "relatedArtifact" : [{ RelatedArtifact }], // Additional documentation, citations, etc "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>", // I The system the codes come from "version" : "<string>", // Specific version of the code system referred to "concept" : [{ // I 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 }, // I Types of uses of designations "additionalUse" : [{ Coding }], // I Additional ways how this designation would be used "value" : "<string>" // R! The text value for this designation }] }], "filter" : [{ // I 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 | child-of | descendent-leaf | exists "value" : "<string>" // R! Code from the system, or regex criteria, or boolean value for exists }], "valueSet" : ["<canonical(ValueSet)>"], // I Select the contents included in this value set "copyright" : "<markdown>" // A copyright statement for the specific code system included in the value set }], "exclude" : [{ Content as for ValueSet.compose.include }], // Explicitly exclude codes from a code system or other value sets "property" : ["<string>"] // Property to return if client doesn't override }, "expansion" : { // Used when the value set is "expanded" "identifier" : "<uri>", // Identifies the value set expansion (business identifier) "next" : "<uri>", // Opaque urls for paging through expansion results "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>" }], "property" : [{ // Additional information supplied about each concept "code" : "<code>", // R! Identifies the property on the concepts, and when referred to in operations "uri" : "<uri>" // Formal identifier for the property }], "contains" : [{ // Codes in the value set "system" : "<uri>", // I System value for the code "abstract" : <boolean>, // I 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>", // I Code - if blank, this is not a selectable code "display" : "<string>", // I User display for the concept "designation" : [{ Content as for ValueSet.compose.include.concept.designation }], // Additional representations for this item "property" : [{ // Property value for the concept "code" : "<code>", // R! Reference to ValueSet.expansion.property.code // value[x]: Value of the property for this concept. One of these 7: "valueCode" : "<code>", "valueCoding" : { Coding }, "valueString" : "<string>", "valueInteger" : <integer>, "valueBoolean" : <boolean>, "valueDateTime" : "<dateTime>", "valueDecimal" : <decimal>, "subProperty" : [{ // SubProperty value for the concept "code" : "<code>", // R! Reference to ValueSet.expansion.property.code // value[x]: Value of the subproperty for this concept. One of these 7: "valueCode" : "<code>", "valueCoding" : { Coding }, "valueString" : "<string>", "valueInteger" : <integer>, "valueBoolean" : <boolean>, "valueDateTime" : "<dateTime>", "valueDecimal" : <decimal> }] }], "contains" : [{ Content as for ValueSet.expansion.contains }] // Codes contained under this entry }] }, "scope" : { // Description of the semantic space the Value Set Expansion is intended to cover and should further clarify the text in ValueSet.description "inclusionCriteria" : "<markdown>", // Criteria describing which concepts or codes should be included and why "exclusionCriteria" : "<markdown>" // Criteria describing which concepts or codes should be excluded and why } }
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:url [ uri ] ; # 0..1 Canonical identifier for this value set, represented as a URI (globally unique) fhir:identifier ( [ Identifier ] ... ) ; # 0..* Additional identifier for the value set (business identifier) fhir:version [ string ] ; # 0..1 Business version of the value set # versionAlgorithm[x] : 0..1 How to compare versions. One of these 2 fhir:versionAlgorithm [ a fhir:string ; string ] fhir:versionAlgorithm [ a fhir:Coding ; Coding ] fhir:name [ string ] ; # 0..1 I Name for this value set (computer friendly) fhir:title [ string ] ; # 0..1 Name for this value set (human friendly) fhir:status [ code ] ; # 1..1 draft | active | retired | unknown fhir:experimental [ boolean ] ; # 0..1 For testing purposes, not real usage fhir:date [ dateTime ] ; # 0..1 Date last changed fhir:publisher [ string ] ; # 0..1 Name of the publisher/steward (organization or individual) fhir:contact ( [ ContactDetail ] ... ) ; # 0..* Contact details for the publisher fhir:description [ markdown ] ; # 0..1 Natural language description of the value set fhir:useContext ( [ UsageContext ] ... ) ; # 0..* The context that the content is intended to support fhir:jurisdiction ( [ CodeableConcept ] ... ) ; # 0..* Intended jurisdiction for value set (if applicable) fhir:immutable [ boolean ] ; # 0..1 Indicates whether or not any change to the content logical definition may occur fhir:purpose [ markdown ] ; # 0..1 Why this value set is defined fhir:copyright [ markdown ] ; # 0..1 Use and/or publishing restrictions fhir:copyrightLabel [ string ] ; # 0..1 Copyright holder and year(s) fhir:approvalDate [ date ] ; # 0..1 When the ValueSet was approved by publisher fhir:lastReviewDate [ date ] ; # 0..1 When the ValueSet was last reviewed by the publisher fhir:effectivePeriod [ Period ] ; # 0..1 When the ValueSet is expected to be used fhir:topic ( [ CodeableConcept ] ... ) ; # 0..* E.g. Education, Treatment, Assessment, etc fhir:author ( [ ContactDetail ] ... ) ; # 0..* Who authored the ValueSet fhir:editor ( [ ContactDetail ] ... ) ; # 0..* Who edited the ValueSet fhir:reviewer ( [ ContactDetail ] ... ) ; # 0..* Who reviewed the ValueSet fhir:endorser ( [ ContactDetail ] ... ) ; # 0..* Who endorsed the ValueSet fhir:relatedArtifact ( [ RelatedArtifact ] ... ) ; # 0..* Additional documentation, citations, etc fhir:compose [ # 0..1 Content logical definition of the value set (CLD) fhir:lockedDate [ date ] ; # 0..1 Fixed date for references with no specified version (transitive) fhir:inactive [ boolean ] ; # 0..1 Whether inactive codes are in the value set fhir:include ( [ # 1..* Include one or more codes from a code system or other value set(s) fhir:system [ uri ] ; # 0..1 I The system the codes come from fhir:version [ string ] ; # 0..1 Specific version of the code system referred to fhir:concept ( [ # 0..* I A concept defined in the system fhir:code [ code ] ; # 1..1 Code or expression from system fhir:display [ string ] ; # 0..1 Text to display for this code for this value set in this valueset fhir:designation ( [ # 0..* Additional representations for this concept fhir:language [ code ] ; # 0..1 Human language of the designation fhir:use [ Coding ] ; # 0..1 I Types of uses of designations fhir:additionalUse ( [ Coding ] ... ) ; # 0..* I Additional ways how this designation would be used fhir:value [ string ] ; # 1..1 The text value for this designation ] ... ) ; ] ... ) ; fhir:filter ( [ # 0..* I Select codes/concepts by their properties (including relationships) fhir:property [ code ] ; # 1..1 A property/filter defined by the code system fhir:op [ code ] ; # 1..1 = | is-a | descendent-of | is-not-a | regex | in | not-in | generalizes | child-of | descendent-leaf | exists fhir:value [ string ] ; # 1..1 Code from the system, or regex criteria, or boolean value for exists ] ... ) ; fhir:valueSet ( [ canonical(ValueSet) ] ... ) ; # 0..* I Select the contents included in this value set fhir:copyright [ markdown ] ; # 0..1 A copyright statement for the specific code system included in the value set ] ... ) ; fhir:exclude ( [ See ValueSet.compose.include ] ... ) ; # 0..* Explicitly exclude codes from a code system or other value sets fhir:property ( [ string ] ... ) ; # 0..* Property to return if client doesn't override ] ; fhir:expansion [ # 0..1 Used when the value set is "expanded" fhir:identifier [ uri ] ; # 0..1 Identifies the value set expansion (business identifier) fhir:next [ uri ] ; # 0..1 Opaque urls for paging through expansion results fhir:timestamp [ dateTime ] ; # 1..1 Time ValueSet expansion happened fhir:total [ integer ] ; # 0..1 Total number of codes in the expansion fhir:offset [ integer ] ; # 0..1 Offset at which this resource starts fhir:parameter ( [ # 0..* Parameter that controlled the expansion process fhir:name [ string ] ; # 1..1 Name as assigned by the client or server # value[x] : 0..1 Value of the named parameter. One of these 7 fhir:value [ a fhir:string ; string ] fhir:value [ a fhir:boolean ; boolean ] fhir:value [ a fhir:integer ; integer ] fhir:value [ a fhir:decimal ; decimal ] fhir:value [ a fhir:uri ; uri ] fhir:value [ a fhir:code ; code ] fhir:value [ a fhir:dateTime ; dateTime ] ] ... ) ; fhir:property ( [ # 0..* Additional information supplied about each concept fhir:code [ code ] ; # 1..1 Identifies the property on the concepts, and when referred to in operations fhir:uri [ uri ] ; # 0..1 Formal identifier for the property ] ... ) ; fhir:contains ( [ # 0..* Codes in the value set fhir:system [ uri ] ; # 0..1 I System value for the code fhir:abstract [ boolean ] ; # 0..1 I If user cannot select this entry fhir:inactive [ boolean ] ; # 0..1 If concept is inactive in the code system fhir:version [ string ] ; # 0..1 Version in which this code/display is defined fhir:code [ code ] ; # 0..1 I Code - if blank, this is not a selectable code fhir:display [ string ] ; # 0..1 I User display for the concept fhir:designation ( [ See ValueSet.compose.include.concept.designation ] ... ) ; # 0..* Additional representations for this item fhir:property ( [ # 0..* Property value for the concept fhir:code [ code ] ; # 1..1 Reference to ValueSet.expansion.property.code # value[x] : 1..1 Value of the property for this concept. One of these 7 fhir:value [ a fhir:code ; code ] fhir:value [ a fhir:Coding ; Coding ] fhir:value [ a fhir:string ; string ] fhir:value [ a fhir:integer ; integer ] fhir:value [ a fhir:boolean ; boolean ] fhir:value [ a fhir:dateTime ; dateTime ] fhir:value [ a fhir:decimal ; decimal ] fhir:subProperty ( [ # 0..* SubProperty value for the concept fhir:code [ code ] ; # 1..1 Reference to ValueSet.expansion.property.code # value[x] : 1..1 Value of the subproperty for this concept. One of these 7 fhir:value [ a fhir:code ; code ] fhir:value [ a fhir:Coding ; Coding ] fhir:value [ a fhir:string ; string ] fhir:value [ a fhir:integer ; integer ] fhir:value [ a fhir:boolean ; boolean ] fhir:value [ a fhir:dateTime ; dateTime ] fhir:value [ a fhir:decimal ; decimal ] ] ... ) ; ] ... ) ; fhir:contains ( [ See ValueSet.expansion.contains ] ... ) ; # 0..* Codes contained under this entry ] ... ) ; ] ; fhir:scope [ # 0..1 Description of the semantic space the Value Set Expansion is intended to cover and should further clarify the text in ValueSet.description fhir:inclusionCriteria [ markdown ] ; # 0..1 Criteria describing which concepts or codes should be included and why fhir:exclusionCriteria [ markdown ] ; # 0..1 Criteria describing which concepts or codes should be excluded and why ] ; ]
Changes from both R4 and R4B
ValueSet | |
ValueSet.versionAlgorithm[x] |
|
ValueSet.copyrightLabel |
|
ValueSet.approvalDate |
|
ValueSet.lastReviewDate |
|
ValueSet.effectivePeriod |
|
ValueSet.topic |
|
ValueSet.author |
|
ValueSet.editor |
|
ValueSet.reviewer |
|
ValueSet.endorser |
|
ValueSet.relatedArtifact |
|
ValueSet.compose.include.concept.designation.language |
|
ValueSet.compose.include.concept.designation.additionalUse |
|
ValueSet.compose.include.filter.op |
|
ValueSet.compose.include.copyright |
|
ValueSet.compose.property |
|
ValueSet.expansion.next |
|
ValueSet.expansion.property |
|
ValueSet.expansion.property.code |
|
ValueSet.expansion.property.uri |
|
ValueSet.expansion.contains.property |
|
ValueSet.expansion.contains.property.code |
|
ValueSet.expansion.contains.property.value[x] |
|
ValueSet.expansion.contains.property.subProperty |
|
ValueSet.expansion.contains.property.subProperty.code |
|
ValueSet.expansion.contains.property.subProperty.value[x] |
|
ValueSet.scope |
|
ValueSet.scope.inclusionCriteria |
|
ValueSet.scope.exclusionCriteria |
|
See the Full Difference for further information
This analysis is available for R4 as XML or JSON and for R4B as XML or JSON.
Structure
Name | Flags | Card. | Type | Description & Constraints | ||||
---|---|---|---|---|---|---|---|---|
ValueSet | N | 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 Interfaces Implemented: MetadataResource | |||||
url | ΣC | 0..1 | uri | Canonical identifier for this value set, represented as a URI (globally unique) + Warning: URL should not contain | or # - these characters make processing canonical references problematic | ||||
identifier | Σ | 0..* | Identifier | Additional identifier for the value set (business identifier) | ||||
version | Σ | 0..1 | string | Business version of the value set | ||||
versionAlgorithm[x] | ΣTU | 0..1 | How to compare versions Binding: Version Algorithm (Extensible) | |||||
versionAlgorithmString | string | |||||||
versionAlgorithmCoding | Coding | |||||||
name | ΣC | 0..1 | string | Name for this value set (computer friendly) | ||||
title | ΣT | 0..1 | string | Name for this value set (human friendly) | ||||
status | ?!Σ | 1..1 | code | draft | active | retired | unknown Binding: PublicationStatus (Required) | ||||
experimental | Σ | 0..1 | boolean | For testing purposes, not real usage | ||||
date | Σ | 0..1 | dateTime | Date last changed | ||||
publisher | ΣT | 0..1 | string | Name of the publisher/steward (organization or individual) | ||||
contact | Σ | 0..* | ContactDetail | Contact details for the publisher | ||||
description | T | 0..1 | markdown | Natural language description of the value set | ||||
useContext | ΣTU | 0..* | UsageContext | The context that the content is intended to support | ||||
jurisdiction | ΣXD | 0..* | CodeableConcept | Intended jurisdiction for value set (if applicable) Binding: Jurisdiction ValueSet (Extensible) | ||||
immutable | Σ | 0..1 | boolean | Indicates whether or not any change to the content logical definition may occur | ||||
purpose | T | 0..1 | markdown | Why this value set is defined | ||||
copyright | T | 0..1 | markdown | Use and/or publishing restrictions | ||||
copyrightLabel | TTU | 0..1 | string | Copyright holder and year(s) | ||||
approvalDate | TU | 0..1 | date | When the ValueSet was approved by publisher | ||||
lastReviewDate | TU | 0..1 | date | When the ValueSet was last reviewed by the publisher | ||||
effectivePeriod | ΣTU | 0..1 | Period | When the ValueSet is expected to be used | ||||
topic | XD | 0..* | CodeableConcept | E.g. Education, Treatment, Assessment, etc Binding: Definition Topic (Example) | ||||
author | TU | 0..* | ContactDetail | Who authored the ValueSet | ||||
editor | TU | 0..* | ContactDetail | Who edited the ValueSet | ||||
reviewer | TU | 0..* | ContactDetail | Who reviewed the ValueSet | ||||
endorser | TU | 0..* | ContactDetail | Who endorsed the ValueSet | ||||
relatedArtifact | TU | 0..* | RelatedArtifact | Additional documentation, citations, etc | ||||
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 | ΣC | 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 | ΣC | 0..1 | uri | The system the codes come from | ||||
version | Σ | 0..1 | string | Specific version of the code system referred to | ||||
concept | C | 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 | C | 0..* | BackboneElement | Additional representations for this concept + Rule: Must have a value for concept.designation.use if concept.designation.additionalUse is present | ||||
language | 0..1 | code | Human language of the designation Binding: All Languages (Required)
| |||||
use | C | 0..1 | Coding | Types of uses of designations Binding: Designation Use (Extensible) | ||||
additionalUse | CTU | 0..* | Coding | Additional ways how this designation would be used Binding: Designation Use (Extensible) | ||||
value | 1..1 | string | The text value for this designation | |||||
filter | ΣC | 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 | child-of | descendent-leaf | exists Binding: Filter Operator (Required) | ||||
value | Σ | 1..1 | string | Code from the system, or regex criteria, or boolean value for exists | ||||
valueSet | ΣC | 0..* | canonical(ValueSet) | Select the contents included in this value set | ||||
copyright | TU | 0..1 | markdown | A copyright statement for the specific code system included in the value set | ||||
exclude | 0..* | see include | Explicitly exclude codes from a code system or other value sets | |||||
property | TU | 0..* | string | Property to return if client doesn't override | ||||
expansion | 0..1 | BackboneElement | Used when the value set is "expanded" | |||||
identifier | 0..1 | uri | Identifies the value set expansion (business identifier) | |||||
next | TU | 0..1 | uri | Opaque urls for paging through expansion results | ||||
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 | |||||||
property | TU | 0..* | BackboneElement | Additional information supplied about each concept | ||||
code | 1..1 | code | Identifies the property on the concepts, and when referred to in operations | |||||
uri | 0..1 | uri | Formal identifier for the property | |||||
contains | C | 0..* | BackboneElement | Codes in the value set + Rule: SHALL have a code or a display + Rule: SHALL have a code if not abstract + Rule: SHALL have a system if a code is present | ||||
system | C | 0..1 | uri | System value for the code | ||||
abstract | C | 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 | C | 0..1 | code | Code - if blank, this is not a selectable code | ||||
display | C | 0..1 | string | User display for the concept | ||||
designation | 0..* | see designation | Additional representations for this item | |||||
property | TU | 0..* | BackboneElement | Property value for the concept | ||||
code | 1..1 | code | Reference to ValueSet.expansion.property.code | |||||
value[x] | 1..1 | Value of the property for this concept | ||||||
valueCode | code | |||||||
valueCoding | Coding | |||||||
valueString | string | |||||||
valueInteger | integer | |||||||
valueBoolean | boolean | |||||||
valueDateTime | dateTime | |||||||
valueDecimal | decimal | |||||||
subProperty | 0..* | BackboneElement | SubProperty value for the concept | |||||
code | 1..1 | code | Reference to ValueSet.expansion.property.code | |||||
value[x] | 1..1 | Value of the subproperty for this concept | ||||||
valueCode | code | |||||||
valueCoding | Coding | |||||||
valueString | string | |||||||
valueInteger | integer | |||||||
valueBoolean | boolean | |||||||
valueDateTime | dateTime | |||||||
valueDecimal | decimal | |||||||
contains | 0..* | see contains | Codes contained under this entry | |||||
scope | TU | 0..1 | BackboneElement | Description of the semantic space the Value Set Expansion is intended to cover and should further clarify the text in ValueSet.description | ||||
inclusionCriteria | 0..1 | markdown | Criteria describing which concepts or codes should be included and why | |||||
exclusionCriteria | 0..1 | markdown | Criteria describing which concepts or codes should be excluded and why | |||||
Documentation for this format |
See the Extensions for this resource
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 --> <versionAlgorithm[x]><!-- 0..1 string|Coding How to compare versions --></versionAlgorithm[x]> <name value="[string]"/><!-- I 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/steward (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 --> <copyrightLabel value="[string]"/><!-- 0..1 Copyright holder and year(s) --> <approvalDate value="[date]"/><!-- 0..1 When the ValueSet was approved by publisher --> <lastReviewDate value="[date]"/><!-- 0..1 When the ValueSet was last reviewed by the publisher --> <effectivePeriod><!-- 0..1 Period When the ValueSet is expected to be used --></effectivePeriod> <topic><!-- 0..* CodeableConcept E.g. Education, Treatment, Assessment, etc --></topic> <author><!-- 0..* ContactDetail Who authored the ValueSet --></author> <editor><!-- 0..* ContactDetail Who edited the ValueSet --></editor> <reviewer><!-- 0..* ContactDetail Who reviewed the ValueSet --></reviewer> <endorser><!-- 0..* ContactDetail Who endorsed the ValueSet --></endorser> <relatedArtifact><!-- 0..* RelatedArtifact Additional documentation, citations, etc --></relatedArtifact> <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]"/><!-- I 0..1 The system the codes come from --> <version value="[string]"/><!-- 0..1 Specific version of the code system referred to --> <concept> <!-- I 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><!-- I 0..1 Coding Types of uses of designations --></use> <additionalUse><!-- I 0..* Coding Additional ways how this designation would be used --></additionalUse> <value value="[string]"/><!-- 1..1 The text value for this designation --> </designation> </concept> <filter> <!-- I 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 | child-of | descendent-leaf | exists --> <value value="[string]"/><!-- 1..1 Code from the system, or regex criteria, or boolean value for exists --> </filter> <valueSet><!-- I 0..* canonical(ValueSet) Select the contents included in this value set --></valueSet> <copyright value="[markdown]"/><!-- 0..1 A copyright statement for the specific code system included in the value set --> </include> <exclude><!-- 0..* Content as for ValueSet.compose.include Explicitly exclude codes from a code system or other value sets --></exclude> <property value="[string]"/><!-- 0..* Property to return if client doesn't override --> </compose> <expansion> <!-- 0..1 Used when the value set is "expanded" --> <identifier value="[uri]"/><!-- 0..1 Identifies the value set expansion (business identifier) --> <next value="[uri]"/><!-- 0..1 Opaque urls for paging through expansion results --> <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> <property> <!-- 0..* Additional information supplied about each concept --> <code value="[code]"/><!-- 1..1 Identifies the property on the concepts, and when referred to in operations --> <uri value="[uri]"/><!-- 0..1 Formal identifier for the property --> </property> <contains> <!-- 0..* Codes in the value set --> <system value="[uri]"/><!-- I 0..1 System value for the code --> <abstract value="[boolean]"/><!-- I 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]"/><!-- I 0..1 Code - if blank, this is not a selectable code --> <display value="[string]"/><!-- I 0..1 User display for the concept --> <designation><!-- 0..* Content as for ValueSet.compose.include.concept.designation Additional representations for this item --></designation> <property> <!-- 0..* Property value for the concept --> <code value="[code]"/><!-- 1..1 Reference to ValueSet.expansion.property.code --> <value[x]><!-- 1..1 code|Coding|string|integer|boolean|dateTime|decimal Value of the property for this concept --></value[x]> <subProperty> <!-- 0..* SubProperty value for the concept --> <code value="[code]"/><!-- 1..1 Reference to ValueSet.expansion.property.code --> <value[x]><!-- 1..1 code|Coding|string|integer|boolean|dateTime|decimal Value of the subproperty for this concept --></value[x]> </subProperty> </property> <contains><!-- 0..* Content as for ValueSet.expansion.contains Codes contained under this entry --></contains> </contains> </expansion> <scope> <!-- 0..1 Description of the semantic space the Value Set Expansion is intended to cover and should further clarify the text in ValueSet.description --> <inclusionCriteria value="[markdown]"/><!-- 0..1 Criteria describing which concepts or codes should be included and why --> <exclusionCriteria value="[markdown]"/><!-- 0..1 Criteria describing which concepts or codes should be excluded and why --> </scope> </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 // versionAlgorithm[x]: How to compare versions. One of these 2: "versionAlgorithmString" : "<string>", "versionAlgorithmCoding" : { Coding }, "name" : "<string>", // I 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/steward (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 "copyrightLabel" : "<string>", // Copyright holder and year(s) "approvalDate" : "<date>", // When the ValueSet was approved by publisher "lastReviewDate" : "<date>", // When the ValueSet was last reviewed by the publisher "effectivePeriod" : { Period }, // When the ValueSet is expected to be used "topic" : [{ CodeableConcept }], // E.g. Education, Treatment, Assessment, etc "author" : [{ ContactDetail }], // Who authored the ValueSet "editor" : [{ ContactDetail }], // Who edited the ValueSet "reviewer" : [{ ContactDetail }], // Who reviewed the ValueSet "endorser" : [{ ContactDetail }], // Who endorsed the ValueSet "relatedArtifact" : [{ RelatedArtifact }], // Additional documentation, citations, etc "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>", // I The system the codes come from "version" : "<string>", // Specific version of the code system referred to "concept" : [{ // I 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 }, // I Types of uses of designations "additionalUse" : [{ Coding }], // I Additional ways how this designation would be used "value" : "<string>" // R! The text value for this designation }] }], "filter" : [{ // I 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 | child-of | descendent-leaf | exists "value" : "<string>" // R! Code from the system, or regex criteria, or boolean value for exists }], "valueSet" : ["<canonical(ValueSet)>"], // I Select the contents included in this value set "copyright" : "<markdown>" // A copyright statement for the specific code system included in the value set }], "exclude" : [{ Content as for ValueSet.compose.include }], // Explicitly exclude codes from a code system or other value sets "property" : ["<string>"] // Property to return if client doesn't override }, "expansion" : { // Used when the value set is "expanded" "identifier" : "<uri>", // Identifies the value set expansion (business identifier) "next" : "<uri>", // Opaque urls for paging through expansion results "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>" }], "property" : [{ // Additional information supplied about each concept "code" : "<code>", // R! Identifies the property on the concepts, and when referred to in operations "uri" : "<uri>" // Formal identifier for the property }], "contains" : [{ // Codes in the value set "system" : "<uri>", // I System value for the code "abstract" : <boolean>, // I 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>", // I Code - if blank, this is not a selectable code "display" : "<string>", // I User display for the concept "designation" : [{ Content as for ValueSet.compose.include.concept.designation }], // Additional representations for this item "property" : [{ // Property value for the concept "code" : "<code>", // R! Reference to ValueSet.expansion.property.code // value[x]: Value of the property for this concept. One of these 7: "valueCode" : "<code>", "valueCoding" : { Coding }, "valueString" : "<string>", "valueInteger" : <integer>, "valueBoolean" : <boolean>, "valueDateTime" : "<dateTime>", "valueDecimal" : <decimal>, "subProperty" : [{ // SubProperty value for the concept "code" : "<code>", // R! Reference to ValueSet.expansion.property.code // value[x]: Value of the subproperty for this concept. One of these 7: "valueCode" : "<code>", "valueCoding" : { Coding }, "valueString" : "<string>", "valueInteger" : <integer>, "valueBoolean" : <boolean>, "valueDateTime" : "<dateTime>", "valueDecimal" : <decimal> }] }], "contains" : [{ Content as for ValueSet.expansion.contains }] // Codes contained under this entry }] }, "scope" : { // Description of the semantic space the Value Set Expansion is intended to cover and should further clarify the text in ValueSet.description "inclusionCriteria" : "<markdown>", // Criteria describing which concepts or codes should be included and why "exclusionCriteria" : "<markdown>" // Criteria describing which concepts or codes should be excluded and why } }
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:url [ uri ] ; # 0..1 Canonical identifier for this value set, represented as a URI (globally unique) fhir:identifier ( [ Identifier ] ... ) ; # 0..* Additional identifier for the value set (business identifier) fhir:version [ string ] ; # 0..1 Business version of the value set # versionAlgorithm[x] : 0..1 How to compare versions. One of these 2 fhir:versionAlgorithm [ a fhir:string ; string ] fhir:versionAlgorithm [ a fhir:Coding ; Coding ] fhir:name [ string ] ; # 0..1 I Name for this value set (computer friendly) fhir:title [ string ] ; # 0..1 Name for this value set (human friendly) fhir:status [ code ] ; # 1..1 draft | active | retired | unknown fhir:experimental [ boolean ] ; # 0..1 For testing purposes, not real usage fhir:date [ dateTime ] ; # 0..1 Date last changed fhir:publisher [ string ] ; # 0..1 Name of the publisher/steward (organization or individual) fhir:contact ( [ ContactDetail ] ... ) ; # 0..* Contact details for the publisher fhir:description [ markdown ] ; # 0..1 Natural language description of the value set fhir:useContext ( [ UsageContext ] ... ) ; # 0..* The context that the content is intended to support fhir:jurisdiction ( [ CodeableConcept ] ... ) ; # 0..* Intended jurisdiction for value set (if applicable) fhir:immutable [ boolean ] ; # 0..1 Indicates whether or not any change to the content logical definition may occur fhir:purpose [ markdown ] ; # 0..1 Why this value set is defined fhir:copyright [ markdown ] ; # 0..1 Use and/or publishing restrictions fhir:copyrightLabel [ string ] ; # 0..1 Copyright holder and year(s) fhir:approvalDate [ date ] ; # 0..1 When the ValueSet was approved by publisher fhir:lastReviewDate [ date ] ; # 0..1 When the ValueSet was last reviewed by the publisher fhir:effectivePeriod [ Period ] ; # 0..1 When the ValueSet is expected to be used fhir:topic ( [ CodeableConcept ] ... ) ; # 0..* E.g. Education, Treatment, Assessment, etc fhir:author ( [ ContactDetail ] ... ) ; # 0..* Who authored the ValueSet fhir:editor ( [ ContactDetail ] ... ) ; # 0..* Who edited the ValueSet fhir:reviewer ( [ ContactDetail ] ... ) ; # 0..* Who reviewed the ValueSet fhir:endorser ( [ ContactDetail ] ... ) ; # 0..* Who endorsed the ValueSet fhir:relatedArtifact ( [ RelatedArtifact ] ... ) ; # 0..* Additional documentation, citations, etc fhir:compose [ # 0..1 Content logical definition of the value set (CLD) fhir:lockedDate [ date ] ; # 0..1 Fixed date for references with no specified version (transitive) fhir:inactive [ boolean ] ; # 0..1 Whether inactive codes are in the value set fhir:include ( [ # 1..* Include one or more codes from a code system or other value set(s) fhir:system [ uri ] ; # 0..1 I The system the codes come from fhir:version [ string ] ; # 0..1 Specific version of the code system referred to fhir:concept ( [ # 0..* I A concept defined in the system fhir:code [ code ] ; # 1..1 Code or expression from system fhir:display [ string ] ; # 0..1 Text to display for this code for this value set in this valueset fhir:designation ( [ # 0..* Additional representations for this concept fhir:language [ code ] ; # 0..1 Human language of the designation fhir:use [ Coding ] ; # 0..1 I Types of uses of designations fhir:additionalUse ( [ Coding ] ... ) ; # 0..* I Additional ways how this designation would be used fhir:value [ string ] ; # 1..1 The text value for this designation ] ... ) ; ] ... ) ; fhir:filter ( [ # 0..* I Select codes/concepts by their properties (including relationships) fhir:property [ code ] ; # 1..1 A property/filter defined by the code system fhir:op [ code ] ; # 1..1 = | is-a | descendent-of | is-not-a | regex | in | not-in | generalizes | child-of | descendent-leaf | exists fhir:value [ string ] ; # 1..1 Code from the system, or regex criteria, or boolean value for exists ] ... ) ; fhir:valueSet ( [ canonical(ValueSet) ] ... ) ; # 0..* I Select the contents included in this value set fhir:copyright [ markdown ] ; # 0..1 A copyright statement for the specific code system included in the value set ] ... ) ; fhir:exclude ( [ See ValueSet.compose.include ] ... ) ; # 0..* Explicitly exclude codes from a code system or other value sets fhir:property ( [ string ] ... ) ; # 0..* Property to return if client doesn't override ] ; fhir:expansion [ # 0..1 Used when the value set is "expanded" fhir:identifier [ uri ] ; # 0..1 Identifies the value set expansion (business identifier) fhir:next [ uri ] ; # 0..1 Opaque urls for paging through expansion results fhir:timestamp [ dateTime ] ; # 1..1 Time ValueSet expansion happened fhir:total [ integer ] ; # 0..1 Total number of codes in the expansion fhir:offset [ integer ] ; # 0..1 Offset at which this resource starts fhir:parameter ( [ # 0..* Parameter that controlled the expansion process fhir:name [ string ] ; # 1..1 Name as assigned by the client or server # value[x] : 0..1 Value of the named parameter. One of these 7 fhir:value [ a fhir:string ; string ] fhir:value [ a fhir:boolean ; boolean ] fhir:value [ a fhir:integer ; integer ] fhir:value [ a fhir:decimal ; decimal ] fhir:value [ a fhir:uri ; uri ] fhir:value [ a fhir:code ; code ] fhir:value [ a fhir:dateTime ; dateTime ] ] ... ) ; fhir:property ( [ # 0..* Additional information supplied about each concept fhir:code [ code ] ; # 1..1 Identifies the property on the concepts, and when referred to in operations fhir:uri [ uri ] ; # 0..1 Formal identifier for the property ] ... ) ; fhir:contains ( [ # 0..* Codes in the value set fhir:system [ uri ] ; # 0..1 I System value for the code fhir:abstract [ boolean ] ; # 0..1 I If user cannot select this entry fhir:inactive [ boolean ] ; # 0..1 If concept is inactive in the code system fhir:version [ string ] ; # 0..1 Version in which this code/display is defined fhir:code [ code ] ; # 0..1 I Code - if blank, this is not a selectable code fhir:display [ string ] ; # 0..1 I User display for the concept fhir:designation ( [ See ValueSet.compose.include.concept.designation ] ... ) ; # 0..* Additional representations for this item fhir:property ( [ # 0..* Property value for the concept fhir:code [ code ] ; # 1..1 Reference to ValueSet.expansion.property.code # value[x] : 1..1 Value of the property for this concept. One of these 7 fhir:value [ a fhir:code ; code ] fhir:value [ a fhir:Coding ; Coding ] fhir:value [ a fhir:string ; string ] fhir:value [ a fhir:integer ; integer ] fhir:value [ a fhir:boolean ; boolean ] fhir:value [ a fhir:dateTime ; dateTime ] fhir:value [ a fhir:decimal ; decimal ] fhir:subProperty ( [ # 0..* SubProperty value for the concept fhir:code [ code ] ; # 1..1 Reference to ValueSet.expansion.property.code # value[x] : 1..1 Value of the subproperty for this concept. One of these 7 fhir:value [ a fhir:code ; code ] fhir:value [ a fhir:Coding ; Coding ] fhir:value [ a fhir:string ; string ] fhir:value [ a fhir:integer ; integer ] fhir:value [ a fhir:boolean ; boolean ] fhir:value [ a fhir:dateTime ; dateTime ] fhir:value [ a fhir:decimal ; decimal ] ] ... ) ; ] ... ) ; fhir:contains ( [ See ValueSet.expansion.contains ] ... ) ; # 0..* Codes contained under this entry ] ... ) ; ] ; fhir:scope [ # 0..1 Description of the semantic space the Value Set Expansion is intended to cover and should further clarify the text in ValueSet.description fhir:inclusionCriteria [ markdown ] ; # 0..1 Criteria describing which concepts or codes should be included and why fhir:exclusionCriteria [ markdown ] ; # 0..1 Criteria describing which concepts or codes should be excluded and why ] ; ]
Changes from both R4 and R4B
ValueSet | |
ValueSet.versionAlgorithm[x] |
|
ValueSet.copyrightLabel |
|
ValueSet.approvalDate |
|
ValueSet.lastReviewDate |
|
ValueSet.effectivePeriod |
|
ValueSet.topic |
|
ValueSet.author |
|
ValueSet.editor |
|
ValueSet.reviewer |
|
ValueSet.endorser |
|
ValueSet.relatedArtifact |
|
ValueSet.compose.include.concept.designation.language |
|
ValueSet.compose.include.concept.designation.additionalUse |
|
ValueSet.compose.include.filter.op |
|
ValueSet.compose.include.copyright |
|
ValueSet.compose.property |
|
ValueSet.expansion.next |
|
ValueSet.expansion.property |
|
ValueSet.expansion.property.code |
|
ValueSet.expansion.property.uri |
|
ValueSet.expansion.contains.property |
|
ValueSet.expansion.contains.property.code |
|
ValueSet.expansion.contains.property.value[x] |
|
ValueSet.expansion.contains.property.subProperty |
|
ValueSet.expansion.contains.property.subProperty.code |
|
ValueSet.expansion.contains.property.subProperty.value[x] |
|
ValueSet.scope |
|
ValueSet.scope.inclusionCriteria |
|
ValueSet.scope.exclusionCriteria |
|
See the Full Difference for further information
This analysis is available for R4 as XML or JSON and for R4B as XML or JSON.
Additional definitions: Master Definition XML + JSON, XML Schema/Schematron + JSON Schema, ShEx (for Turtle) , the spreadsheet version & the dependency analysis
Path | ValueSet | Type | Documentation |
---|---|---|---|
ValueSet.versionAlgorithm[x] | VersionAlgorithm | Extensible | Indicates the mechanism used to compare versions to determine which is more current. |
ValueSet.status | PublicationStatus | Required | The lifecycle status of an artifact. |
ValueSet.jurisdiction | JurisdictionValueSet | Extensible | This value set defines a base set of codes for country, country subdivision and region for indicating where a resource is intended to be used. Note: The codes for countries and country subdivisions are taken from ISO 3166 while the codes for "supra-national" regions are from UN Standard country or area codes for statistical use (M49) . |
ValueSet.topic | DefinitionTopic | Example | High-level categorization of the definition, used for searching, sorting, and filtering. |
ValueSet.compose.include.concept.designation.language | AllLanguages (a valid code from Tags for the Identification of Languages ) | Required | This value set includes all possible codes from BCP-47 (see http://tools.ietf.org/html/bcp47) |
Common Languages | starter | ||
ValueSet.compose.include.concept.designation.use | DesignationUse | Extensible | Details of how a designation would be used |
ValueSet.compose.include.concept.designation.additionalUse | DesignationUse | Extensible | Details of how a designation would be used |
ValueSet.compose.include.filter.op | FilterOperator | Required | The kind of operation to perform as a part of a property based filter. |
UniqueKey | Level | Location | Description | Expression |
cnl-0 | Warning | (base) | Name should be usable as an identifier for the module by machine processing applications such as code generation | name.exists() implies name.matches('^[A-Z]([A-Za-z0-9_]){1,254}$') |
cnl-1 | Warning | ValueSet.url | URL should not contain | or # - these characters make processing canonical references problematic | exists() implies matches('^[^|# ]+$') |
vsd-1 | Rule | ValueSet.compose.include | A value set include/exclude SHALL have a value set or a system | valueSet.exists() or system.exists() |
vsd-2 | Rule | ValueSet.compose.include | A value set with concepts or filters SHALL include a system | (concept.exists() or filter.exists()) implies system.exists() |
vsd-3 | Rule | ValueSet.compose.include | Cannot have both concept and filter | concept.empty() or filter.empty() |
vsd-6 | Rule | ValueSet.expansion.contains | SHALL have a code or a display | code.exists() or display.exists() |
vsd-9 | Rule | ValueSet.expansion.contains | SHALL have a code if not abstract | code.exists() or abstract = true |
vsd-10 | Rule | ValueSet.expansion.contains | SHALL have a system if a code is present | code.empty() or system.exists() |
vsd-11 | Rule | ValueSet.compose.include.concept.designation | Must have a value for concept.designation.use if concept.designation.additionalUse is present | additionalUse.exists() implies use.exists() |
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:
include
statements are cumulative - e.g. the value set contains the union of all the includesinclude
, all the criterion apply -e.g. the value set contains the intersection of the criterioninclude
, a single system with selection criteria may be listed, and/or one or more value sets may be listedvalueSet
(s) only: Codes are 'selected' for inclusion if they are in all the referenced value setsSystem
only is specified, the following rules apply:
concept
or filter
: All codes defined by the code system, independent of code status, are includedconcept
: Only the enumerated codes are selectedfilter
: Any codes meeting the filter criteria are selectedvalueSet
and System
: Codes are 'selected' for inclusion if they are selected by the code system selection
(after checking for concept
and filter
) and if they are in all the referenced value sets*
', 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).
Implementation Note: Use of this capability is subject to future clarification and conformance requirements based on implementation experience.
VSD Content Logical Definition (CLD) is analogous to FHIR ValueSet.compose
. The ValueSet author creates the expression (intensional definition), the extensional list, or a text description of ValueSet.scope
and ValueSet.description
. There are three ways to accomplish ValueSet definitions in FHIR:
ValueSet.compose
ValueSet.compose
, must be an expression that aligns with the ValueSet.compose
ValueSet.compose
, must be a computable expression (e.g., ECL)ValueSet.compose
VSD describes filters for the Content Logical Definition. FHIR uses filters in the ValueSet.compose
to implement the VSD features.
Scenario | FHIR 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 |
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 |
(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":
|
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:
ValueSet.compose
may reference other ValueSets.
Intersection:
ValueSet.compose.include
Union:
ValueSet.compose.include
elementsFor 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.
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.
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.
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.
In combination with ValueSet.description
, ValueSet.scope
is used by a ValueSet.author
to communicate the semantic space the ValueSet expansion is intended to cover to other authors and users and to create specific descriptions of what is included and what is excluded. Inclusion criteria should not be used to repeat the Content Logical Definition (ValueSet.compose
) (see the first example below).
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 Name | Description | Scope Inclusion Criteria | Scope Exclusion Criteria |
Body Site Value Set | All SNOMED CT anatomic structures, locations, abnormal structures that can be considered to describe an anatomical site. | Bad Example: SNOMED CT concepts descending from the Anatomical Structure (91723000) or Acquired body structure (body structure) (289115004) or Anatomical site notations for tumor staging (body structure) (258331007) or Body structure, altered from its original anatomical structure (morphologic abnormality) (118956008) or Physical anatomical entity (body structure) (91722005). | None |
Familial Hypercholesterolemia | This value set contains terms defining familial hypercholesterolemia, regardless of genetic origin. | Good Example: Terms identifying familial hypercholesterolemia diagnoses. | Familial combined hyperlipidemia, polygenic hypercholesterolemia, pure hypercholesterolemia not specifically familial. There are no ICD-9-CM codes specific to familial hypercholesterolemia, hence no ICD-9-CM codes are included in this value set. |
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.
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.
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 Value | FHIR Publication Status Value |
Preliminary | Draft |
Active | Active |
Inactive | Retired |
* | Unknown |
Deleted | * |
*There is no equivalent value in either VSD or the PublicationStatus Value Set.
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.
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.
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.
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:
.compose
), return an errorvalueSet
, find the referenced value set by ValueSet.url, expand that (e.g., using the $expand 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.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.
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.
Note that the
CodeSystem
resource and ValueSet.compose
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.
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.
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:
ValueSet.expansion.identifier
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 return in ValueSet.expansion.parameter
, but at a minimum, the list SHOULD include:
The following parameters are predefined by the $expand operation, and are suitable for use in the expansion parameters:
filter |
A text filter that is applied to restrict the codes that are returned (this is useful in a UI context). The interpretation of this is delegated to the server in order to allow to determine the most optimal search approach for the context. The server can document the way this parameter works in TerminologyCapabilities..expansion.textFilter. Typical usage of this parameter includes functionality like:
Text Search engines such as Lucene or Solr, long with their considerable functionality, might also be used. The optional text search might also be code system specific, and servers might have different implementations for different code systems |
date |
The date for which the expansion should be generated. if a date is provided, it means that the server should use the value set / code system definitions as they were on the given date, or return an error if this is not possible. Normally, the date is the current conditions (which is the default value) but under some circumstances, systems need to generate an expansion as it would have been in the past. A typical example of this would be where code selection is constrained to the set of codes that were available when the patient was treated, not when the record is being edited. Note that which date is appropriate is a matter for implementation policy. |
offset |
Paging support - where to start if a subset is desired (default = 0). Offset is number of records (not number of pages) |
count |
Paging support - how many codes should be provided in a partial page view. Paging only applies to flat expansions - servers ignore paging if the expansion is not flat. If count = 0, the client is asking how large the expansion is. Servers SHOULD honor this request for hierarchical expansions as well, and simply return the overall count |
includeDesignations |
Controls whether concept designations are to be included or excluded in value set expansions |
designation |
A token that specifies a system+code that is either a use or a language. Designations that match by language or use are included in the expansion. If no designation is specified, it is at the server discretion which designations to return |
includeDefinition |
Controls whether the value set definition is included or excluded in value set expansions |
activeOnly |
Controls whether inactive concepts are included or excluded in value set expansions. Note that if the value set explicitly specifies that inactive codes are included, this parameter can still remove them from a specific expansion, but this parameter cannot include them if the value set excludes them |
excludeNested |
Controls whether or not the value set expansion may nest codes or not (i.e. ValueSet.expansion.contains.contains). If excludeNested is set to true, the expansion MUST be flat (no nesting). If excludeNested is set to false (default), however, nesting is possible but not required |
excludeNotForUI |
Controls whether or not the value set expansion might include
One purpose of such concepts is helping a user navigate through the list efficiently. If excludeNotForUI is set to true, the concepts as described above will be excluded from the expansion. If excludeNotForUI is set to false (default), all concepts as described above may be part of the expansion. In the FHIR Specification itself, the value set expansions are generated with excludeNotForUI = false, and the expansions used when generating schema / code etc., or performing validation, are all excludeNotForUI = true. |
excludePostCoordinated |
Controls whether or not the value set expansion includes post coordinated codes |
displayLanguage |
Specifies the language to be used for description in the expansions i.e. the language to be used for ValueSet.expansion.contains.display |
exclude-system |
Code system, or a particular version of a code system to be excluded from the value set expansion. The format is the same as a canonical URL: [system]|[version] - e.g. http://loinc.org|2.56 |
system-version |
Specifies a version to use for a system, if the value set does not specify which one to use. The format is the same as a canonical URL: [system]|[version] - e.g. http://loinc.org|2.56 |
check-system-version |
Edge Case: Specifies a version to use for a system. If a value set specifies a different version, an error is returned instead of the expansion. The format is the same as a canonical URL: [system]|[version] - e.g. http://loinc.org|2.56 |
force-system-version |
Edge Case: Specifies a version to use for a system. This parameter overrides any specified version in the value set (and any it depends on). The format is the same as a canonical URL: [system]|[version] - e.g. http://loinc.org|2.56. Note that this has obvious safety issues, in that it may result in a value set expansion giving a different list of codes that is both wrong and unsafe, and implementers should only use this capability reluctantly. It primarily exists to deal with situations where specifications have fallen into decay as time passes. If the value is override, the version used SHALL explicitly be represented 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:
[canonical]#CodeSystem.content |
[content] : The content value for the code system for the canonical URL. Applications generating expansions SHALL use this parameter if the CodeSystem.content value is "fragment" |
[canonical1]#supplement |
[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 |
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]
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.
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.
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).
.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.
.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).
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.
Implicit value sets allow the URI to serve as the basis for ValueSet operations such as $expand and $validate-code without the need to create a defining ValueSet resource instance.
Some advantages of using implicit value sets are that they may be used:
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.
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.
Implementation 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.
Implementers SHOULD NOT create ValueSet resources where the ValueSet.url value matches the pattern of a known implicit value set.
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.
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.
The following links describe the currently defined FHIR implicit value set URL patterns for these listed code systems:
Search parameters for this resource. See also the full list of search parameters for this resource, and check the Extensions registry for search parameters on extensions related to this resource. The common parameters also apply. See Searching for more information about searching in REST, messaging, and services.
Name | Type | Description | Expression | In Common |
code | token | This special parameter searches for codes in the value set. See additional notes on the ValueSet resource | ValueSet.expansion.contains.code | ValueSet.compose.include.concept.code | |
context | token | A use context assigned to the value set | (ValueSet.useContext.value.ofType(CodeableConcept)) | 30 Resources |
context-quantity | quantity | A quantity- or range-valued use context assigned to the value set | (ValueSet.useContext.value.ofType(Quantity)) | (ValueSet.useContext.value.ofType(Range)) | 30 Resources |
context-type TU | token | A type of use context assigned to the value set | ValueSet.useContext.code | 30 Resources |
context-type-quantity TU | composite | A use context type and quantity- or range-based value assigned to the value set | On ValueSet.useContext: context-type: code context-quantity: value.ofType(Quantity) | value.ofType(Range) |
30 Resources |
context-type-value TU | composite | A use context type and value assigned to the value set | On ValueSet.useContext: context-type: code context: value.ofType(CodeableConcept) |
30 Resources |
date | date | The value set publication date | ValueSet.date | 30 Resources |
derived-from TU | reference | A resource that the ValueSet is derived from | ValueSet.relatedArtifact.where(type='derived-from').resource (Any) |
10 Resources |
description | string | The description of the value set | ValueSet.description | 28 Resources |
effective TU | date | The time during which the ValueSet is intended to be in use | ValueSet.effectivePeriod | 12 Resources |
expansion | uri | Identifies the value set expansion (business identifier) | ValueSet.expansion.identifier | |
identifier | token | External identifier for the value set | ValueSet.identifier | 36 Resources |
jurisdiction | token | Intended jurisdiction for the value set | ValueSet.jurisdiction | 26 Resources |
name | string | Computationally friendly name of the value set | ValueSet.name | 27 Resources |
predecessor TU | reference | The predecessor of the ValueSet | ValueSet.relatedArtifact.where(type='predecessor').resource (Any) |
10 Resources |
publisher | string | Name of the publisher of the value set | ValueSet.publisher | 30 Resources |
reference | uri | A code system included or excluded in the value set or an imported value set | ValueSet.compose.include.system | |
status | token | The current status of the value set | ValueSet.status | 36 Resources |
title | string | The human-friendly name of the value set | ValueSet.title | 27 Resources |
topic TU | token | Topics associated with the ValueSet | ValueSet.topic | 10 Resources |
url | uri | The uri that identifies the value set | ValueSet.url | 35 Resources |
version | token | The business version of the value set | ValueSet.version | 31 Resources |