A
value
set
specifies
a
set
of
codes
drawn
from
one
or
more
code
systems.
A value set specifies a set of codes drawn from one or more code systems.
6.21.1
Scope
and
Usage
6.24.1
Scope and Usage The
FHIR
terminology
specification
is
based
two
key
concepts,
originally
defined
in
HL7
v3
Core
Principles
code system
- defines a set of codes with meanings (also known as enumeration, terminology, classification, and/or ontology)
value set
- selects a set of codes from those defined by one or more code systems
Code systems define which codes (symbols and/or expressions) exist, and how they are understood. Value sets select a set of codes from one or more code systems to specify which codes can be used in a particular context.
Value sets may be constructed in one of two ways:
A value set can contain an in-line
codeSystem
,
and/or
A
value
set
can
be
, and/or
A value set can be
composed
of
codes
defined
in
other
code
systems,
either
by
listing
the
codes
or
by
providing
a
set
of
selection
criteria
A
value
set
can
also
be
"expanded",
where
the
value
set
is
turned
into
a
simple
collection
of
enumerated
codes.
This
operation
is
performed
to
produce
a
collection
of
codes
that
are
ready
to
use
for
data
entry
or
validation.
An
expanded
value
set
may
also
contain
the
original
definition.
Value
sets
that
contain
inline
code
systems
are
intended
for
small,
simple
code
systems
that
are
found
throughout
the
implementation
context
(e.g.,
lists
of
words,
status
codes,
enumerations).
The
inline
code
system
definition
is
not
intended
to
represent
large
publically
defined
terminologies
such
as
LOINC,
etc.
-
these
terminologies
have
their
own
distribution
formats.
of codes defined in other code systems, either by listing the codes or by providing a set of selection criteria
A value set can also be "expanded", where the value set is turned into a simple collection of enumerated codes. This operation is performed to produce a collection of codes that are ready to use for data entry or validation. An expanded value set may also contain the original definition.
Value sets that contain inline code systems are intended for small, simple code systems that are found throughout the implementation context (e.g., lists of words, status codes, enumerations). The inline code system definition is not intended to represent large publically defined terminologies such as LOINC, etc. - these terminologies have their own distribution formats.
6.21.2
Boundaries
and
Relationships
6.24.2
Boundaries and Relationships Value
sets
are
used
in
The ValueSet resource design is based on the functionality described in the
OMG CTS 2 specification,
along
with
metadata
in
the
HL7
Value
Set
Definition
specification.
Value
set
resources
can
be
converted
to
CTS2
value
set
and
code
system
resources.
The
value
set
resource
is
aligned
with
the
Value
Set
Definition
specification, along with metadata in the HL7 Value Set Definition specification. Value set resources can be converted to CTS2 value set and code system resources.
The value set resource is aligned with the
Value Set Definition (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
(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
lockedDate
,
,
compose
and
and
codeSystem
elements
make
up
the
VSD
Content
Logical
definition.
elements make up the VSD Content Logical definition.
6.21.3
Background
and
Context
6.24.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
.
Each
value
set
has
2
different
URLs
that
can
be
used
to
reference
it
-
its
logical
identifier,
and
its
location.
The
location
of
the
value
set
is
a
URL
by
which
it
may
be
retrieved,
usually
from
a
FHIR
server,
and
is
often
a
relative
reference
to
a
value
set
on
the
same
server.
The
logical
identifier
is
in
the
value
set
itself,
in
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
.
Each value set has 2 different URLs that can be used to reference it - its logical identifier, and its location.
For example, the value sets published as part of FHIR all have a logical URL which is also a location by which they may be accessed in the FHIR specification itself. However, 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 FHIR specification.
Because it is common practice to copy (cache) value sets locally, most references to value sets can be either a logical or a literal URL.
6.21.3.1
6.24.3.1
ValueSet
Identification
ValueSet Identification A
value
set
has
3
identifiers:
ValueSet.id:
the
local
identifier
on
the
system
that
holds
it
-
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
master
identifier
that
never
changes
for
this
value
set
-
it
is
the
same
in
every
copy
(this
is
called
the
'logical
identity'
of
the
resource)
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
A value set has 3 identifiers:
ValueSet.id: the local identifier on the system that holds it - 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 master identifier that never changes for this value set - it is the same in every copy (this is called the 'logical identity' of the resource)
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 specification)
For
further
information,
see
Resource
Identity
.
This
resource
is
referenced
by
specification)
A
set
of
codes
drawn
from
one
or
more
code
systems
A
defined
code
system
(if
present)
SHALL
have
a
different
url
than
the
value
set
url
A set of codes drawn from one or more code systems
Value
set
SHALL
contain
at
least
one
of
a
codeSystem,
a
compose,
or
an
expansion
element
Value set SHALL contain at least one of a a compose, or an expansion element
A
value
set
with
only
one
import
SHALL
also
have
an
include
and/or
an
exclude
unless
the
value
set
includes
and
inline
code
system
A value set with only one import SHALL also have an include and/or an exclude unless the value set includes an inline code system
Indicates
whether
or
not
any
change
to
the
content
logical
definition
may
occur
Indicates whether or not any change to the content logical definition may occur
An
inline
code
system,
which
is
part
of
this
value
set
Codes
must
be
unique
When value set includes codes from elsewhere
Within
a
code
system
definition,
all
the
codes
SHALL
be
unique
A value set composition SHALL have an include or an import
value
1..1
string
The
text
value
for
this
designation
concept
0..*
see
concept
Child
Concepts
(is-a/contains/categorizes)
compose
I
0..1
BackboneElement
When
value
set
includes
codes
from
elsewhere
A
value
set
composition
SHALL
have
an
include
or
an
import
import
Σ
I
0..*
uri
Import
the
contents
of
another
value
set
include
Σ
I
0..*
BackboneElement
Include
one
or
more
codes
from
a
code
system
Cannot
have
both
concept
and
filter
system
Σ
1..1
uri
The
system
the
codes
come
from
version
Σ
0..1
string
Specific
version
of
the
code
system
referred
to
concept
I
0..*
BackboneElement
A
concept
defined
in
the
system
code
1..1
code
Code
or
expression
from
system
display
0..1
string
Test
to
display
for
this
code
for
this
value
set
designation
0..*
see
designation
Additional
representations
for
this
valueset
The text value for this designation
Codes
in
the
value
set
Codes in the value set
Must
have
a
code
if
not
abstract
Must have a code if not abstract
SHALL
have
a
code
or
a
display
SHALL have a code or a display
Must
have
a
system
if
a
code
is
present
Must have a system if a code is present
A
set
of
codes
drawn
from
one
or
more
code
systems
A
defined
code
system
(if
present)
SHALL
have
a
different
url
than
the
value
set
url
A set of codes drawn from one or more code systems
Value
set
SHALL
contain
at
least
one
of
a
codeSystem,
a
compose,
or
an
expansion
element
Value set SHALL contain at least one of a a compose, or an expansion element
A
value
set
with
only
one
import
SHALL
also
have
an
include
and/or
an
exclude
unless
the
value
set
includes
and
inline
code
system
A value set with only one import SHALL also have an include and/or an exclude unless the value set includes an inline code system
Indicates
whether
or
not
any
change
to
the
content
logical
definition
may
occur
Indicates whether or not any change to the content logical definition may occur
An
inline
code
system,
which
is
part
of
this
value
set
Codes
must
be
unique
When value set includes codes from elsewhere
Within
a
code
system
definition,
all
the
codes
SHALL
be
unique
A value set composition SHALL have an include or an import
value
1..1
string
The
text
value
for
this
designation
concept
0..*
see
concept
Child
Concepts
(is-a/contains/categorizes)
compose
I
0..1
BackboneElement
When
value
set
includes
codes
from
elsewhere
A
value
set
composition
SHALL
have
an
include
or
an
import
import
Σ
I
0..*
uri
Import
the
contents
of
another
value
set
include
Σ
I
0..*
BackboneElement
Include
one
or
more
codes
from
a
code
system
Cannot
have
both
concept
and
filter
system
Σ
1..1
uri
The
system
the
codes
come
from
version
Σ
0..1
string
Specific
version
of
the
code
system
referred
to
concept
I
0..*
BackboneElement
A
concept
defined
in
the
system
code
1..1
code
Code
or
expression
from
system
display
0..1
string
Test
to
display
for
this
code
for
this
value
set
designation
0..*
see
designation
Additional
representations
for
this
valueset
The text value for this designation
Codes
in
the
value
set
Codes in the value set
Must
have
a
code
if
not
abstract
Must have a code if not abstract
SHALL
have
a
code
or
a
display
SHALL have a code or a display
Must
have
a
system
if
a
code
is
present
Must have a system if a code is present
Indicates
the
countries,
regions,
disciplines
and
other
aspects
of
use
within
which
this
artifact
is
targeted
for
use.
Indicates the countries, regions, disciplines and other aspects of use within which this artifact is targeted for use.
vsd-1
:
On
ValueSet.compose:
A
value
set
composition
SHALL
have
an
include
or
an
import
(xpath
on
f:ValueSet/f:compose:
exists(f:include)
or
exists(f:import)
: On ValueSet.compose: A value set composition SHALL have an include or an import (
expression
on ValueSet.compose:
include or import
)
vsd-10
:
On
ValueSet.expansion.contains:
Must
have
a
system
if
a
code
is
present
(xpath
on
f:ValueSet/f:expansion/f:contains:
exists(f:system)
or
not(exists(f:code))
: On ValueSet.expansion.contains: Must have a system if a code is present (
expression
on ValueSet.expansion.contains:
code.empty() or system
)
vsd-11
:
On
ValueSet.compose.include:
Cannot
have
both
concept
and
filter
(xpath
on
f:ValueSet/f:compose/f:include:
not(exists(f:concept))
or
not(exists(f:filter))
: On ValueSet.compose.include: Cannot have both concept and filter (
expression
on ValueSet.compose.include:
concept.empty() or filter.empty()
)
vsd-2
:
A
value
set
with
only
one
import
SHALL
also
have
an
include
and/or
an
exclude
unless
the
value
set
includes
and
inline
code
system
(xpath:
not(exists(f:compose))
or
(count(f:compose/f:import)!=1
or
exists(f:compose/f:include)
or
exists(f:compose/f:exclude)
or
exists(f:codeSystem))
)
vsd-3
:
On
ValueSet.codeSystem:
Within
a
code
system
definition,
all
the
codes
SHALL
be
unique
(xpath
on
f:ValueSet/f:codeSystem:
count(distinct-values(descendant::f:concept/f:code/@value))=count(descendant::f:concept)
: A value set with only one import SHALL also have an include and/or an exclude unless the value set includes an inline code system (
expression
:
compose.import.count() != 1 or compose.include or compose.exclude
)
vsd-5
:
Value
set
SHALL
contain
at
least
one
of
a
codeSystem,
a
compose,
or
an
expansion
element
(xpath:
exists(f:codeSystem)
or
exists(f:compose)
or
exists(f:expansion)
: Value set SHALL contain at least one of a a compose, or an expansion element (
expression
:
compose or expansion
)
vsd-6
:
On
ValueSet.expansion.contains:
SHALL
have
a
code
or
a
display
(xpath
on
f:ValueSet/f:expansion/f:contains:
exists(f:code)
or
exists(f:display)
)
vsd-7
:
A
defined
code
system
(if
present)
SHALL
have
a
different
url
than
the
value
set
url
(xpath:
not(f:codeSystem/f:system/@value
=
f:url/@value)
)
vsd-8
:
On
ValueSet.codeSystem:
Codes
must
be
unique
(xpath
on
f:ValueSet/f:codeSystem:
count(descendant::f:concept)=count(distinct-values(descendant::f:concept/f:code/@value))
: On ValueSet.expansion.contains: SHALL have a code or a display (
expression
on ValueSet.expansion.contains:
code or display
)
vsd-9
:
On
ValueSet.expansion.contains:
Must
have
a
code
if
not
abstract
(xpath
on
f:ValueSet/f:expansion/f:contains:
exists(f:code)
or
(f:abstract/@value
=
true())
: On ValueSet.expansion.contains: Must have a code if not abstract (
expression
on ValueSet.expansion.contains:
code or abstract = true
)
6.21.5
Identifier
and
Version
6.24.5
Identifier and Version The
6.21.6
Value
Sets
with
In-line
Code
Systems
6.24.6
Value Sets with In-line Code Systems A
value
set
that
contains
an
inline
code
system
automatically
includes
all
of
the
codes
that
the
code
system
defines.
This
is
useful
for
simple
sets
of
codes
that
are
highly
specific
and
context-dependent.
The
value
set
and
the
code
system
are
both
given
URI
identifiers
by
which
they
may
be
identified
from
elsewhere
(ValueSet.identifier
and
ValueSet.codeSystem.system).
These
identifiers
SHALL
be
different.
A value set that contains an inline code system automatically includes all of the codes that the code system defines. This is useful for simple sets of codes that are highly specific and context-dependent. The value set and the code system are both given URI identifiers by which they may be identified from elsewhere (ValueSet.identifier and ValueSet.codeSystem.system). These identifiers SHALL be different.
ValueSet.codeSystem.system
is
the
URI
that
identifies
these
codes
when
used
in
a
is the URI that identifies these codes when used in a
Coding
The
usability
of
the
codes
is
closely
linked
to
the
quality
of
the
definitions.
Although
a
definition
is
not
required
for
each
concept,
a
good
definition
SHOULD
be
provided.
In
the
absence
of
any
definition,
there
is
no
formal
meaning
associated
with
the
concept.
This
specification
does
not
fix
the
meaning
of
the
relationship
between
parent
and
child
codes.
Most
code
systems
use
a
subsumption
based
approach,
but
other
kinds
of
relationships
are
possible,
including
partitive
and
categorization
relationships.
The
definitions
of
the
concepts
dictate
the
nature
of
the
relationship.
An
abstract
concept
SHALL
have
contained
concepts
The
code
system
SHALL
NOT
contain
duplicate
codes
Note:
Value
sets
only
contain
inline
code
systems
when
they
are
not
defined
elsewhere,
such
as
in
SNOMED
CT,
LOINC,
RxNorm,
etc.,
which
have
their
own
public
distributions.
To
specify
a
value
set
that
is
made
up
of
codes
from
other
code
systems,
see
"compose"
below.
The usability of the codes is closely linked to the quality of the definitions. Although a definition is not required for each concept, a good definition SHOULD be provided. In the absence of any definition, there is no formal meaning associated with the concept.
This specification does not fix the meaning of the relationship between parent and child codes. Most code systems use a subsumption based approach, but other kinds of relationships are possible, including partitive and categorization relationships. The definitions of the concepts dictate the nature of the relationship.
An abstract concept SHALL have contained concepts
The code system SHALL NOT contain duplicate codes
Note: Value sets only contain inline code systems when they are not defined elsewhere, such as in SNOMED CT, LOINC, RxNorm, etc., which have their own public distributions. To specify a value set that is made up of codes from other code systems, see "compose" below.
6.21.6.1
Versioning
Code
Systems
6.24.6.1
Versioning Code Systems Most
code
systems
evolve
over
time,
due
to
corrections,
clarifications,
and
changes
to
approach
or
underlying
knowledge
or
reality.
If
these
changes
lead
to
the
meanings
of
existing
codes
changing
significantly,
then
the
interpretation
of
the
code
system
becomes
version
dependent.
This
significantly
complicates
implementation
based
on
the
code
system,
to
the
point
where
it
is
not
clear
that
safety
can
be
assured,
so
changing
the
meaning
of
an
existing
code
SHOULD
be
avoided
whenever
possible.
It
is
preferable
to
assign
a
new
identifier
to
a
code
system
when
any
concepts
in
it
have
a
significant
change
in
meaning
(for
example,
the
German
diagnostic
classification
code
system
ICD10GM2009
has
a
different
system
to
ICD10GM2008),
but
this
also
can
have
substantial
impact
on
implementation,
so
is
often
not
practical
-
for
instance,
SNOMED
CT
has
a
complex
version
release
framework,
which
may
lead
to
variations
in
meaning
of
concepts,
but
there
is
only
one
identifier
for
SNOMED
CT.
For
this
reason,
a
code
Most code systems evolve over time, due to corrections, clarifications, and changes to approach or underlying knowledge or reality. If these changes lead to the meanings of existing codes changing significantly, then the interpretation of the code system becomes version dependent. This significantly complicates implementation based on the code system, to the point where it is not clear that safety can be assured, so changing the meaning of an existing code SHOULD be avoided whenever possible. It is preferable to assign a new identifier to a code system when any concepts in it have a significant change in meaning (for example, the German diagnostic classification code system ICD10GM2009 has a different
system
MAY
provide
a
version
identifier
which
can
be
specified
in
to ICD10GM2008), but this also can have substantial impact on implementation, so is often not practical - for instance,
SNOMED CT
has a complex version release framework, which may lead to variations in meaning of concepts, but there is only one identifier for SNOMED CT.
For this reason, a code system MAY provide a version identifier which can be specified in
ValueSet.codeSystem.version
.
The
version
specific
identifier
SHOULD
be
provided
whenever
there
are
potentially
significant
changes
in
meaning
across
multiple
releases
of
a
code
system.
There
is
no
particular
format
requirement
for
the
version
identifier,
though
HL7
recommends
a
date
based
approach.
When
the
value
set
definition
includes
a
code
system
version
identifier,
the
version
identifier
SHOULD
be
used
in
. The version specific identifier SHOULD be provided whenever there are potentially significant changes in meaning across multiple releases of a code system. There is no particular format requirement for the version identifier, though HL7 recommends a date based approach.
Where the terminology does not clearly define what string should be used to identify code system versions, the recommendation is to use as the version string the date (expressed in FHIR date format) on which the version of the code system that is being used was officially published.
6.21.7
Value
Sets
that
include
codes
defined
elsewhere
6.24.7
Value Sets that include codes defined elsewhere Value
sets
that
include
codes
defined
in
some
other
code
system
are
most
useful
when
dealing
with
large
general
code
systems
such
as
SNOMED
CT,
LOINC,
RxNorm
or
various
IETF
code
sets,
including
human
language.
The
value
set
can
be
a
simple
list
of
included
codes,
or
it
can
be
some
kind
of
general
selection
criteria
using
the
facilities
provided
by
the
code
system.
For
these
value
sets:
Within
an
include
or
exclude
criterion,
multiple
filters
and
concept
selections
are
intersected.
All
of
the
conditions
specified
SHALL
be
true.
An
include
statement
consists
of
any
enumerated
codes
and
any
codes
that
meet
the
filter
criteria.
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
content
of
the
value
set
is
constructed
by
unioning
of
all
the
import
and
include
statements
and
then
eliminating
any
of
the
'excluded'
codes.
A
value
set
needs
to
do
something.
It
can't
simply
include
an
existing
value
set
without
also
including
additional
content
or
excluding
content.
Using
the
property
filters
is
only
possible
where
the
underlying
code
system
defines
appropriate
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.
See
below
for
notes
about
its
use
against
common
code
systems.
Value
sets
may
include
abstract
codes
-
that
is,
codes
designated
by
the
underlying
code
system
as
not
for
use
as
a
real
concept.
These
abstract
codes
are
typically
used
as
a
grouping/searching
mechanism,
and
can
be
included
either
by
enumerating
them,
or
by
using
a
filter.
When
a
value
set
enumerates
codes,
it
is
also
able
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.
The
display
name
for
the
code
in
the
value
set
is
only
used
in
the
UI.
The
display
in
a
Value sets that include codes defined in some other code system are most useful when dealing with large general code systems such as SNOMED CT, LOINC, RxNorm or various IETF code sets, including human language. The value set can be a simple list of included codes, or it can be some kind of general selection criteria using the facilities provided by the code system. For these value sets:
Within an include or exclude criterion, multiple filters and concept selections are intersected. All of the conditions specified SHALL be true.
An include statement consists of any enumerated codes and any codes that meet the filter criteria.
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 content of the value set is constructed by unioning of all the import and include statements and then eliminating any of the 'excluded' codes.
A value set needs to do something. It can't simply include an existing value set without also including additional content or excluding content.
Using the property filters is only possible where the underlying code system defines appropriate 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. See below for notes about its use against common code systems.
Value sets may include abstract codes - that is, codes designated by the underlying code system as not for use as a real concept. These abstract codes are typically used as a grouping/searching mechanism, and can be included either by enumerating them, or by using a filter.
When a value set enumerates codes, it is also able 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.
6.21.8
Value
Sets
with
multiple
code
systems
6.24.8
Value Sets with multiple code systems Value
sets
may
select
codes
from
multiple
code
systems
-
either
by
including
codes
from
different
systems,
importing
other
value
sets
that
include
them,
and/or
containing
their
own
code
system.
Note
that
a
value
set
always
includes
any
codes
in
an
inline
code
system,
even
if
it
also
has
a
compose.
A
typical
use
for
containing
both
a
compose
statement
and
an
inline
code
system
is
when
including
a
set
of
codes
from
elsewhere,
and
adding
a
few
additional
codes
to
cover
cases
not
catered
to
by
the
included
codes.
Best
Practice
Note:
Mixing
definitional
systems
offers
the
potential
for
confusing,
overlapping,
and
inconsistent
definitions.
Creating
value
sets
that
cross
code
systems
should
be
done
with
care
to
avoid
creating
definitional
confusion.
Value sets may select codes from multiple code systems - either by including codes from different systems, importing other value sets that include them, and/or containing their own code system.
Note that a value set always includes any codes in an inline code system, even if it also has a compose. A typical use for containing both a compose statement and an inline code system is when including a set of codes from elsewhere, and adding a few additional codes to cover cases not catered to by the included 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.
6.21.8.1
Code
systems
Note
6.24.8.1
Code systems Note How
filters
are
used
with
various
code
systems:
6.21.9
Value
Set
Expansion
6.24.9
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.
This
is
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
(
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. This is 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 (
codeSystem
and
and
compose
elements).
In
addition,
it
has
an
expansion
element
which
contains
the
list
of
codes
that
constitute
the
value
set
expansion.
If
the
elements). In addition, it has an
expansion
has
nested
element which contains the list of codes that constitute the value set expansion. If the expansion has 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
codes
in
the
expansion.
When
a
request
for
an
expansion
is
received
(e.g.,
for
the
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 codes in the expansion.
For each
compose.include
,
identify
the
correct
version
of
the
code
system,
and
then:
If
there
are
no
codes
or
filters,
add
every
code
in
the
code
system
to
the
result
set.
If
codes
are
listed,
check
that
they
are
valid,
and
check
their
active
status,
and
if
ok,
add
them
to
the
result
set
(the
profile
parameter
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.
For
each
, identify the correct version of the code system, and then:
If there are no codes or filters, add every code in the code system to the result set.
If codes are listed, check that they are valid, and check their active status, and if ok, add them to the result set (the profile parameter 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.
For each
compose.exclude
,
follow
the
same
process
as
for
, follow the same process as for
compose.include
,
but
remove
any
codes
from
the
result
set,
instead
of
adding
them.
Add
any
codes
in
the
, but remove any codes from the result set, instead of adding them.
Add any codes in the
codeSystem
to
the
result
set.
The
"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
specification
does
not
fix
the
meaning
of
use
of
either
of
these,
and
the
conceptual
approach
described
should
not
be
understood
to
prohibit
any
implementation
approach
in
these
regards.
There
is
a
defined
operation
to
ask
a
server
to
perform
this
expansion.
An
expansion
may
include
entries
in
the
to the result set.
The "result set" is then represented in
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.
Note
that
the
value
set
. Note that the expansion structure is inherently ordered, and also provides support for a hierarchical tree of items. This specification does not fix the meaning of use of either of these, and the conceptual approach described should not be understood to prohibit any implementation approach in these regards. There is a
defined operation
to ask a server to perform this expansion.
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. Note that the value set
codeSystem
and
and
compose
offer
no
support
for
defining
these,
but
this
does
not
exclude
servers
from
using
extensions
or
other
knowledge
to
introduce
such
groups
as
an
implementation
feature.
The
codes
in
the
expansion
should
be
treated
as
case
sensitive
-
implementers
should
use
the
correct
case.
Implementers
can
consult
the
definition
of
the
code
system
to
determine
whether
the
code
system
that
defines
the
code
is
case
sensitive
or
not.
Whether
to
store
expanded
value
sets,
or
simply
to
store
their
definitions
and
expand
on
the
fly
is
a
matter
for
system
deployment.
Some
servers,
including
public
value
sets
servers,
only
store
expansions.
However
any
system
that
stores
an
expansion
must
be
concerned
with
how
to
determine
whether
the
expansion
is
still
current,
and
this
requires
deep
knowledge
of
how
the
expansion
was
created.
A
system
with
a
dedicated
terminology
server
that
returns
expansions
on
demand
avoids
this
problem,
but
leaves
open
the
question
of
how
to
audit
the
specific
expansion
that
was
used
for
a
particular
case.
One
solution
to
this
is
to
use
a
dedicated
terminology
server,
and
have
the
clients
ask
for
expansions
on
demand
based
on
the
value
set
definitions,
and
for
the
server
to
store
(and
reuse
as
appropriate)
the
returned
expansion
(when
it
reuses
the
expansion,
ValueSet.expansion.identifier
will
be
the
same).
offer no support for defining these, but this does not exclude servers from using extensions or other knowledge to introduce such groups as an implementation feature.
The codes in the expansion should be treated as case sensitive - implementers should use the correct case. Implementers can consult the definition of the code system to determine whether the code system that defines the code is case sensitive or not.
Whether to store expanded value sets, or simply to store their definitions and expand on the fly is a matter for system deployment. Some servers, including public value sets servers, only store expansions. However any system that stores an expansion must be concerned with how to determine whether the expansion is still current, and this requires deep knowledge of how the expansion was created. A system with a dedicated terminology server that returns expansions on demand avoids this problem, but leaves open the question of how to audit the specific expansion that was used for a particular case. One solution to this is to use a dedicated terminology server, and have the clients ask for expansions on demand based on the value set definitions, and for the server to store (and reuse as appropriate) the returned expansion (when it reuses the expansion, ValueSet.expansion.identifier will be the same).
6.21.9.1
Code
systems
with
detailed
metadata
6.24.9.1
Code systems with detailed metadata Sometimes
code
systems
may
be
used
to
represent
more
complex
information
than
just
code,
display
name
and
code
system.
For
example,
a
code
system
of
drug
information
which
contains
information
about
the
content
of
the
medication
(e.g.,
RxNorm),
or
a
set
of
observation
types,
that
contain
methods,
units,
etc.
(e.g.,
LOINC).
In
FHIR,
these
are
handled
by
splitting
the
concept
into
two
distinct
parts
-
the
It allows generic systems that support terminology management to perform standard terminology operations on code systems dealing with complex structures - code lookup, validation, subsumption testing, mapping and translation.
It allows information to be exchanged about individual medications, data elements and locations. Codes can't be retrieved individually in FHIR - it is necessary to retrieve the entire resource. By packaging the detailed information in separate resources, independent retrieval and update is possible.
It supports use-cases for sharing medication, location, observation type and similar information in circumstances where the code may be unknown, unavailable or occasionally non-existent (e.g., custom compounds, non-registered locations). Having a distinct resource supports these capabilities, which would not be possible using
ValueSet
.
Note
that
this
division
in
FHIR
does
not
imply
that
a
similar
division
is
required
in
the
internal
representation
used
by
systems
exposing
a
FHIR
interface.
Similarly,
some
systems
may
choose
to
only
expose
or
maintain
one
aspect
of
such
information
types
(i.e.
only
the
discrete
resource
instances
or
only
the
value
set).
The
linkage
between
the
"detail"
resource
and
the
Note that this division in FHIR does not imply that a similar division is required in the internal representation used by systems exposing a FHIR interface. Similarly, some systems may choose to only expose or maintain one aspect of such information types (i.e. only the discrete resource instances or only the value set).
The linkage between the "detail" resource and the
ValueSet
is
accomplished
via
the
is accomplished via the
code
element
(or
equivalent)
on
the
detail
resource.
As
well,
the
"name"
or
"title"
on
the
detail
resource
generally
corresponds
with
the
display
name
on
the
matching
code.
Most
detail
resources
will
also
have
an
"identifier"
element.
This
element (or equivalent) on the detail resource. As well, the "name" or "title" on the detail resource generally corresponds with the display name on the matching code. Most detail resources will also have an "identifier" element. This
can
be
set
to
the
same
value
and
namespace
as
the
code,
but
if
the
only
identifier
a
resource
has
is
its
defining
code,
it
may
be
better
to
omit
the
identifier
entirely.
be set to the same value and namespace as the code, but if the only identifier a resource has is its defining code, it may be better to omit the identifier entirely.
6.21.10
Search
Parameters
6.24.10
Search Parameters Search
parameters
for
this
resource.
The
common
parameters
also
apply.
See
A
code
system
included
or
excluded
in
the
value
set
or
an
imported
value
set
A code system included or excluded in the value set or an imported value set
ValueSet
url
identifier
contact
exclude
value[x]
<!-- from Resource: id, meta, implicitRules, and language --> <!-- from DomainResource: text, contained, extension, and modifierExtension --> <url value="[uri]"/><!-- 0..1 Globally unique logical identifier for value set --> <identifier><!-- 0..1 Identifier Additional identifier for the value set (e.g. HL7 v2 / CDA) --></identifier> <version value="[string]"/><!-- 0..1 Logical identifier for this version of the value set --> <name value="[string]"/><!-- 0..1 Informal name for this value set --> <status value="[code]"/><!-- 1..1 draft | active | retired --> <experimental value="[boolean]"/><!-- 0..1 If for testing purposes, not real usage --> <publisher value="[string]"/><!-- 0..1 Name of the publisher (organization or individual) --> <contact> <!-- 0..* Contact details of the publisher --> <name value="[string]"/><!-- 0..1 Name of an individual to contact --> <telecom><!-- 0..* ContactPoint Contact details for individual or publisher --></telecom> </contact> <date value="[dateTime]"/><!-- 0..1 Date for given status --> <lockedDate value="[date]"/><!-- 0..1 Fixed date for all referenced code systems and value sets --> <description value="[string]"/><!-- 0..1 Human language description of the value set --> <useContext><!-- 0..* CodeableConcept Content intends to support these contexts --></useContext> <immutable value="[boolean]"/><!-- 0..1 Indicates whether or not any change to the content logical definition may occur --> <requirements value="[string]"/><!-- 0..1 Why needed --> <copyright value="[string]"/><!-- 0..1 Use and/or publishing restrictions --> <extensible value="[boolean]"/><!-- 0..1 Whether this is intended to be used with an extensible binding -->
0..1 When value set includes codes from elsewhere --> <import value="[uri]"/><!--
