This page is part of the FHIR Specification (v1.4.0:
STU
3 Ballot 3). The current version which supercedes this version is
5.0.0
.
For
a
full
list
of
available
versions,
see
the
Directory
of
published
versions
. For a full list of available versions, see the
Directory of published versions 
.
Page
versions:
. Page versions:
R5
R4B
R4
R3
R2
|
|
|
|
Many elements in the FHIR resources have a coded value : some fixed string (a sequence of characters) assigned elsewhere that identifies some defined "concept". The sequence of characters and its meaning may be defined in one of several places:
All of these kinds of ways of defining codes are collectively called "code systems". This list is far from complete; there are many ways to define code systems, and they vary widely in sophistication and size.
Throughout this specification, coded values are always treated as a pair composed of "system" and "code", where the system is a URL that identifies the code system that defines the codes. Note that
system
values are always case sensitive. Different code systems make their own rules as to whether the codes they define are case sensitive or not. Note that all the codes defined by FHIR itself are case sensitive and SHALL be used in the provided case (usually, but not always, lowercase). values
are
always
case
sensitive.
Different
code
systems
make
their
own
rules
as
to
whether
the
codes
they
define
are
case
sensitive
or
not.
Note
that
all
the
codes
defined
by
FHIR
itself
are
case
sensitive
and
SHALL
be
used
in
the
provided
case
(usually,
but
not
always,
lowercase).
The
FHIR
framework
for
using
coded
values
is
based
on
the
fundamental
framework
defined
in
section
5
of
the
HL7
v3
Core
Principles
The FHIR framework for using coded values is based on the fundamental framework defined in section 5 of the
HL7 v3 Core Principles
document,
including
the
separation
between
code
systems
and
value
sets.
When
codes
are
carried
in
resources,
one
of
4
different
data
types
is
used:
document, including the separation between code systems and value sets.
When codes are carried in resources, one of 4 different data types is used:
| code |
|
| Coding |
|
| CodeableConcept |
|
| Quantity |
|
Note: generally the choice of data type is dictated by the resource itself. When choosing a data type for an
extension
,
see
the
FHIR
wiki
for
advice
about
data
type
choice
, see the FHIR wiki for
advice about data type choice
.
.
The set of coded values that is allowed to be used in an element of one of these 4 data types is known as a "value set" . Anywhere these data types are used, the specification "binds" a value set to the element.
The difference between a code system and a value set is an important distinction that is easily missed by implementers, since the difference is often overlooked in system design. For instance, it's not unusual to see an application table that is a mixed list of codes, containing some LOINC codes and also some additional in-house codes. Quite often, there is no explicit differentiation between them; only the fact that a code happens to look like a LOINC code betrays its origin.
For data exchange, on the other hand, explicitly tracking the source of the code is both important and necessary. In order to do this, each code system that defines codes is assigned a URL that identifies it, and all the codes it defines are actually a pair ("Code Pair": a name with a namespace). So in the case of this mixed list example from the previous paragraph, there are two code systems:
LOINC
(http://loinc.org)
and
a
local
one
(let's
say
it
has
been
given
the
URL:
http://example.com/codesystems/additional-test-codes).
The
application
table
is
a
single
value
set
(a
set
of
Code
Pairs)
that
includes
codes
from
each
of
those
two
namespaces.
The
value
set
itself
is
given
its
own
URL
as
an
identifier
(e.g.
"http://example.com/fhir/ValueSet/test-codes)")
-
this
identifies
the
set
of
Code
Pairs,
but
is
never
used
as
the
namespace
in
a
actual
code
pair,
or
in
an
instance.
In
FHIR,
Code
Pairs
are
always
represented
as
"code"
and
"system",
except
for
the
simple
data
type
"code"
data
type
where
the
namespace
(e.g.
the
system
element/property)
is
fixed
in
the
schema
and
not
represented
explicitly.
(http://loinc.org) and a local one (let's say it has been given the URL: http://example.com/codesystems/additional-test-codes). The application table is a single value set (a set of Code Pairs) that includes codes from each of those two namespaces. The value set itself is given its own URL as an identifier (e.g. "http://example.com/fhir/ValueSet/test-codes)") - this identifies the set of Code Pairs, but is never used as the namespace in a actual code pair, or in an instance. In FHIR, Code Pairs are always represented as "code" and "system", except for the simple
data type "code"
data type where the namespace (e.g. the system element/property) is fixed in the schema and not represented explicitly.
The URL in a
system
is always a reference to a code system, not to a value set. The URI
or
OID
defined
as
the
correct
value
to
use
in
FHIR
by
the
publisher
of
the
code
system
ensures that codes can be unambiguously traced back to their original definition, and that logical comparisons, matching and inferences can be performed consistently by different systems. For this reason, choice of the correct URI for the system attribute is critical. the
FHIR
community
code
The correct value to use in the
system
registry
for a given code system can be determined by working through the following list, in order:
If a code system is not resolved by this list, and there is no publisher to consult, implementers will have to choose a URI to use. The priority should be to choose a unique value that won't accidently be used by another implementer for a different purpose - or a very similar purpose with a different scope.
For publishers of code systems, the following considerations should be kept in mind when defining the correct URI to use:
Note: if the code system is made available packaged inside a
ValueSet
resource,
the
correct
URL
for
the
resource, the correct URL for the
system
value is
ValueSet.codeSystem.system
value
is
,
not
, not
ValueSet.uri
.
.
When an element is bound to a value set, the binding has these properties:
In the FHIR declarative datatypes, a binding is always represented using an
ElementDefinition.binding
.
.
There are a number of places in the specification where value sets are referenced in order to bind a coded value to a value set:
| ElementDefinition .binding.valueSet[x] |
|
|
ConceptMap
|
|
| Questionnaire .group.question.options |
|
| ValueSet .compose.import |
|
|
|
|
There are two types of value set references in this list, direct and logical.
A direct value set reference has the type
Reference
,
and
refers
directly
to
a
ValueSet
based
on
a
URL,
usually
to
a
terminology
server
running
a
FHIR
RESTful
API
.
When
accessing
a
value
set
based
on
this
kind
of
reference,
a
system
should
access
the
URL
directly
(after
converting
a
relative
reference
to
an
absolute
reference
according
to
the
local
context).
If
this
process
fails,
the
system
is
unable
to
resolve
the
value
set
and
must
handle
the
error
appropriately.
Example:
, and refers directly to a ValueSet based on a URL, usually to a terminology server running a
FHIR RESTful API
. When accessing a value set based on this kind of reference, a system should access the URL directly (after converting a relative reference to an absolute reference according to the local context). If this process fails, the system is unable to resolve the value set and must handle the error appropriately.
Example:
GET fhir/Questionnaire/234
<Questionnaire>
...
<question>
<options>
<reference value="ValueSet/234234"/>
</options>
</question>
....
</Questionnaire>
This
specifies
that
the
values
for
a
particular
questionnaire
come
from
the
ValueSet
with
id
234234
on
the
same
FHIR
end-point.
To
resolve
this,
the
system
would
GET
fhir/ValueSet/234234
Typically,
a
direct
reference
like
this
is
good
for
in-process
references,
in
closed
or
carefully
managed
eco-systems.
In
a
more
general
context,
these
references
tend
to
be
fragile
over
time
because
web
URLs
-
including
RESTful
API
URLS
-
are
easily
reassigned.
For
this
reason,
systems
are
encouraged
to
use
logical
value
set
references.
This specifies that the values for a particular questionnaire come from the ValueSet with id 234234 on the same FHIR end-point. To resolve this, the system would GET fhir/ValueSet/234234
Typically, a direct reference like this is good for in-process references, in closed or carefully managed eco-systems. In a more general context, these references tend to be fragile over time because web URLs - including RESTful API URLS - are easily reassigned. For this reason, systems are encouraged to use logical value set references.
A logical value set reference has the type
uri
,
where
an
absolute
URI
is
provided
that
matches
the
one
in
ValueSet.url.
The
value
set
URL
can
-
and
is
preferred
to
be
-
a
web
address
that
actually
resolves
directly
to
a
fixed
web
address
that
serves
as
the
authoritative
source
for
that
value
set.
Alternatively,
the
system
can
query
its
terminology
server(s)
to
resolve
a
value
set
with
that
URL
as
its
identity.
Example:
, where an absolute URI is provided that matches the one in ValueSet.url. The value set URL can - and is preferred to be - a web address that actually resolves directly to a fixed web address that serves as the authoritative source for that value set. Alternatively, the system can query its terminology server(s) to resolve a value set with that URL as its identity.
Example:
<StructureDefinition>
...
<element>
...
<binding>
...
<valueSetUri value="http://hl7.org/fhir/ValueSet/clinical-findings"/>
</binding>
...
</element>
....
</StructureDefinition>
This
specifies
that
the
element
is
bound
to
the
value
set
with
a
Value.url
of
http://hl7.org/fhir/ValueSet/clinical-findings
This specifies that the element is bound to the value set with a Value.url of
http://hl7.org/fhir/ValueSet/clinical-findings
.
One
way
to
accees
this
value
set
is
to
try
GET
http://hl7.org/fhir/ValueSet/clinical-findings
-
which
works,
for
this
value
set
-
http://hl7.org/fhir/ValueSet/clinical-findings
returns
the
authoritative
value
set
for
this
URL.
Alternatively,
the
value
set
could
be
resolved
using
a
local
terminology
server.
If
that's
running
a
FHIR
Terminology
Server
,
then
this
would
work
like
this:
. One way to accees this value set is to try GET http://hl7.org/fhir/ValueSet/clinical-findings - which works, for this value set - http://hl7.org/fhir/ValueSet/clinical-findings returns the authoritative value set for this URL.
Alternatively, the value set could be resolved using a local terminology server. If that's running a FHIR Terminology Server , then this would work like this:
GET fhir/ValueSet?url=http://hl7.org/fhir/ValueSet/clinical-findingsif the terminology server knows the value set, then it will return the value set. If the URL doesn't resolve to an authoritative value set, and the terminology server(s) don't know the value set, the system is unable to resolve the value set and must handle the error appropriately. The value set URL is allowed to be a URI such as a UUID (e.g. urn:uuid:c0e0d027-1250-4278-8f44-33a49dc67916). These value sets can never be accessed directly, and must come from a terminology server. Note that this specification defines many value sets that have a logical URL that is not resolvable (examples for SNOMED CT ,
if the terminology server knows the value set, then it will return the value set. If the URL doesn't resolve to an authoritative value set, and the terminology server(s) don't know the value set, the system is unable to resolve the value set and must handle the error appropriately.
The value set URL is allowed to be a URI such as a UUID (e.g. urn:uuid:c0e0d027-1250-4278-8f44-33a49dc67916). These value sets can never be accessed directly, and must come from a terminology server. Note that this specification defines many value sets that have a logical URL that is not resolvable (examples for
SNOMED CT
,
RxNorm
,
,
LOINC
)
Using
a
logical
reference
which
is
a
direct
reference
to
the
authoritative
value
set
is
the
easiest
and
most
reliable
approach.
However
this
requires
suitable
hosting
arrangements,
and
cannot
always
be
guaranteed,
so
it
is
not
required.
)
Using a logical reference which is a direct reference to the authoritative value set is the easiest and most reliable approach. However this requires suitable hosting arrangements, and cannot always be guaranteed, so it is not required.
Version
specific
Logical
References
Version specific Logical References
A
value
set
has
a
two
part
identifier:
a
url,
and
a
version.
Some
value
sets
only
ever
have
a
single
'version';
a
revision
of
the
value
set
contents
will
cause
a
new
url
to
be
assigned.
Others,
however,
maintain
the
same
URL,
and
change
the
version.
A
terminology
server
may
have
multiple
value
sets
for
the
same
ValueSet.url
with
different
versions.
To
be
precise
about
which
version
of
a
value
set
is
being
referred
to
in
a
value
set
reference,
append
the
version
to
the
logical
url
like
this:
A value set has a two part identifier: a url, and a version. Some value sets only ever have a single 'version'; a revision of the value set contents will cause a new url to be assigned. Others, however, maintain the same URL, and change the version. A terminology server may have multiple value sets for the same ValueSet.url with different versions.
To be precise about which version of a value set is being referred to in a value set reference, append the version to the logical url like this:
<valueSetUri value="http://hl7.org/fhir/ValueSet/clinical-findings?version=0.8"/>This is a version specific reference to a value set. Searching for this on a terminology server would look like this:
This is a version specific reference to a value set. Searching for this on a terminology server would look like this:
GET fhir/ValueSet?url=http://hl7.org/fhir/ValueSet/clinical-findings&version=0.8Note that if a value set reference does not have a version, and the server finds multiple versions for the value set, the system using the value set should pick the latest version of the value set and use that.
Note that if a value set reference does not have a version, and the server finds multiple versions for the value set, the system using the value set should pick the latest version of the value set and use that.
Note that as a matter of ongoing development, a few elements that have coded data types are not bound to any value set at all. Bindings are to be provided for these elements.
Almost all of the elements that have a coded data type are bound to a value set. The bindings are associated with various degrees of flexibility as to how closely the value set should be followed:
| required |
|
| extensible |
|
| preferred |
|
| example |
|
Irrespective of the binding strength, when a
StructureDefinition
is
used
to
describe
local
usage,
it
can
bind
the
element
to
a
different
value
set
in
order
to
be
much
more
precise
about
exactly
which
coded
values
can
be
used
for
these
elements,
and/or
increase
the
strength
of
the
binding.
There
are
different
rules
for
this,
depending
on
the
binding
strength,
as
discussed
below.
Generally
it
is
expected
that
jurisdictions,
projects
and
vendors
will
work
together
to
choose
actual
working
value
sets.
is used to describe local usage, it can bind the element to a different value set in order to be much more precise about exactly which coded values can be used for these elements, and/or increase the strength of the binding. There are different rules for this, depending on the binding strength, as discussed below. Generally it is expected that jurisdictions, projects and vendors will work together to choose actual working value sets.
To be conformant, instances of this element SHALL include a code from the specified value set. .
In the standard, this is generally used for elements where the value needs to be strictly controlled so that everyone can interpret it with confidence. Generally, this is used for elements with type
code
:
the
element
is
bound
to
a
value
set
that
contains
a
list
of
distinct
codes
with
a
specified
system
(and
version,
where
required)
the
element
is
bound
to
some
external
standard
that
defines
the
set
of
valid
codes
that
can
be
used
(typical
examples
of
references
are
Mime
Types
:
The other place where this is used is when
profiling resources
, and there is agreement within a particular context of use that a particular set of codes are the only ones that can be used. In these cases, the data type SHALL contain one of the values in the value set. If the data type is
CodeableConcept
,
then
one
of
the
, then one of the
coding
values
SHALL
be
from
the
specified
value
set.
values SHALL be from the specified value set.
Text
can
be
provided
as
well,
and
is
always
recommended,
but
is
not
an
acceptable
substitute
for
the
required
code.
Note
the
following
additional
rules
about
required
bindings
when
used
with
the
can be provided as well, and is always recommended, but is not an acceptable substitute for the required code.
Note the following additional rules about required bindings when used with the
code
data
type:
Where
the
value
set
is
defined
by
FHIR,
the
list
of
allowed
codes
will
be
fixed
in
the
XML
schema
Comparison
between
codes
is
always
case
sensitive
for
codes
unless
the
codes
are
selected
by
reference
(e.g.
ValueSet.compose),
and
the
referenced
specification
clearly
states
otherwise
The
list
of
codes
that
can
be
used
can
only
be
extended
in
subsequent
releases
of
the
FHIR
specification
When
an
element
is
bound
to
a
required
value
set,
derived
profiles
may
state
rules
on
which
codes
can
be
used,
but
cannot
select
new
or
additional
codes
for
these
elements.
data type:
When an element is bound to a required value set, derived profiles may state rules on which codes can be used, but cannot select new or additional codes for these elements.
To be conformant, instances of this element SHALL include a code from the specified value set if any of the codes within the value set can apply to the concept being communicated. If the value set does not cover the concept (based on human review), an alternate system.code may be used instead.
If the data type is
CodeableConcept
,
then
one
of
the
, then one of the
coding
values
SHALL
be
from
the
specified
value
set
if
a
code
applies,
but
if
no
suitable
code
exists
in
the
value
set,
alternate
code(s)
may
be
provided
in
its
place.
If
no
codes,
including
local
codes,
are
available,
then
just
text
may
be
used.
If
the
data
type
is
values SHALL be from the specified value set if a code applies, but if no suitable code exists in the value set, alternate code(s) may be provided in its place. If no codes, including local codes, are available, then just text may be used.
If the data type is
Coding
,
then
the
code/system
SHALL
be
from
the
specified
value
set
if
a
code
applies,
but
if
no
suitable
code
exists
in
the
value
set,
an
alternate
code
may
provided
in
its
place.
Identified
gaps
in
value
sets
should
be
submitted
to
the
organization
administering
the
value
set
in
order
to
improve
interoperability
in
the
future.
Extensible
bindings
are
used
when
there
is
consensus
at
the
specification
or
profiling
level
about
the
coded
values
that
should
be
used,
but
it
is
impossible
to
create
a
bounded
list
of
codes
that
a
known
to
cover
all
use
cases,
including
one
that
are
yet
to
arise.
When
an
element
is
extensibly
bound
to
value
set,
derived
profiles
may
state
rules
on
which
codes
can
be
used,
but
cannot
select
new
or
additional
codes
for
these
elements
unless
no
codes
with
appropriate
meanings
are
found
in
the
base
value
set.
, then the code/system SHALL be from the specified value set if a code applies, but if no suitable code exists in the value set, an alternate code may provided in its place.
Identified gaps in value sets should be submitted to the organization administering the value set in order to improve interoperability in the future.
Extensible bindings are used when there is consensus at the specification or profiling level about the coded values that should be used, but it is impossible to create a bounded list of codes that a known to cover all use cases, including one that are yet to arise.
When an element is extensibly bound to value set, derived profiles may state rules on which codes can be used, but cannot select new or additional codes for these elements unless no codes with appropriate meanings are found in the base value set.
Instances are encouraged to draw from the specified codes for interoperability purposes but are not required to do so to be considered conformant.
If the data type is
CodeableConcept
,
then
one
of
the
, then one of the
coding
values
SHOULD
be
from
the
specified
value
set,
but
another
code
and/or
text
can
be
used
in
its
place.
Preferred
bindings
are
used
when
there
is
consensus
at
the
specification
level
about
the
coded
values
that
are
the
best
to
be
used,
but
there
is
recognition
that
some
implementation
contexts
are
unable
to
use
the
recommended
codes
for
a
variety
of
reasons.
Applications
should
consider
adopting
the
preferred
value
set
where
ever
possible,
as
these
preferred
value
sets
are
the
most
likely
to
server
interoperability
purposes
in
the
future.
When
an
element
is
bound
to
a
preferred
value
set,
derived
profiles
may
bind
the
element
to
any
value
set
they
choose.
values SHOULD be from the specified value set, but another code and/or text can be used in its place.
Preferred bindings are used when there is consensus at the specification level about the coded values that are the best to be used, but there is recognition that some implementation contexts are unable to use the recommended codes for a variety of reasons. Applications should consider adopting the preferred value set where ever possible, as these preferred value sets are the most likely to server interoperability purposes in the future.
When an element is bound to a preferred value set, derived profiles may bind the element to any value set they choose.
Instances are not expected or even encouraged to draw from the specified value set. The value set merely provides examples of the types of concepts intended to be included.
Example bindings are used when an element has a very broad meaning (such as
List
.code),
or
there
is
no
consensus
over
the
correct
codes
to
be
used.
For
these
bindings:
.code), or there is no consensus over the correct codes to be used. For these bindings:
Some other coded value MAY be used, or (for a CodeableConcept), a text alternative MAY be provided. Example value sets are provided to assist implementers to understand the correct use of an element. Value sets based on code systems such as SNOMED CT that have restrictive license terms will only be used as example bindings in the base FHIR specification, though implementation guides for particular jurisdictions may adopt value sets that require licenses.
When an element is bound to an example value set, derived profiles may bind the element to any value set they choose.
In a few special cases, humans customarily use codes directly for elements that have type "string". A typical case is codes for states, and there are several places where a URI must come from a set of controlled values. An element of type
string
or
or
uri
can
also
be
bound
to
a
value
set.
When
a
string
or
URI
is
bound
to
a
value
set,
the
value
property
SHALL
contain
the
code
specified
by
the
value
set,
and
the
system
and
display
values
are
ignored.
©
HL7.org
2011+.
FHIR
DSTU2
(v1.0.2-7202)
generated
on
Sat,
Oct
24,
2015
07:44+1100.
Links:
Search
can also be bound to a value set. When a string or URI is bound to a value set, the value property SHALL contain the code specified by the value set, and the system and display values are ignored.
© HL7.org 2011+. FHIR STU3 Candidate (v1.4.0-8139) generated on Thu, Mar 31, 2016 08:10+1100.
QA Page
Links:
Search
|
Version
History
|
Table
of
Contents
|
Compare
to
DSTU1
|
Version History
|
Table of Contents
|
Compare to DSTU2
|
|
|
Propose
a
change
|
Propose a change