R4 Ballot #1 (Mixed Normative/Trial use) FHIR CI-Build

This page is part of the FHIR Specification (v3.3.0: R4 Ballot 2). The current version which supercedes this version is 5.0.0 . For a full list Continuous Integration Build of available versions, see FHIR (will be incorrect/inconsistent at times).
See the Directory of published versions icon . Page versions: R5 R4B R4 R3 R2

4.8 4.9 Resource ValueSet - Content

Responsible Owner: Vocabulary Terminology Infrastructure icon Work Group Maturity Level : 5   Normative (from v4.0.0) Security Category : Anonymous Compartments : Not linked to any No defined compartments
Normative Candidate Note: This page is candidate normative content for R4 in the Conformance Package . Once normative, it will lose it's Maturity Level, and breaking changes will no longer be made.

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]]] CodeSystem definitions and their use in [coded elements](terminologies.html). coded elements .

4.8.1 4.9.1 Scope and Usage

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

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

Value sets have 2 aspects:

  • .compose : A definition of 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 both. 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. 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.

4.8.2 4.9.2 Boundaries and Relationships

Value Sets are used by many resources:

For a full list of uses, see below.

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

  • The ValueSet resource design is based on the functionality described in the OMG CTS 2 icon specification, along with metadata in the HL7 Value Set Definition specification. Value set resources can be converted to CTS2 value set and or code system instances.
  • The value set resource is aligned with the Value Set Definition icon (VSD) project. Not all of the elements defined by the VSD are part of the base resource - some are defined as part of the ValueSet Extensions . In the ValueSet resource, the compose element is the VSD "Content Logical definition".

4.8.3 4.9.3 Background and Context

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

4.8.3.1

4.9.3.1 ValueSet Identification

A value set has 3 identifiers:

  • ValueSet.id : the logical id on the system that holds the value set - this changes as it moves from server to server (this id, with the server address prepended, is called the 'literal identity' of the resource)
  • ValueSet.url : the canonical URI 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 also to strongly encourage providing a resolvable URL as the identifier whenever possible. Ideally, it should be a literal URL that is the location of the master version of the value set, though this is not always possible
  • ValueSet.identifier : A system/value pair that is used to identify the value set in other contexts (such as an OID in an HL7 v3 icon 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 URI 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 URI. 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 URI. URL.

Alternatively, the identifier and version elements may be used to reference this value set in a design, a profile, a CDA icon template or HL7 v3 icon 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 URI (or "canonical URL") URL is always the focus.

4.9.3.2 Intensional vs Extensional

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

An intensionally defined value set may be algorithmically defined e.g. all codes with the word diabetes in the description. A key benefit of intensionally defined value sets is that their expansion can be dynamically updated without changing the value set definition. This resource 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 referenced by 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.

4.9.4 References to this Resource

4.8.4 4.9.5 Resource Content

Structure

Intended jurisdiction for Use and/or publishing BackboneElement 0..1 Details BackboneElement Uniquely identifies this 1..1 BackboneElement
Name Flags Card. Type Description & Constraints      Filter: Filters doco
. . ValueSet I N DomainResource A set of codes drawn from one or more code systems
+ Status must = 'active' if expansion is present and compose is absent Warning: Name should be usable as an identifier for the module by machine processing applications such as code generation
+ Value set SHALL contain at least one of a compose or an expansion element
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
. . name . versionAlgorithm[x] Σ 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 ?! Σ I 1..1 code draft | active | retired | unknown
Binding: PublicationStatus ( Required )
. . . experimental ?! Σ 0..1 boolean For testing purposes, not only - never for real usage
. . . date Σ 0..1 dateTime Date last changed
. . . publisher Σ T 0..1 string Name of the publisher 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 Σ 0..* CodeableConcept Jurisdiction of the authority that maintains the value set (if applicable)
Binding: Jurisdiction ValueSet icon ( 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 Notice about intellectual property ownership, can include restrictions on use
. . . extensible copyrightLabel T Σ 0..1 string Copyright holder and year(s)
. . . approvalDate 0..1 date boolean When the ValueSet was approved by publisher
... lastReviewDate Whether this 0..1 date When the ValueSet was last reviewed by the publisher
... effectivePeriod Σ 0..1 Period When the ValueSet is intended expected to be used with an extensible binding
. . compose . topic 0..* I CodeableConcept E.g. Education, Treatment, Assessment, etc
Binding: Definition Topic ( Example )

0..1
. . . author Definition of 0..* ContactDetail Who authored the content ValueSet

... editor 0..* ContactDetail Who edited the ValueSet

... reviewer 0..* ContactDetail Who reviewed the ValueSet

... endorser 0..* ContactDetail Who endorsed the ValueSet

... relatedArtifact C 0..* RelatedArtifact Additional documentation, citations, etc
+ Rule: Related artifact can't be depends-on or composed-of

... compose 0..1 BackboneElement Content logical definition of the value set (CLD)
. . . . lockedDate Σ 0..1 date Fixed date for version-less references with no specified version (transitive)
. . . . inactive Σ 0..1 boolean Whether inactive codes are in the value set
. . . . include Σ I 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
+ A value set include/exclude SHALL have a value set or a system
. . . . . system Σ I C 0..1 uri The system the codes come from
. . . . . version Σ 0..1 string Specific version of the code system referred to
. . . . . concept I 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 )
Additional Bindings Purpose
Common Languages Starter

....... use C 0..1 Coding Types of uses of designations
Binding: Designation Use ( Extensible but limited to All Languages )
. . . . . . . use additionalUse C 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 Σ I C 0..* BackboneElement Select codes/concepts by their properties (including relationships)

. . . . . . property Σ 1..1 code A property 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
FilterOperator Binding: Filter Operator ( Required )
. . . . . . value Σ 1..1 string Code from the system, or regex criteria, or boolean value for exists
. . . . . valueSet Σ I C 0..* canonical ( ValueSet ) Select the contents included in this value set

. . . . exclude . copyright 0..1 I markdown A copyright statement for the specific code system included in the value set
0..*
. . . . exclude 0..* see include Explicitly exclude codes from a code system or other value sets

. . . expansion . property 0..* I string Property to return if client doesn't override

0..1
. . . expansion 0..1 BackboneElement Used when the value set is "expanded"
. . . . identifier 0..1 uri Identifies the value set expansion (business identifier)
. . . . timestamp next 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 0..* BackboneElement Additional information supplied about each concept

..... code 1..1 code Identifies the property on the concepts, and when referred to in operations
. . . . contains . uri 0..1 I uri Formal identifier for the property
0..*
. . . . contains C 0..* BackboneElement Codes in the value set
+ Rule: SHALL have a code or a display
+ Must Rule: SHALL have a code if not abstract
+ Must 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 I C 0..1 code Code - if blank, this is not a selectable code
. . . . . display I C 0..1 string User display for the concept
. . . . . designation 0..* see designation Additional representations for this item

. . . . contains . property 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..* see 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


doco Documentation for this format icon

See the Extensions for this resource

UML Diagram ( Legend )

ValueSet ( DomainResource ) + MetadataResource An absolute URI that is used to identify this value set when it is referenced in a specification, model, design or an instance; also called its canonical identifier. This SHOULD be globally unique and SHOULD be a literal address at which an authoritative instance of this value set is (or will be) published published. This URL can be the target of a canonical reference. It SHALL remain the same when the value set is stored on different servers url : uri [0..1] A formal identifier that is used to identify this value set when it is represented in other formats, or referenced in a specification, model, design or an instance identifier : Identifier [0..*] The identifier that is used to identify this version of the value set when it is referenced in a specification, model, design or instance. This is an arbitrary value managed by the value set author and is not expected to be globally unique. For example, it might be a timestamp (e.g. yyyymmdd) if a managed version is not available. There is also no expectation that versions can be placed in a lexicographical sequence version : string [0..1] Indicates the mechanism used to compare versions to determine which ValueSet is more current versionAlgorithm[x] : DataType [0..1] « string | Coding ; null (Strength=Extensible) VersionAlgorithm + » A natural language name identifying the value set. This name should be usable as an identifier for the module by machine processing applications such as code generation name : string [0..1] « This element has or is affected by some invariants C » A short, descriptive, user-friendly title for the value set title : string [0..1] The status of this value set. Enables tracking the life-cycle of the content content. The status of the value set applies to the value set definition (ValueSet.compose) and the associated ValueSet metadata. Expansions do not have a state (this element modifies the meaning of other elements) status : code [1..1] « The lifecycle status of an artifact. null (Strength=Required) PublicationStatus ! » A Boolean value to indicate that this value set is authored for testing purposes (or education/evaluation/marketing) and is not intended to no version of this resource will ever be used intended for genuine usage (this element modifies the meaning of other elements) experimental : boolean [0..1] The date (and optionally time) when the value set was published. The date must change when the business version changes and it must change if the status code changes. In addition, it should change when the substantive metadata or content of the value set changes. (e.g. the 'content logical definition') definition (.compose) was created or revised date : dateTime [0..1] The name of the organization or individual that published responsible for the release and ongoing maintenance of the value set publisher : string [0..1] Contact details to assist a user in finding and communicating with the publisher contact : ContactDetail [0..*] A free text natural language description of the value set from a consumer's perspective perspective. The textual description specifies the span of meanings for concepts to be included within the Value Set Expansion, and also may specify the intended use and limitations of the Value Set description : markdown [0..1] The content was developed with a focus and intent of supporting the contexts that are listed. These terms contexts may be general categories (gender, age, ...) or may be references to specific programs (insurance plans, studies, ...) and may be used to assist with indexing and searching for appropriate value set instances useContext : UsageContext [0..*] A legal or geographic region in which the value set authority that maintains the resource is intended to be used operating. In general, the jurisdiction is also found in the useContext. The useContext may reference additional jurisdictions because the defining jurisdiction does not necessarily limit the jurisdictions of use jurisdiction : CodeableConcept [0..*] « Countries and regions within which this artifact is targeted for use null (Strength=Extensible) Jurisdiction ValueSet JurisdictionValueSet + » If this is set to 'true', then no new versions of the content logical definition can be created. Note: Other metadata might still change immutable : boolean [0..1] Explanation of why this value set is needed and why it has been designed as it has purpose : markdown [0..1] A copyright statement relating to the value set and/or its contents. Copyright statements are generally legal notices of intellectual property ownership and can include restrictions on the use and publishing of the value set copyright : markdown [0..1] Whether this A short string (<50 characters), suitable for inclusion in a page footer that identifies the copyright holder, effective period, and optionally whether rights are restricted. (e.g. 'All rights reserved', 'Some rights reserved') copyrightLabel : string [0..1] The date on which the resource content was approved by the publisher. Approval happens once when the content is intended officially approved for usage approvalDate : date [0..1] The date on which the resource content was last reviewed. Review happens periodically after approval but does not change the original approval date lastReviewDate : date [0..1] The period during which the ValueSet content was or is planned to be used with an extensible binding or not in active use extensible effectivePeriod : boolean Period [0..1] Descriptions related to the content of the ValueSet. Topics provide a high-level categorization as well as keywords for the ValueSet that can be useful for filtering and searching topic : CodeableConcept [0..*] « null (Strength=Example) DefinitionTopic ?? » An individiual or organization primarily involved in the creation and maintenance of the ValueSet author : ContactDetail [0..*] An individual or organization primarily responsible for internal coherence of the ValueSet editor : ContactDetail [0..*] An individual or organization asserted by the publisher to be primarily responsible for review of some aspect of the ValueSet reviewer : ContactDetail [0..*] An individual or organization asserted by the publisher to be responsible for officially endorsing the ValueSet for use in some setting endorser : ContactDetail [0..*] Related artifacts such as additional documentation, justification, dependencies, bibliographic references, and predecessor and successor artifacts relatedArtifact : RelatedArtifact [0..*] Compose If a locked date The Locked Date is defined, then the Content Logical Definition must be evaluated using effective date that is used to determine the current version as of the locked date for all referenced code system(s) Code Systems and value set instances where ValueSet.compose.include.version is Value Set Definitions included in the compose that are not defined already tied to a specific version lockedDate : date [0..1] Whether inactive codes - codes that are not approved for current use - are in the value set. If inactive = true, inactive codes are to be included in the expansion, if inactive = false, the inactive codes will not be included in the expansion. If absent, the behavior is determined by the implementation, or by the applicable ExpansionProfile $expand parameters (but generally, inactive codes would be expected to be included) inactive : boolean [0..1] A property to return in the expansion, if the client doesn't ask for any particular properties. May be either a code from the code system definition (convenient) or a the formal URI that refers to the property. The special value '*' means all properties known to the server property : string [0..*] ConceptSet An absolute URI which is the code system from which the selected codes come from system : uri [0..1] « This element has or is affected by some invariants C » The version of the code system that the codes are selected from from, or the special version '*' for all versions version : string [0..1] Selects the concepts found in this value set (based on its value set definition). This is an absolute URI that is a reference to ValueSet.url. If multiple value sets are specified this includes the union intersection of the contents of all of the referenced value sets valueSet : canonical [0..*] « ValueSet » « This element has or is affected by some invariants C » A copyright statement for the specific code system asserted by the containing ValueSet.compose.include element's system value (if the associated ValueSet.compose.include.version element is not present); or the code system and version combination (if the associated ValueSet.compose.include.version element is present) copyright : markdown [0..1] ConceptReference Specifies a code for the concept to be included or excluded code : code [1..1] The text to display to the user for this concept in the context of this valueset. If no display is provided, then applications using the value set use the display specified for the code by the system display : string [0..1] Designation The language this designation is defined for language : code [0..1] « null (Strength=Required) AllLanguages ! » A human language. code that represents types of uses of designations use : Coding [0..1] « null (Strength=Extensible) Common Languages DesignationUse + » « This element has or is affected by some invariants C » A code Additional codes that details detail how this designation would be used used, if there is more than one use additionalUse : Coding [0..1] [0..*] « Details of how a designation would be used. null (Strength=Extensible) Designation Use DesignationUse + » « This element has or is affected by some invariants C » The text value for this designation value : string [1..1] Filter A code that identifies a property or a filter defined in the code system property : code [1..1] The kind of operation to perform as a part of the filter criteria op : code [1..1] « The kind of operation to perform as a part of a property based filter. null (Strength=Required) FilterOperator ! » The match value may be either a code defined by the system, or a string value, which ValueSet.compose.include.filter.value is represented as a regex match on string, and the literal string of the property value when the operation is 'regex', or one of the values (true and false), when the operation is 'exists' must be [as described](valueset.html#filter-values) value : string [1..1] Expansion An identifier that uniquely identifies this expansion of the valueset. valueset, based on a unique combination of the provided parameters, the system default parameters, and the underlying system code system versions etc. Systems may re-use the same identifier as long as those factors remain the expansion same, and the definition remain expansion is the same, but are not required to do so so. This is a business identifier identifier : uri [0..1] As per paging Search results, the next URLs are opaque to the client, have no dictated structure, and only the server understands them next : uri [0..1] The time at which the expansion was produced by the expanding system timestamp : dateTime [1..1] The total number of concepts in the expansion. If the number of concept nodes in this resource is less than the stated number, then the server can return more using the offset parameter total : integer [0..1] If paging is being used, the offset at which this resource starts. I.e. this resource is a partial view into the expansion. If paging is not being used, this element SHALL not NOT be present offset : integer [0..1] Parameter The name Name of the input parameter to the $expand operation; may be a server-assigned name for additional default or other server-supplied parameters used to control the expansion process name : string [1..1] The value of the parameter value[x] : Type PrimitiveType [0..1] « string | boolean | integer | decimal | uri | code | dateTime » Property A code that is used to identify the property. The code is used in ValueSet.expansion.contains.property.code code : code [1..1] Reference to the formal meaning of the property. One possible source of meaning is the [Concept Properties](codesystem-concept-properties.html) code system uri : uri [0..1] Contains An absolute URI which is the code system in which the code for this item in the expansion is defined system : uri [0..1] « This element has or is affected by some invariants C » If true, this entry is included in the expansion for navigational purposes, and the user cannot select the code directly as a proper value abstract : boolean [0..1] « This element has or is affected by some invariants C » If the concept is inactive in the code system that defines it. Inactive codes are those that are no longer to be used, but are maintained by the code system for understanding legacy data. It might not be known or specified whether an a concept is inactive (and it may depend on the context of use) inactive : boolean [0..1] The version of this the code system that defined from this code and/or display. This should only be used with code systems was taken. Note that do a well-maintained code system does not enforce concept permanence need the version reported, because the meaning of codes is consistent across versions. However this cannot consistently be assured, and when the meaning is not guaranteed to be consistent, the version SHOULD be exchanged version : string [0..1] The code for this item in the expansion hierarchy. If this code is missing the entry in the hierarchy is a place holder (abstract) and does not represent a valid code in the value set code : code [0..1] « This element has or is affected by some invariants C » The recommended display for this item in the expansion display : string [0..1] « This element has or is affected by some invariants C » ConceptProperty A code that is a reference to ValueSet.expansion.property.code code : code [1..1] The value of this property value[x] : DataType [1..1] « code | Coding | string | integer | boolean | dateTime | decimal » ConceptSubProperty A code that is a reference to ValueSet.expansion.property.code code : code [1..1] The value of this subproperty value[x] : DataType [1..1] « code | Coding | string | integer | boolean | dateTime | decimal » Additional representations for this concept when used in this value set - other languages, aliases, specialized purposes, used for particular purposes, etc designation [0..*] Specifies a concept to be included or excluded concept [0..*] Select concepts by specify specifying a matching criteria criterion based on the properties (including relationships) defined by the system, or on filters defined by the system. If multiple filters are specified, specified within the include, they SHALL all be true filter [0..*] Include one or more codes from a code system or other value set(s) include [1..*] Exclude one or more codes from the value set based on code system filters and/or other value sets exclude [0..*] A set of criteria that define the contents of the value set by including or excluding codes selected from the specified code system(s) that the value set draws from. This is also known as the Content Logical Definition (CLD) compose [0..1] A parameter that controlled the expansion process. These parameters may be used by users of expanded value sets to check whether the expansion is suitable for a particular purpose, or to pick the correct expansion parameter [0..*] A property defines an additional slot through which additional information can be provided about a concept property [0..*] Additional representations for this item - other languages, aliases, specialized purposes, used for particular purposes, etc. These are relevant when the conditions of the expansion do not fix to a single correct representation designation [0..*] A subproperty value for this concept subProperty [0..*] A property value for this concept property [0..*] Other codes and entries contained under this entry in the hierarchy contains [0..*] The codes that are contained in the value set expansion contains [0..*] A value set can also be "expanded", where the value set is turned into a simple collection of enumerated codes. This element holds the expansion, if it has been performed expansion [0..1]

XML Template 

<

<ValueSet xmlns="http://hl7.org/fhir"> doco

 <!-- from Resource: id, meta, implicitRules, and language -->
 <!-- from DomainResource: text, contained, extension, and modifierExtension -->
 <

 <url value="[uri]"/><!-- 0..1 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 only - never for 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>
 <
 <</useContext>
 <</jurisdiction>

 <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 Jurisdiction of the authority that maintains the  value set (if applicable) icon --></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 Notice about intellectual property ownership, can include restrictions on use -->
 <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 -->
     <
     <</use>

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

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

  <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 -->
   <
   <</value[x]>

   <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>
</ValueSet>

JSON Template 

{doco
  "resourceType" : "",

  "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 only - never for 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 }], // Jurisdiction of the authority that maintains the  value set (if applicable) icon

  "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>", // Notice about intellectual property ownership, can include restrictions on use
  "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
    }]
  }
}

Turtle Template 

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


[ a fhir:;

[ a fhir:ValueSet;

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

  # from 
  # from 
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
    fhir:
    fhir:
    fhir:
      fhir:
      fhir:
      fhir:
        fhir:
        fhir:
        fhir:
          fhir:
          fhir:
          fhir:
        ], ...;
      ], ...;
      fhir:
        fhir:
        fhir:
        fhir:
      ], ...;
      fhir:
    ], ...;
    fhir:
  ];
  fhir:
    fhir:
    fhir:
    fhir:
    fhir:
    fhir:
      fhir:
      # . One of these 6
        fhir: ]
        fhir: ]
        fhir: ]
        fhir: ]
        fhir: ]
        fhir: ]
    ], ...;
    fhir:
      fhir:
      fhir:
      fhir:
      fhir:
      fhir:
      fhir:
      fhir:
      fhir:
    ], ...;
  ];

  # from Resource: fhir:id, fhir:meta, fhir:implicitRules, and fhir:language
  # from DomainResource: fhir:text, fhir:contained, fhir:extension, and fhir: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 only - never for 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..* Jurisdiction of the authority that maintains the  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 Notice about intellectual property ownership, can include restrictions on use
  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
    ] ... ) ;
  ] ;

]

Changes since R3 from both R4 and R4B

ValueSet
ValueSet.compose.include.filter ValueSet.versionAlgorithm[x]
  • No longer marked as Modifier Added Element
ValueSet.compose.include.filter.value ValueSet.jurisdiction
  • Type changed Change value set from code http://hl7.org/fhir/ValueSet/jurisdiction to string Jurisdiction ValueSet icon
ValueSet.compose.include.valueSet ValueSet.copyrightLabel
  • Type changed from uri to canonical Added Element
ValueSet.approvalDate
  • Added Element
ValueSet.lastReviewDate
  • Added Element
ValueSet.effectivePeriod
  • Added Element
ValueSet.topic
  • Added Element
ValueSet.author
  • Added Element
ValueSet.editor
  • Added Element
ValueSet.reviewer
  • Added Element
ValueSet.endorser
  • Added Element
ValueSet.relatedArtifact
  • Added Element
ValueSet.expansion.identifier ValueSet.compose.include.concept.designation.language
ValueSet.expansion.contains.abstract ValueSet.compose.include.concept.designation.additionalUse
  • Default Value "false" removed Added Element
ValueSet.expansion.contains.inactive ValueSet.compose.include.filter.op
  • Default Value "false" removed Add codes child-of , descendent-leaf
ValueSet.compose.include.copyright
  • Added Element
ValueSet.compose.property
  • Added Element
ValueSet.expansion.next
  • Added Element
ValueSet.expansion.property
  • Added Element
ValueSet.expansion.property.code
  • Added Mandatory Element
ValueSet.expansion.property.uri
  • Added Element
ValueSet.expansion.contains.property
  • Added Element
ValueSet.expansion.contains.property.code
  • Added Mandatory Element
ValueSet.expansion.contains.property.value[x]
  • Added Mandatory Element
ValueSet.expansion.contains.property.subProperty
  • Added Element
ValueSet.expansion.contains.property.subProperty.code
  • Added Mandatory Element
ValueSet.expansion.contains.property.subProperty.value[x]
  • Added Mandatory Element

See the Full Difference for further information

This analysis is available for R4 as XML or JSON . See R2 <--> R3 Conversion Maps (status = 11 tests that all execute ok. 5 fail round-trip testing and 4 r3 resources are invalid (4 errors). ). Note: these have note yet been updated to be R3 to R4 for R4B as XML or JSON .

Structure

Intended jurisdiction for Use and/or publishing BackboneElement 0..1 Details BackboneElement Uniquely identifies this BackboneElement
Name Flags Card. Type Description & Constraints      Filter: Filters doco
. . ValueSet I N DomainResource A set of codes drawn from one or more code systems
+ Status must = 'active' if expansion is present and compose is absent Warning: Name should be usable as an identifier for the module by machine processing applications such as code generation
+ Value set SHALL contain at least one of a compose or an expansion element
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
. . name . versionAlgorithm[x] Σ 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 ?! Σ I 1..1 code draft | active | retired | unknown
Binding: PublicationStatus ( Required )
. . . experimental ?! Σ 0..1 boolean For testing purposes, not only - never for real usage
. . . date Σ 0..1 dateTime Date last changed
. . . publisher Σ T 0..1 string Name of the publisher 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 Σ 0..* CodeableConcept Jurisdiction of the authority that maintains the value set (if applicable)
Binding: Jurisdiction ValueSet icon ( 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 Notice about intellectual property ownership, can include restrictions on use
. . . extensible copyrightLabel T Σ 0..1 string Copyright holder and year(s)
. . . approvalDate 0..1 date boolean When the ValueSet was approved by publisher
... lastReviewDate Whether this 0..1 date When the ValueSet was last reviewed by the publisher
... effectivePeriod Σ 0..1 Period When the ValueSet is intended expected to be used with an extensible binding
. . compose . topic 0..* I CodeableConcept E.g. Education, Treatment, Assessment, etc
Binding: Definition Topic ( Example )

0..1
. . . author Definition of 0..* ContactDetail Who authored the content ValueSet

... editor 0..* ContactDetail Who edited the ValueSet

... reviewer 0..* ContactDetail Who reviewed the ValueSet

... endorser 0..* ContactDetail Who endorsed the ValueSet

... relatedArtifact C 0..* RelatedArtifact Additional documentation, citations, etc
+ Rule: Related artifact can't be depends-on or composed-of

... compose 0..1 BackboneElement Content logical definition of the value set (CLD)
. . . . lockedDate Σ 0..1 date Fixed date for version-less references with no specified version (transitive)
. . . . inactive Σ 0..1 boolean Whether inactive codes are in the value set
. . . . include Σ I 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
+ A value set include/exclude SHALL have a value set or a system
. . . . . system Σ I C 0..1 uri The system the codes come from
. . . . . version Σ 0..1 string Specific version of the code system referred to
. . . . . concept I 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 )
Additional Bindings Purpose
Common Languages Starter

....... use C 0..1 Coding Types of uses of designations
Binding: Designation Use ( Extensible but limited to All Languages )
. . . . . . . use additionalUse C 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 Σ I C 0..* BackboneElement Select codes/concepts by their properties (including relationships)

. . . . . . property Σ 1..1 code A property 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
FilterOperator Binding: Filter Operator ( Required )
. . . . . . value Σ 1..1 string Code from the system, or regex criteria, or boolean value for exists
. . . . . valueSet Σ I C 0..* canonical ( ValueSet ) Select the contents included in this value set

. . . . exclude . copyright 0..1 I markdown A copyright statement for the specific code system included in the value set
0..*
. . . . exclude 0..* see include Explicitly exclude codes from a code system or other value sets

. . . expansion . property 0..* I string Property to return if client doesn't override

0..1
. . . expansion 0..1 BackboneElement Used when the value set is "expanded"
. . . . identifier 0..1 uri Identifies the value set expansion (business identifier)
. . . . timestamp next 0..1 uri Opaque urls for paging through expansion results
1..1
. . . . 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 0..* BackboneElement Additional information supplied about each concept

..... code 1..1 code Identifies the property on the concepts, and when referred to in operations
. . . . contains . uri 0..1 I uri Formal identifier for the property
0..*
. . . . contains C 0..* BackboneElement Codes in the value set
+ Rule: SHALL have a code or a display
+ Must Rule: SHALL have a code if not abstract
+ Must 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 I C 0..1 code Code - if blank, this is not a selectable code
. . . . . display I C 0..1 string User display for the concept
. . . . . designation 0..* see designation Additional representations for this item

. . . . contains . property 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..* see 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


doco Documentation for this format icon

See the Extensions for this resource

UML Diagram ( Legend )

ValueSet ( DomainResource ) + MetadataResource An absolute URI that is used to identify this value set when it is referenced in a specification, model, design or an instance; also called its canonical identifier. This SHOULD be globally unique and SHOULD be a literal address at which an authoritative instance of this value set is (or will be) published published. This URL can be the target of a canonical reference. It SHALL remain the same when the value set is stored on different servers url : uri [0..1] A formal identifier that is used to identify this value set when it is represented in other formats, or referenced in a specification, model, design or an instance identifier : Identifier [0..*] The identifier that is used to identify this version of the value set when it is referenced in a specification, model, design or instance. This is an arbitrary value managed by the value set author and is not expected to be globally unique. For example, it might be a timestamp (e.g. yyyymmdd) if a managed version is not available. There is also no expectation that versions can be placed in a lexicographical sequence version : string [0..1] Indicates the mechanism used to compare versions to determine which ValueSet is more current versionAlgorithm[x] : DataType [0..1] « string | Coding ; null (Strength=Extensible) VersionAlgorithm + » A natural language name identifying the value set. This name should be usable as an identifier for the module by machine processing applications such as code generation name : string [0..1] « This element has or is affected by some invariants C » A short, descriptive, user-friendly title for the value set title : string [0..1] The status of this value set. Enables tracking the life-cycle of the content content. The status of the value set applies to the value set definition (ValueSet.compose) and the associated ValueSet metadata. Expansions do not have a state (this element modifies the meaning of other elements) status : code [1..1] « The lifecycle status of an artifact. null (Strength=Required) PublicationStatus ! » A Boolean value to indicate that this value set is authored for testing purposes (or education/evaluation/marketing) and is not intended to no version of this resource will ever be used intended for genuine usage (this element modifies the meaning of other elements) experimental : boolean [0..1] The date (and optionally time) when the value set was published. The date must change when the business version changes and it must change if the status code changes. In addition, it should change when the substantive metadata or content of the value set changes. (e.g. the 'content logical definition') definition (.compose) was created or revised date : dateTime [0..1] The name of the organization or individual that published responsible for the release and ongoing maintenance of the value set publisher : string [0..1] Contact details to assist a user in finding and communicating with the publisher contact : ContactDetail [0..*] A free text natural language description of the value set from a consumer's perspective perspective. The textual description specifies the span of meanings for concepts to be included within the Value Set Expansion, and also may specify the intended use and limitations of the Value Set description : markdown [0..1] The content was developed with a focus and intent of supporting the contexts that are listed. These terms contexts may be general categories (gender, age, ...) or may be references to specific programs (insurance plans, studies, ...) and may be used to assist with indexing and searching for appropriate value set instances useContext : UsageContext [0..*] A legal or geographic region in which the value set authority that maintains the resource is intended to be used operating. In general, the jurisdiction is also found in the useContext. The useContext may reference additional jurisdictions because the defining jurisdiction does not necessarily limit the jurisdictions of use jurisdiction : CodeableConcept [0..*] « Countries and regions within which this artifact is targeted for use null (Strength=Extensible) Jurisdiction ValueSet JurisdictionValueSet + » If this is set to 'true', then no new versions of the content logical definition can be created. Note: Other metadata might still change immutable : boolean [0..1] Explanation of why this value set is needed and why it has been designed as it has purpose : markdown [0..1] A copyright statement relating to the value set and/or its contents. Copyright statements are generally legal notices of intellectual property ownership and can include restrictions on the use and publishing of the value set copyright : markdown [0..1] Whether this A short string (<50 characters), suitable for inclusion in a page footer that identifies the copyright holder, effective period, and optionally whether rights are restricted. (e.g. 'All rights reserved', 'Some rights reserved') copyrightLabel : string [0..1] The date on which the resource content was approved by the publisher. Approval happens once when the content is intended officially approved for usage approvalDate : date [0..1] The date on which the resource content was last reviewed. Review happens periodically after approval but does not change the original approval date lastReviewDate : date [0..1] The period during which the ValueSet content was or is planned to be used with an extensible binding or not in active use extensible effectivePeriod : boolean Period [0..1] Descriptions related to the content of the ValueSet. Topics provide a high-level categorization as well as keywords for the ValueSet that can be useful for filtering and searching topic : CodeableConcept [0..*] « null (Strength=Example) DefinitionTopic ?? » An individiual or organization primarily involved in the creation and maintenance of the ValueSet author : ContactDetail [0..*] An individual or organization primarily responsible for internal coherence of the ValueSet editor : ContactDetail [0..*] An individual or organization asserted by the publisher to be primarily responsible for review of some aspect of the ValueSet reviewer : ContactDetail [0..*] An individual or organization asserted by the publisher to be responsible for officially endorsing the ValueSet for use in some setting endorser : ContactDetail [0..*] Related artifacts such as additional documentation, justification, dependencies, bibliographic references, and predecessor and successor artifacts relatedArtifact : RelatedArtifact [0..*] Compose If a locked date The Locked Date is defined, then the Content Logical Definition must be evaluated using effective date that is used to determine the current version as of the locked date for all referenced code system(s) Code Systems and value set instances where ValueSet.compose.include.version is Value Set Definitions included in the compose that are not defined already tied to a specific version lockedDate : date [0..1] Whether inactive codes - codes that are not approved for current use - are in the value set. If inactive = true, inactive codes are to be included in the expansion, if inactive = false, the inactive codes will not be included in the expansion. If absent, the behavior is determined by the implementation, or by the applicable ExpansionProfile $expand parameters (but generally, inactive codes would be expected to be included) inactive : boolean [0..1] A property to return in the expansion, if the client doesn't ask for any particular properties. May be either a code from the code system definition (convenient) or a the formal URI that refers to the property. The special value '*' means all properties known to the server property : string [0..*] ConceptSet An absolute URI which is the code system from which the selected codes come from system : uri [0..1] « This element has or is affected by some invariants C » The version of the code system that the codes are selected from from, or the special version '*' for all versions version : string [0..1] Selects the concepts found in this value set (based on its value set definition). This is an absolute URI that is a reference to ValueSet.url. If multiple value sets are specified this includes the union intersection of the contents of all of the referenced value sets valueSet : canonical [0..*] « ValueSet » « This element has or is affected by some invariants C » A copyright statement for the specific code system asserted by the containing ValueSet.compose.include element's system value (if the associated ValueSet.compose.include.version element is not present); or the code system and version combination (if the associated ValueSet.compose.include.version element is present) copyright : markdown [0..1] ConceptReference Specifies a code for the concept to be included or excluded code : code [1..1] The text to display to the user for this concept in the context of this valueset. If no display is provided, then applications using the value set use the display specified for the code by the system display : string [0..1] Designation The language this designation is defined for language : code [0..1] « null (Strength=Required) AllLanguages ! » A human language. code that represents types of uses of designations use : Coding [0..1] « null (Strength=Extensible) Common Languages DesignationUse + » « This element has or is affected by some invariants C » A code Additional codes that details detail how this designation would be used used, if there is more than one use additionalUse : Coding [0..1] [0..*] « Details of how a designation would be used. null (Strength=Extensible) Designation Use DesignationUse + » « This element has or is affected by some invariants C » The text value for this designation value : string [1..1] Filter A code that identifies a property or a filter defined in the code system property : code [1..1] The kind of operation to perform as a part of the filter criteria op : code [1..1] « The kind of operation to perform as a part of a property based filter. null (Strength=Required) FilterOperator ! » The match value may be either a code defined by the system, or a string value, which ValueSet.compose.include.filter.value is represented as a regex match on string, and the literal string of the property value when the operation is 'regex', or one of the values (true and false), when the operation is 'exists' must be [as described](valueset.html#filter-values) value : string [1..1] Expansion An identifier that uniquely identifies this expansion of the valueset. valueset, based on a unique combination of the provided parameters, the system default parameters, and the underlying system code system versions etc. Systems may re-use the same identifier as long as those factors remain the expansion same, and the definition remain expansion is the same, but are not required to do so so. This is a business identifier identifier : uri [0..1] As per paging Search results, the next URLs are opaque to the client, have no dictated structure, and only the server understands them next : uri [0..1] The time at which the expansion was produced by the expanding system timestamp : dateTime [1..1] The total number of concepts in the expansion. If the number of concept nodes in this resource is less than the stated number, then the server can return more using the offset parameter total : integer [0..1] If paging is being used, the offset at which this resource starts. I.e. this resource is a partial view into the expansion. If paging is not being used, this element SHALL not NOT be present offset : integer [0..1] Parameter The name Name of the input parameter to the $expand operation; may be a server-assigned name for additional default or other server-supplied parameters used to control the expansion process name : string [1..1] The value of the parameter value[x] : Type PrimitiveType [0..1] « string | boolean | integer | decimal | uri | code | dateTime » Property A code that is used to identify the property. The code is used in ValueSet.expansion.contains.property.code code : code [1..1] Reference to the formal meaning of the property. One possible source of meaning is the [Concept Properties](codesystem-concept-properties.html) code system uri : uri [0..1] Contains An absolute URI which is the code system in which the code for this item in the expansion is defined system : uri [0..1] « This element has or is affected by some invariants C » If true, this entry is included in the expansion for navigational purposes, and the user cannot select the code directly as a proper value abstract : boolean [0..1] « This element has or is affected by some invariants C » If the concept is inactive in the code system that defines it. Inactive codes are those that are no longer to be used, but are maintained by the code system for understanding legacy data. It might not be known or specified whether an a concept is inactive (and it may depend on the context of use) inactive : boolean [0..1] The version of this the code system that defined from this code and/or display. This should only be used with code systems was taken. Note that do a well-maintained code system does not enforce concept permanence need the version reported, because the meaning of codes is consistent across versions. However this cannot consistently be assured, and when the meaning is not guaranteed to be consistent, the version SHOULD be exchanged version : string [0..1] The code for this item in the expansion hierarchy. If this code is missing the entry in the hierarchy is a place holder (abstract) and does not represent a valid code in the value set code : code [0..1] « This element has or is affected by some invariants C » The recommended display for this item in the expansion display : string [0..1] « This element has or is affected by some invariants C » ConceptProperty A code that is a reference to ValueSet.expansion.property.code code : code [1..1] The value of this property value[x] : DataType [1..1] « code | Coding | string | integer | boolean | dateTime | decimal » ConceptSubProperty A code that is a reference to ValueSet.expansion.property.code code : code [1..1] The value of this subproperty value[x] : DataType [1..1] « code | Coding | string | integer | boolean | dateTime | decimal » Additional representations for this concept when used in this value set - other languages, aliases, specialized purposes, used for particular purposes, etc designation [0..*] Specifies a concept to be included or excluded concept [0..*] Select concepts by specify specifying a matching criteria criterion based on the properties (including relationships) defined by the system, or on filters defined by the system. If multiple filters are specified, specified within the include, they SHALL all be true filter [0..*] Include one or more codes from a code system or other value set(s) include [1..*] Exclude one or more codes from the value set based on code system filters and/or other value sets exclude [0..*] A set of criteria that define the contents of the value set by including or excluding codes selected from the specified code system(s) that the value set draws from. This is also known as the Content Logical Definition (CLD) compose [0..1] A parameter that controlled the expansion process. These parameters may be used by users of expanded value sets to check whether the expansion is suitable for a particular purpose, or to pick the correct expansion parameter [0..*] A property defines an additional slot through which additional information can be provided about a concept property [0..*] Additional representations for this item - other languages, aliases, specialized purposes, used for particular purposes, etc. These are relevant when the conditions of the expansion do not fix to a single correct representation designation [0..*] A subproperty value for this concept subProperty [0..*] A property value for this concept property [0..*] Other codes and entries contained under this entry in the hierarchy contains [0..*] The codes that are contained in the value set expansion contains [0..*] A value set can also be "expanded", where the value set is turned into a simple collection of enumerated codes. This element holds the expansion, if it has been performed expansion [0..1]

XML Template 

<

<ValueSet xmlns="http://hl7.org/fhir"> doco

 <!-- from Resource: id, meta, implicitRules, and language -->
 <!-- from DomainResource: text, contained, extension, and modifierExtension -->
 <

 <url value="[uri]"/><!-- 0..1 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 only - never for 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>
 <
 <</useContext>
 <</jurisdiction>

 <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 Jurisdiction of the authority that maintains the  value set (if applicable) icon --></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 Notice about intellectual property ownership, can include restrictions on use -->
 <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 -->
     <
     <</use>

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

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

  <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 -->
   <
   <</value[x]>

   <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>
</ValueSet>

JSON Template 

{doco
  "resourceType" : "",

  "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 only - never for 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 }], // Jurisdiction of the authority that maintains the  value set (if applicable) icon

  "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>", // Notice about intellectual property ownership, can include restrictions on use
  "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
    }]
  }
}

Turtle Template 

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


[ a fhir:;

[ a fhir:ValueSet;

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

  # from 
  # from 
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
    fhir:
    fhir:
    fhir:
      fhir:
      fhir:
      fhir:
        fhir:
        fhir:
        fhir:
          fhir:
          fhir:
          fhir:
        ], ...;
      ], ...;
      fhir:
        fhir:
        fhir:
        fhir:
      ], ...;
      fhir:
    ], ...;
    fhir:
  ];
  fhir:
    fhir:
    fhir:
    fhir:
    fhir:
    fhir:
      fhir:
      # . One of these 6
        fhir: ]
        fhir: ]
        fhir: ]
        fhir: ]
        fhir: ]
        fhir: ]
    ], ...;
    fhir:
      fhir:
      fhir:
      fhir:
      fhir:
      fhir:
      fhir:
      fhir:
      fhir:
    ], ...;
  ];

  # from Resource: fhir:id, fhir:meta, fhir:implicitRules, and fhir:language
  # from DomainResource: fhir:text, fhir:contained, fhir:extension, and fhir: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 only - never for 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..* Jurisdiction of the authority that maintains the  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 Notice about intellectual property ownership, can include restrictions on use
  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
    ] ... ) ;
  ] ;

]

Changes since DSTU2 from both R4 and R4B

ValueSet
ValueSet.compose.include.filter ValueSet.versionAlgorithm[x]
  • No longer marked as Modifier Added Element
ValueSet.compose.include.filter.value ValueSet.jurisdiction
  • Type changed Change value set from code http://hl7.org/fhir/ValueSet/jurisdiction to string Jurisdiction ValueSet icon
ValueSet.compose.include.valueSet ValueSet.copyrightLabel
  • Type changed from uri to canonical Added Element
ValueSet.approvalDate
  • Added Element
ValueSet.lastReviewDate
  • Added Element
ValueSet.effectivePeriod
  • Added Element
ValueSet.topic
  • Added Element
ValueSet.author
  • Added Element
ValueSet.editor
  • Added Element
ValueSet.reviewer
  • Added Element
ValueSet.endorser
  • Added Element
ValueSet.relatedArtifact
  • Added Element
ValueSet.expansion.identifier ValueSet.compose.include.concept.designation.language
ValueSet.expansion.contains.abstract ValueSet.compose.include.concept.designation.additionalUse
  • Default Value "false" removed Added Element
ValueSet.expansion.contains.inactive ValueSet.compose.include.filter.op
  • Default Value "false" removed Add codes child-of , descendent-leaf
ValueSet.compose.include.copyright
  • Added Element
ValueSet.compose.property
  • Added Element
ValueSet.expansion.next
  • Added Element
ValueSet.expansion.property
  • Added Element
ValueSet.expansion.property.code
  • Added Mandatory Element
ValueSet.expansion.property.uri
  • Added Element
ValueSet.expansion.contains.property
  • Added Element
ValueSet.expansion.contains.property.code
  • Added Mandatory Element
ValueSet.expansion.contains.property.value[x]
  • Added Mandatory Element
ValueSet.expansion.contains.property.subProperty
  • Added Element
ValueSet.expansion.contains.property.subProperty.code
  • Added Mandatory Element
ValueSet.expansion.contains.property.subProperty.value[x]
  • Added Mandatory Element

See the Full Difference for further information

This analysis is available for R4 as XML or JSON . See R2 <--> R3 Conversion Maps (status = 11 tests that all execute ok. 5 fail round-trip testing and 4 r3 resources are invalid (4 errors). ). Note: these have note yet been updated to be R3 to R4 for R4B as XML or JSON .

 

Alternate Additional definitions: Master Definition XML + JSON , XML Schema / Schematron + JSON Schema , ShEx (for Turtle ) + see , the extensions spreadsheet version & the dependency analysis

4.8.4.1 4.9.5.1 Terminology Bindings

ValueSet.status ValueSet.compose.include.concept.designation.language
Path Definition ValueSet Type Reference Documentation
ValueSet.versionAlgorithm[x] The lifecycle status of an artifact. VersionAlgorithm Required 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 Countries and regions within which this artifact is targeted for use JurisdictionValueSet icon Extensible Jurisdiction ValueSet

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 icon while the codes for "supra-national" regions are from UN Standard country or area codes for statistical use (M49) icon.
ValueSet.topic DefinitionTopic Example A human language.

High-level categorization of the definition, used for searching, sorting, and filtering.

ValueSet.compose.include.concept.designation.language Extensible , but limited to All AllLanguages (a valid code from Tags for the Identification of Languages icon ) 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. used

ValueSet.compose.include.concept.designation.additionalUse DesignationUse Extensible Designation Use

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. Required FilterOperator

4.8.4.2 4.9.5.2 Constraints

vsd-10 : On ValueSet.expansion.contains: Must have a system if a code is present ( expression on ValueSet.expansion.contains: code.empty() or system.exists() ) vsd-2 : On ValueSet.compose.include: vsd-5 : Value set SHALL contain at least one of a compose or an expansion element ( expression : compose.exists() or expansion.exists() )
UniqueKey Level Location Description Expression
vsd-1 : On ValueSet.compose.include: img  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}$')
img  cnl-1 Warning ValueSet.url URL should not contain | or # - these characters make processing canonical references problematic exists() implies matches('^[^|# ]+$')
img  vsd-1 Rule ValueSet.compose.include A value set include/exclude SHALL have a value set or a system ( expression on ValueSet.compose.include: valueSet.exists() or system.exists() )
vsd-11 : Status must = 'active' if expansion is present and compose is absent ( expression : status='active' or compose.exists() or expansion.empty() ) img  vsd-2 Rule ValueSet.compose.include A value set with concepts or filters SHALL include a system ( expression on ValueSet.compose.include: (concept.exists() or filter.exists()) implies system.exists() )
vsd-3 : On ValueSet.compose.include: img  vsd-3 Rule ValueSet.compose.include Cannot have both concept and filter ( expression on ValueSet.compose.include: concept.empty() or filter.empty() )
vsd-6 : On ValueSet.expansion.contains: img  vsd-6 Rule ValueSet.expansion.contains SHALL have a code or a display ( expression on ValueSet.expansion.contains: code.exists() or display.exists() )
vsd-9 : On ValueSet.expansion.contains: Must img  vsd-9 Rule ValueSet.expansion.contains SHALL have a code if not abstract ( expression on ValueSet.expansion.contains: code.exists() or abstract = true )
img  vsd-10 Rule ValueSet.expansion.contains SHALL have a system if a code is present code.empty() or system.exists()
img  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()
img  vsd-12 Rule ValueSet.relatedArtifact Related artifact can't be depends-on or composed-of (type in ('depends-on' | 'composed-of')).not()

4.8.5 4.9.6 Composition Rules

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

  • Multiple include statements are cumulative - e.g. the value set contains the union of all the includes
  • Within an include , all the criterion apply -e.g. the value set contains the intersection of the criterion
  • Within an include , a single system with selection criteria may be listed, and/or one or more value sets may be listed. Rules for interpretation: System only : Codes are 'selected' for inclusion if they are selected by the code system selection (see next point) listed
  • valueSet (s) only : Codes are 'selected' for inclusion if they are in all the referenced value sets
  • If a System and valueSet : Codes are 'selected' for inclusion if they are selected by the code system selection and if they are in all the referenced value sets If a system only is specified, the following rules apply:
    • no concept or filter : All codes in defined by the system code system, independent of code status, are included
    • concept : Only the enumerated codes are selected
    • filter : Any codes meeting the filter criteria are selected
  • valueSet 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
  • If the system reference is not version specific and filters are present, then the contents of the value set are open and change over time as the underlying code systems are updated
  • The version reference may be the special value ' * ', 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 .

  • Using the property filters is only possible where the code system in use defines the relevant properties. Note that in some cases the underlying code system defines the logical concepts but not the syntax for exercising them. In such cases, the literal definitions may be provided by a third party
  • In addition to include rules, codes may be excluded. Rules for interpretation of exclude statements match those for includes, but codes in the exlude exclude statements are never in the value set
  • Value sets may include abstract codes - that is, codes designated by the underlying code system as not for use as a selectable concept in a particular context. These abstract codes are typically used as a grouping/searching mechanism, and can be included either by enumerating them, or by using a filter.
  • Any compose.exclude SHALL be processed such that excluded codes are not found in the expansion
  • Any compose.include SHALL NOT reference a CodeSystem supplement.
  • Any compose.exclude SHALL NOT reference a CodeSystem supplement.
  • Required CodeSystem supplements SHALL be declared using either the valueset-supplement extension, or the useSupplement $expand input parameter.

4.9.6.1 Compose

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

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

  • By listing the codes that are in the ValueSet explicitly using ValueSet.compose.include.concept
  • By specifying the codes for inclusion using filter expressions in ValueSet.compose.include.filter
  • If the language in filter cannot be used, using the Extension ValueSet.valueset-expression to define some alternative expression, though this can only be evaluated by a system that understands the syntax used in the expression
  • For a few value sets, there is no formal expression, and the rules are expressed using the Extension ValueSet.valueset-rules-text that is not computable and is meant to be interpreted by a human. Such value sets are rare

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

4.9.6.2 Filters

Mapping from VSD to ValueSet.compose

VSD Scenario FHIR Implementation
When the ValueSet.compose is an expression ( ValueSet.expression ), declare the type of expression here
  • compose.include.filter.op = "property"
  • compose.include.filter.op = regex
  • compose.include.filter.value = "property value"
When the ValueSet.compose describes Concepts to include based on CodeSystem properties

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

Either the Value or Expression must be provided

Value:

  • compose.include.filter.op = "="
  • compose.include.filter.value = the value

Expression:

  • compose.include.filter.op = "regex"
  • compose.include.filter.value = the Expression
When the ValueSet.compose defines the types of relationships between concepts to include in the ValueSet Expansion

compose.filter.property = "RelationshipType"

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

  • compose.filter.property.op = "="
  • compose.filter.property.value = a code defined by the CodeSystem

Example:

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

  • filter.property.name = '272741003'
  • filter.property.op = '='
  • filter.property.value = '7771000'

4.9.6.3 Using Filter Values

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

  • If the op is regex , the format is a regex expression
  • If the op is exists , the format is a boolean ( true or false )
  • If the op is in or not-in , the format is either a comma-separated list of code values, or an absolute uri , which is a canonical reference to a ValueSet. If the value is a code or list of codes, the interpretation of the codes is subject to the CodeSystem e.g. for SNOMED-CT reference sets. If the value is a valueSet uri, then commas and percents should be percent encoded
  • If the property is concept , the format is a code
  • If the name in property refers to a CodeSystem filter , the format is as defined in the filter table on the CodeSystem page, or as described in the applicable CodeSystem.filter.value
  • If the name in property refers to a CodeSystem property , the format is as defined in the following table

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

string Use the string directly
integer Use the integer value directly
boolean Use true or false
dateTime Use ISO 8601 format, following the precision rules for the dateTime data type
decimal Use the decimal value directly
code Use the code directly
Coding Use the format system (| version )# code , which is effectively a canonical reference to the CodeSystem, followed by # and then the code in the CodeSystem. There is no way to specify the display

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

4.9.6.3.1 Code Systems Note

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

HL7 Terminology defines filters for various published code systems:

4.9.6.4 Union and Intersection

ValueSet.compose may reference other ValueSets.

Intersection:

  • If the ValueSet definition contains references to multiple ValueSets within a single ValueSet.compose.include
    • The resulting expansion includes only those concepts that are in each expansion of the included ValueSets

Union:

  • If the ValueSet definition contains references to ValueSets using multiple ValueSet.compose.include elements
    • The resulting expansion includes all concepts from the ValueSet expansions

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

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

4.9.6.5 Referencing CodeSystem Fragments

The VSD Partition aligns with FHIR CodeSystem Fragments .

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

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

4.9.7 ValueSet Alignment with VSD

4.9.7.1 Author and Publisher

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

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

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

4.9.7.2 Scope and Description

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

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

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

Example:

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

4.9.7.3 Name and Title

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

4.9.7.4 Include Active Concepts Only

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

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

4.9.7.5 Status

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

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

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

VSD Activity Status 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.

4.9.8 Display and Designations

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

When a value set enumerates codes, it is sometimes useful to define an alternative display for the code that is to be used wherever the value set is expanded and used in a UI. This facility is provided to cover the following circumstances:

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

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

Any display name for a concept provided in the value set is only used in the UI. for display to a human user. The display in a 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). 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 icon code 55423-8 icon 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.

4.8.6 4.9.9 Value Sets with multiple code systems

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

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

4.8.6.1 Code systems Note

Each Code System defines which filters can be used in ValueSet.compose.include.filter . All Value sets should only include well differentiated concepts, but many value sets and code systems do not have base filters and any additional filters defined in ( CodeSystem.filter) . This specification also defines filters for well differentiated concepts because of various published code systems: real-world constraints.

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

4.8.7 4.9.10 Value Set Expansion

A value set can be "expanded", where the definition of the value set is used to create a simple collection of codes suitable for use for data entry or validation. There is a defined operation $expand to ask a server to perform this expansion. Expansions are most useful when a value set includes all the codes in a code system, or a set of codes by filter.

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

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

  • If the value set already has an expansion (e.g., a stored expansion), simply take expansion):
    • Check that the parameters associated with the $expand operation are consistent with the parameters recorded in the expansion
    • If the parameters are inconsistent, then either generate a new expansion, or, if there is no definition ( .compose ), return an error
    • Additional parameters may be applied to an existing expansion if the server has validated that the result will be the same as it is. If not, then: if the expansion was generated directly from the value set definition (e.g. text filter, designations included).
  • Otherwise: For each compose.include :
    1. If there is a system, identify the correct version of the code system, system , and then:
      • If there are no codes or filters, add every code in the code system to the result set.
      • If codes are listed, check that they are valid, and check their active status, and if ok, add them to the result set (the profile parameter parameters to the $expand operation may be used to control whether active codes are included).
      • If any filters are present, process them in order (as explained above), and add the intersection of their results to the result set.
    2. For each valueSet , find the referenced value set by ValueSet.url, expand that (e.g., using the $expand operation: GET [base]/ValueSet/$expand$url=[compose.include.valueSet]), and add it to the produce a collection of result set. sets. This means that expansion across imports is a recursive process.
    3. Add the intersection of the result set from the system (step 1) and all of the result sets from the value sets (step 2) to the expansion
  • For each compose.exclude , follow the same process as for compose.include , but remove any codes from the result set, expansion in step 3 instead of adding them.
  • When available, ValueSet.status and ValueSet.version from the ValueSet resource instance which contains the definition SHALL be returned in the ValueSet resource instance which contains the expansion.

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

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

 

4.9.10.1 Hierarchical Expansions

The expansion MAY be hierarchical - that is, it may have contains element that contain their own sub-elements, to any level of depth. This specification does not fix the meaning of the hierarchy: there is no implication about the logical relationship between the nested contain elements, and the structure cannot be used for logical inferencing. The structure exists to provide navigational assistance for helping human users to locate codes in the expansion.

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.

4.9.10.2 Uniqueness of Concepts in Expansions

Value set definitions may lead to more than one instruction to include a given concept in the value set across the includes and imports. No matter how many times the definitions include a concept, it is only present in the value set once, and will only appear once in a flat expansion of the value set. Note, however, that a concept may appear more than once in a nested hierarchy when the expansion is prepared for UI use (irrespective of how many times it is included in the definitions). Note that uniqueness is based on system/version/code; it is possible to include the CodeSystem resource and ValueSet.compose offer no support same concept from different versions of a code system in the same expansion, though this is generally confusing for defining hierarchies users and groups, but this does not exclude servers from using extensions or other knowledge to introduce such groups as an implementation feature. should be avoided.

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

4.9.10.3 Expansion Identifiers

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

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

4.9.10.4 Expansion Parameters

The expansion contains a set of parameters in ValueSet.expansion.parameter that record what controlled the expansion process. These parameters may be used by users of expanded value sets to check whether the expansion is suitable for a particular purpose, or to pick the correct expansion. The server decides which parameters to include here, return in ValueSet.expansion.parameter , but at a minimum, the list SHOULD include include:

  • All input parameters defined by the date, filter, $expand operation and profile parameters passed provided by the client and used by the server to generate the expansion
  • All input parameters defined by the $expand operation (if any). If and their values for which the codeSystem server provided default values
  • Canonical or URI references (including version) for all CodeSystems, CodeSystem Supplements and ValueSets used in the expansion

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:

  • using left matching e.g. "acut ast"
  • allowing for wild cards such as %, &, ?
  • searching on definition, designations and display(s)
  • allowing for search conditions (and / or / exclusions)

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 has 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. This includes all elements of the ValueSet, including extensions, with the exception that the id and meta elements would be specific to the expansion, not to the definition value set, and the expansion itself is filled out.

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 then 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 overridden, the version used SHALL explicitly be provided as 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 in if the CodeSystem.content value is "fragment"
[canonical1]#supplement [canonical2] : Indicates that the specified supplement (canonical2) contributed to the content of the expansion (note for the code system canonical1 (by influencing selection, or providing designations). Applications generating expansions SHALL use this parameter to record that not all a supplement was used during the expansion process

There's also some parameters that only go in the response to an expand, so that the server can inform the consumer of the expansion which value sets, code systems have and supplements were used as the basis for the expansion:

used-system uri The canonical URL (system | {version} if available) of a version). code system that was used during the expansion of the value set
used-supplement uri The canonical URL (system | {version} if available) of a code system supplement that was used during the expansion of the value set
used-valueset uri The canonical URL (system | {version} if available) of a different value set that was used during the expansion of the value set

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

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

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

Ongoing feedback is welcome at [link to be provided]

4.9.10.5 Storing Expansions

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

4.8.7.1

4.9.10.6 Searching for codes in value sets

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

4.9.11 Combinations of .compose and .expansion

Use cases for the different combinations:

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

4.9.12 Implicit Value Sets

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:

  • With read-only terminology servers because a ValueSet resource cannot be posted
  • With HTTP GET requests because they are cacheable
  • To enable text searches (google like) for concepts across the entirety of large code systems (e.g., SNOMED CT)
  • To provide a convenient way to reference all or parts of code systems in the definition of a ValueSet or ConceptMap

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:

4.8.8 4.9.13 Search Parameters

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.expansion.repeat(contains).code | ValueSet.compose.include.concept.code
context token A use context assigned to the value set (ValueSet.useContext.value.ofType(CodeableConcept)) 25 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)) 25 Resources
context-type token A type of use context assigned to the value set ValueSet.useContext.code 25 Resources
context-type-quantity 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) 		25 Resources
context-type-value composite A use context type and value assigned to the value set On ValueSet.useContext:
  context-type: code
  context: value.ofType(CodeableConcept) 		25 Resources
date date The value set publication date ValueSet.date 26 Resources
derived-from reference A resource that the ValueSet is derived from ValueSet.relatedArtifact.where(type='derived-from').resource
(Any) 		9 Resources
description string The description of the value set ValueSet.description 24 Resources
effective date The time during which the ValueSet is intended to be in use ValueSet.effectivePeriod 10 Resources
expansion uri Uniquely identifies this Identifies the value set expansion (business identifier) ValueSet.expansion.identifier
experimental token Whether the ValueSet is experimental ValueSet.experimental
identifier token External identifier for the value set ValueSet.identifier 30 Resources
jurisdiction token Intended jurisdiction for Jurisdiction of the authority that maintains the the value set ValueSet.jurisdiction 22 Resources
name string Computationally friendly name of the value set ValueSet.name 24 Resources
predecessor reference The predecessor of the ValueSet ValueSet.relatedArtifact.where(type='predecessor').resource
(Any) 		9 Resources
publisher string Name of the publisher of the value set ValueSet.publisher 26 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 30 Resources
title string The human-friendly name of the value set ValueSet.title 24 Resources
topic token Topics associated with the ValueSet ValueSet.topic 10 Resources
url uri The uri that identifies the value set ValueSet.url 30 Resources
version token The business version of the value set ValueSet.version 27 Resources