Foundation
This
page
is
part
of
the
FHIR
Specification
(v5.0.0:
R5
-
STU
v6.0.0-ballot3:
Release
6
Ballot
(3rd
Draft)
(see
Ballot
Notes
).
This
is
the
The
current
published
version
in
it's
permanent
home
(it
will
always
be
available
at
this
URL).
is
5.0.0
.
For
a
full
list
of
available
versions,
see
the
Directory
of
published
versions
.
Page
versions:
R5
R4B
R4
R3
|
FHIR
Infrastructure
Work
Group
|
Maturity Level : Normative | Standards Status : Normative |
This page documents the way version change is handled in FHIR. FHIR is a standard, so the way version change is handled is a bit different from an application API. This page describes:
See also Managing FHIR Versions for additional implementer advice about dealing with versions.
FHIR is a standard. In order to be useful, standards need to evolve. At the same time, the evolution of standards needs to be predictable and manageable for the implementation community. This section describes how HL7 develops a standard so that implementers know what to expect as the standard evolves.
HL7 has five descriptive terms that describe the level of stability and implementation readiness associated with different aspects of the specification. They are as follows:
| Standard Level | Description |
|---|---|
| Normative |
This
content
was
approved
by
the
ANSI
standards
process
in
a
previous
version
(see
Normative
status
note
).
It
has
been
subject
to
review
and
production
implementation
in
a
wide
variety
of
environments.
The
content
is
considered
to
be
stable
and
has
been
'locked',
subjecting
it
to
FHIR
Inter-version
Compatibility
Rules
.
While
changes
are
possible,
they
are
expected
to
be
infrequent
and
are
tightly
constrained.
Note that this version of the specification has NOT been submitted to ANSI for consideration as a normative standard. |
| Trial Use |
This content has been well reviewed and is considered by the authors to be ready for use in production systems. It has been subjected to ballot and approved as an official standard. However, it has not yet seen widespread use in production across the full spectrum of environments it is intended to be used in. In some cases, there may be documented known issues that require implementation experience to determine appropriate resolutions for. Future versions of FHIR may make significant changes to Trial Use content that are not compatible with previously published content. |
| Draft |
This
portion
of
the
specification
is
not
considered
to
be
complete
enough
or
sufficiently
reviewed
to
be
safe
for
implementation.
It
may
have
known
issues
or
still
be
in
the
"in
development"
stage.
It
is
included
in
the
publication
as
a
place-holder,
to
solicit
feedback
from
the
implementation
community
and/or
to
give
implementers
some
insight
as
to
functionality
likely
to
be
included
in
future
versions
of
the
specification.
Content
at
this
level
should
only
be
implemented
by
the
brave
or
desperate
and
is
very
much
"use
at
your
own
risk".
The
content
that
is
Draft
that
will
usually
be
elevated
to
Trial
Use
once
review
and
correction
is
complete
after
it
has
been
subjected
to
ballot
Some resources with a standards status of 'draft' have an FMM level of 1 or 2 - this means that the committee responsible for them is ready for them to be tested and balloting, but that balloting has not yet occurred. Draft resources cannot have a FMM level greater than 2 |
| Informative | This portion of the specification is provided for implementer assistance and does not make rules that implementers are required to follow. Typical examples of this content in the FHIR specification are tables of contents, registries, examples, and implementer advice |
| Deprecated | This portion of the specification is outdated and may be withdrawn in a future version. Implementers who already support it should continue to do so for backward compatibility. Implementers should avoid adding new uses of this portion of the specification. The specification should include guidance on what implementers should use instead of the deprecated portion |
Some Normative artifacts contain a few parts labeled as 'Trial Use' even though the artifact itself is labeled 'Normative' :
While
HL7
prefers
to
avoid
this
outcome,
there
are
several
resources
where
the
overall
functionality
of
the
artifact
is
clearly
ready
to
be
labeled
as
'normative'
while
some
very
specific
parts
are
known
not
to
have
the
requisite
level
of
implementation
experience
as
the
rest
of
the
resource.
E.g.
Bundle.signature
Bundle.issues
.
Where
a
Normative
resource
contains
elements
marked
as
trial-use,
these
elements
are
clearly
marked
in
the
resource
definitions.
Implementers
should
be
aware
that
future
versions
of
the
FHIR
specification
may
change
these
parts
of
the
resources
(in
addition
to
the
other
changes
allowed
under
the
inter-version
compatibility
rules
.
).
While
HL7
will
carefully
consider
the
consequences
of
breaking
change
to
these
elements,
implementers
should
be
aware
that
reading/using
these
elements
has
the
potential
to
cause
breaking
change
to
their
applications
later.
Note
that
this
same
status
will
arise
as
a
matter
of
process
when
Notes:
The
content
of
this
release
has
been
subject
to
significant
review
through
ballot
and
other
HL7
processes
and
many
aspects
of
it
have
been
implemented
and
subjected
to
interoperability
testing
through
Connectathons
and
early
adoption.
However,
the
degree
of
testing
has
varied.
Some
resources
have
been
well
tested
in
a
variety
of
environments.
Others
have
received
relatively
little
real-world
exercise.
In
general,
the
infrastructure
should
be
considered
to
be
more
stable
than
the
resources
themselves.
In
some
cases,
there
are
issues
on
which
input
is
specifically
requested
during
the
Trial
Use
period
(see
the
Outstanding
Issue
List
,
and
known
issues
will
arise
after
publication
(refer
to
the
FHIR
Change
Request
tracker
for
details.)
Guidance
from
early
implementation
will
help
address
these
areas.
All
artifacts
in
this
specification
are
assigned
a
"Maturity
Level",
known
as
FMM
(after
the
well-known
CMM
grades).
The
FMM
level
can
be
used
by
implementers
to
judge
how
advanced
-
and
therefore
stable
-
an
artifact
is.
The
following
FMM
levels
are
defined:
| Draft (0) | the artifact has been published on the current build. Artifacts with this level must have a standards status of Draft . |
| FMM 1 | FMM0 + the artifact produces no warnings during the build process and the responsible work group has indicated that they consider the artifact substantially complete and ready for implementation. For resources, profiles and implementation guides, the FHIR Management Group has approved the underlying resource/profile/IG proposal. |
| FMM 2 | FMM1 + the artifact has been tested and successfully supports interoperability among at least three independently developed systems leveraging most of the scope (e.g. at least 80% of the core data elements) using semi-realistic data and scenarios based on at least one of the declared scopes of the artifact (e.g. at a connectathon). These interoperability results must have been reported to and accepted by the FHIR Management Group. |
| FMM 3 |
FMM2
+
the
artifact
has
been
verified
by
the
work
group
as
meeting
the
Conformance
Resource
Quality
Guidelines
;
has
been
subject
to
a
round
of
formal
balloting;
has
at
least
10
distinct
implementer
comments
recorded
in
the
tracker
drawn
from
at
least
3
organizations
resulting
in
at
least
one
substantive
change.
|
| FMM 4 |
FMM3
+
the
artifact
has
been
tested
across
its
scope
(see
below),
published
in
a
formal
publication
(e.g.
STU
),
and
implemented
in
multiple
prototype
projects.
As
well,
the
responsible
work
group
agrees
the
artifact
is
sufficiently
stable
to
require
implementer
consultation
for
subsequent
non-backward
compatible
changes.
|
| FMM 5 | FMM4 + the artifact has been published in two formal publication release cycles as STU and has been implemented in at least 5 independent production systems in more than one country. |
| FMM 6 ( N ) | FMM5 + the responsible work group and the FHIR management group agree the material is ready to lock down according to the inter-version change rules and the artifact has passed HL7 normative ballot. This is synonymous with Normative standard status. |
Tested across scope means:
has
signed
off
on
the
list
of
"example
contexts"
defined
for
the
artifact
The
Maturity
level
is
strongly
related
to
stability;
the
higher
the
maturity
level,
the
more
controls
are
enforced
to
restrict
breaking
changes
to
the
resource
resource.
The
table
above
represents
a
frozen
snapshot
of
the
maturity
levels
maintained
by
the
FHIR
Management
Group
on
the
FHIR
Confluence
page
.
Further
information
and
discussion
about
these
levels
can
be
found
there.
The
maturity
model
is
significantly
influenced
by
the
degree
and
type
of
implementation
activity
using
an
artifact.
For
this
reason,
we
encourage
implementers
to
register
their
implementations
.
A
detailed
analysis
of
the
basis
for
the
maturity
metrics
for
FHIR
artifacts
can
be
found
here
.
New versions of FHIR will be published on a release cycle of approximately 18-24 months. This frequency is based on the timelines necessary to consult with implementers, to develop and review new content, as well as to undertake the formal balloting and reconciliation processes required for ANSI-approved standards. This release cycle also ensures an opportunity to incorporate implementer feedback from earlier versions of the specification into subsequent versions. Limited-scope releases on a shorter timeline may occur occasionally where necessary to meet implementer needs.
Each
new
release
is
assigned
a
unique
version
number.
The
FHIR
version
policy
is
based
on
Semantic
versioning
,
but
with
some
differences
due
to
the
fact
that
FHIR
is
a
specification,
not
a
software
API.
There is a single development version of FHIR. This undergoes cycles of development as managed by HL7. Each major cycle of development is concluded by a formal ballot (or more than one), and then a new specification is published. In version control terms, each published specification is a branch off the development trunk, which may then itself undergo further change as HL7 maintains the published specification (though such changes are usually minimal, limited to necessary technical corrections or security alerts).
Each FHIR version is identified by a string composed from 4 parts: major.minor.patch-label.
| major |
|
| minor |
|
| patch |
|
| label |
|
Additional notes:
The FHIR version is usually known implicitly, but can be specified/determined by one of three methods:
For further information, see Managing Multiple FHIR Versions .
The following kinds of changes may be made to the specification:
The intent of these rules is to ensure that applications that are conformant to an existing specification are also conformant to subsequent versions. In practice, there are many subtle issues around inter-version change, and the exact rules are subject to further clarification based on feedback from implementers.
Content with a status of Draft or Trial Use can change - including Breaking Changes - from version to version, subject to the rules described by the Maturity Process . There are no rules for maintaining any sort of compatibility between versions for content with these statuses, though of course we will only make breaking changes based on feedback from the community.
Once an artifact achieves Normative status, specific rules come into play around inter-version compatibility. These rules have implication for both forward and backward compatibility and are intended to allow implementations to exercise FHIR interfaces and process the content of FHIR resources safely while exchanging data between systems using different versions of FHIR. These rules do not apply to non-normative content, including STU content within normative artifacts.
The
following
kinds
of
changes
In
rare
circumstances,
HL7
may
be
made
to
normative
portions
of
the
specification:
Breaking
changes
are
approve
changes
that
mean
that
previously
conformant
resource
instances
are
no
longer
conformant
to
the
updated
specification
Substantive
changes
are
changes
technically
break
content
with
a
status
of
Normative
where
there
is
a
high
level
of
confidence
that
introduce
new
functionality
-
changes
to
the
specification
that
create
new
capabilities
-
but
would
change
will
not
render
unchanged
impact
existing
applications
non-conformant
Non-substantive
changes
should
not
cause
changes
in
any
conformant
resource
instances.
For
example,
section
renumbering,
correcting
broken
links,
changing
styles,
fixing
typos,
and
providing
clarifications
that
do
not
change
the
meaning
of
implementers.
Such
deviations
from
the
specification.
In
addition,
this
covers
corrections
that
are
judged
not
to
create
any
expectation
declared
rules
will
involve
broad
notification,
extensive
community
consultation
and
reviews
by
multiple
levels
of
change
to
a
conformant
resource
instance.
HL7
governance
processes.
Yes, this this is the second dragon in as many paragraphs. Inter-version compatibility is complicated...
The assertion around non-breaking change does NOT mean that the types of changes permitted here cannot cause existing systems to fail, even if they make allowances for the types of changes permitted. (Though those that make allowances will hopefully fail more gracefully.) Because the requirements of healthcare continue to evolve, the rules defined here allow for new content to be introduced - new codes, new elements, etc. Depending on the design of a receiving system, such new content may cause failure. A system that relies on schema validation will fail because of a new element. A system that relies on a select statement iterating through 'status' codes might fail or behave unexpectedly due to incorrect fall-through when a new status code is introduced. Systems designers are strongly encouraged to consider the types of changes permitted here and consider how these types of changes will impact their ability to safely function when dealing with newer versions of FHIR.
NOTE: The examples provided as part of this specification are never substantive. While every effort is made to ensure that FHIR examples are correct, changes to the examples in the specification are not considered substantive.
Content
with
a
status
of
Draft
or
Trial
Use
can
change
-
including
Breaking
Changes
-
from
version
to
version,
subject
to
the
rules
described
by
the
Maturity
Process
.
There
are
no
rules
for
maintaining
any
sort
of
compatibility
between
versions
for
content
with
these
statuses,
though
of
we
will
only
make
breaking
changes
based
on
feedback
from
the
community.
Forward
compatibility
means
that
content
that
is
conformant
in
an
old
release
will
remain
conformant
with
future
versions.
Once
normative,
FHIR's
rules
try
to
enforce
forward
compatibility.
However,
that
doesn't
guarantee
that
all
old
systems
will
interoperate
with
future
systems.
Backward compatibility means that instances created against future versions of the specification will interoperate with older versions of the specification. This is not guaranteed by FHIR, though there are strategies systems can adhere to that will increase their chances of such interoperability. Specifically, when dealing with content from a system supporting an unknown normative version and wishing to maximize backwards compatibility, applications SHOULD:
However, in a healthcare context, many implementers are unwilling to consider some of these steps because of concerns about clinical risk or technical limitations in their software (e.g. schema-based processing).
.
| Category | Allowed changes |
|---|---|
| Resources | New artifacts resources may be introduced. Existing resources will not have their names changed |
| Artifacts (resources, profiles, code systems, etc.) | New artifacts including new resources and datatypes may be introduced. Existing artifacts will not have any computable identifiers (e.g. resource names) changed. Artifacts may be deprecated . |
| Elements | New optional elements and/or content (e.g. XML attributes, etc.) may be introduced at any location in resource and datatype structures provided they do not constitute "isModifier" elements. However, the names, path and meaning of previously existing data elements will not be changed. This means there will be no change to resource names and no changes to names assigned to slices and other elements within profiles. |
| Cardinality | Minimum element cardinalities will not be changed. Upper cardinality may change from 1 to * only in circumstances where all elements except for the first repetition can be safely ignored. Note that this may change the path to the element in some syntaxes (e.g. JSON). This may mean that an order is assigned to the repeating items or that there is no preference as to which element is retained. Systems should follow the rules above for unexpected elements. Because of the JSON issue, changes to cardinality for normative elements will be minimized whenever possible, e.g. by defining new sibling elements. |
| Descriptions | Descriptive information about a resource - short labels, definitions, usage notes, aliases, examples, rationale, mappings, etc. may be updated or revised to provide additional clarity or guidance, but not in such a manner as to invalidate a reasonable interpretation of the previously documented use of an element. (This does not preclude fixing obvious errors.) |
| Value Sets and Code Systems |
The definition of any value set that is marked as immutable will never change. The expansions for immutable value sets may still change if no "stable date" is declared and the value set does not restrict code system and/or value set references to specific versions and the codes in the referenced code system(s) or value set(s) change. For non-immutable value sets:
For both immutable and non-immutable value sets, additional designations may be declared. Normative CodeSystems whose content is generated from a mix of normative and non-normative contents may break these rules. For example, the code system containing the list of all resources may have codes removed or renamed as non-normative resources are removed or renamed. These expectations only apply to Value Sets and Code Systems maintained as part of the FHIR specification. HL7 cannot enforce these rules on terminology artifacts maintained by other authorities - e.g. UCUM unit codes, ISO language codes, etc. |
| Terminology Bindings |
|
| Datatypes |
Except
as
described
in
the
preceding
paragraph,
Datatypes
will
not
be
removed
or
changed
except
as
allowed
above
for
elements.
New
datatypes
may
be
introduced.
Types
declared
on
existing
elements
will
not
be
removed
or
changed,
except
for
the
special
case
that
string
may
be
changed
to
markdown
.
Additional
datatypes
may
be
added
to
elements
which
are
already
expressed
as
a
choice
of
datatypes
only
if
those
elements
are
optional
(minimum
cardinality
=
0).
|
| Value Constraints | The allowed list of Datatypes will not be added, removed or changed. Invariants, regular expressions, fixed values and patterns will not be added, removed or changed in a way that could invalidate previous instances. New warning or best practice invariants may be added. 'Error' invariants may be added that are tied to newly introduced elements or codes, or existing rules in the specification narrative. |
| Flags | The Is Modifier and Is Summary flags will not be changed. |
| Slicing | Slicing rules and aggregation characteristics will not be changed. |
| Search Criteria | Search criteria may be added but not removed or renamed. Existing criteria will not have their type or path changed or have their description altered in any way that would invalidate the reasonable behavior of existing systems (except for correcting obvious errors). |
| Operations | New operations may be defined but operations will not be removed or renamed. Existing parameters will not be removed or renamed, nor may their type or lower cardinality be changed. Upper cardinality may be changed from 1 to *. (Systems should ignore unexpected repetitions.) Additional optional parameters may be introduced. Changes to operations that would violate the preceding constraints will be handled by defining new operations and, potentially, deprecating the old operations. |
| Restful interface | Existing endpoints will not be renamed or removed, nor have their expected behavior changed in a manner that would cause reasonable systems designed against prior versions to be non-interoperable. Additional endpoints and interactions may be introduced. |
| Profiles and extension definitions | Profile structure, extension definitions and search criteria definitions will not be removed or have their URIs changed. New profile structures, extension definitions and search criteria definitions may be introduced. Profiles may have their statuses changed to "retired". Profiles referenced by data elements for structures or datatypes may be replaced with a reference to a distinct profile that is "compatible" with the previously referenced profile according to these forward and backward compatibility rules. |
| Capability Statements | Within the CapabilityStatements for defined FHIR Services or 'core' implementation guides, additional operations may be added. These additions might be optional (MAY/SHOULD) or mandatory (SHALL). Note that the introduction of mandatory operations would break forwards compatibility and will only occur with community consultation. |
| Implementation Guides |
Additional
artifacts
can
be
added,
and
artifacts
can
be
changed.
The
list
of
global
profiles
will
not
|
| References |
Where
one
conformance
resource
points
to
another
(e.g.
CapabilityStatement
to
profile,
profile
to
profiles,
profile
to
value
set,
etc.),
the
reference
may
change
to
point
to
a
newer
version
of
the
conformance
resource
or
to
a
distinct
conformance
resource
so
long
as
the
content
of
the
newly
referenced
resource
adheres
to
the
compatibility
rules
with
respect
to
the
previously
referenced
version.
|
| Conformance Language | SHALL statements cannot be broken (though they can be clarified) and new SHALL statements cannot be introduced unless they are conditional based on version. E.g. "Instances in version x and higher of FHIR SHALL..." Changes of SHOULD to MAY and vice versa as well as introducing new MAY and SHOULD statements are permitted. |
Once
content
is
normative,
there
is
a
process
for
removing
it
from
the
standard
by
marking
it
as
deprecated
or
withdrawn
(from
the
HTML
4.0
Standard
):
| Deprecated | Systems should continue to support the artifact/feature/concept, but are discouraged from making use of it |
| Withdrawn | Documented for historical purposes, no longer supported |
The
specification
will
provide
guidance
with
deprecated
materials
showing
how
to
avoid
using
them.
Deprecated
materials
are
eligible
to
be
balloted
to
be
withdrawn
two
years
after
their
deprecated
status
is
published.
The computable artifact labels (e.g. codes, element names, urls, etc.) associated with withdrawn materials SHALL not be used in future versions of HL7 specifications. Materials marked "deprecated" may have that marking removed as part of a subsequent ballot at a later moment, while withdrawn materials SHALL NOT.
The following artifacts are deprecated in this version of FHIR:
Additional
discussion
on
inter-versioning
issues
can
be
found
here:
https://confluence.hl7.org/display/FHIR/Interversion+Compatibility
.
Regardless of the degree of prior implementation, all aspects of the FHIR specification are potentially subject to change while an artifact has a status of Draft or Trial Use . These changes may be minor (clarifications of definitions, etc.) or major (refactoring of resources, changes to serialization rules, eliminating or adding datatypes, etc.) There is no commitment to backward or forward compatibility during the trial use process until content is normative. Changes will not be made without cause, however the interests of long-term implementability will generally trump the impact on early adopters when determining what changes should be made. This balance will shift more towards early adopters as maturity levels increase. I.e. Impact on existing implementations will be weighted more highly for an FMM-level 5 artifact than they would for an FMM-level 1 artifact.
Implementers who are willing to accept the risk of change (perhaps for the benefit of early implementation experience, first mover advantage and the ability to leverage FHIR's intrinsic benefits) are encouraged to implement those parts of FHIR that are early in the maturity cycle in real-world systems. However, those implementers should be aware that local adaptations may be necessary to meet real-world requirements. Furthermore, such implementers should architect their solutions to be tolerant of changes to the specification and, where necessary, to manage interoperability with systems that may be using different versions of the specification or different local adaptations.
During
the
Trial
Use
period,
requests
for
change
may
be
submitted
using
the
HL7
issue
tracker
which
can
be
found
here
.
Where
possible,
updates
to
the
"development"
version
of
the
specification
will
be
made
in
a
timely
fashion.
Implementers
should
be
aware
that
the
changes
are
not
considered
"official"
until
such
time
as
they
are
balloted
and
approved
as
part
of
a
subsequent
Trial
Use
or
Normative
publication.
Change
requests
might
be
fixes
to
allow
implementation,
clarifications
or
enhancements.
In
addition,
HL7
will
be
developing
and
introducing
additional
resources
and
profiles
as
part
of
the
FHIR
specification.
SDOs and regulatory bodies that are interested in making use of the FHIR specification should feel free to do so, but should consider and plan for the possibility that the specification will evolve and change prior to becoming Normative .
A
key
aspect
of
the
FHIR
specification
development
process
is
gaining
feedback
from
implementers
making
use
of
the
specification.
As
well,
the
process
is
conditional
on
real-world
implementation
in
order
to
move
through
the
maturity
cycle.
For
this
reason,
all
FHIR
implementers
are
encouraged
to
register
their
usage
here
,
which
captures
contact
and
other
information
that
will
allow
HL7
to
perform
appropriate
monitoring
of
FHIR
usage.
Survey
information
is
confidential
and
reported
in
aggregate
only.
Many implementations need to convert resources from one FHIR version to another. Once resources become normative (once sufficiently mature and stable), converting resources forwards from past versions is not needed. Converting back to older versions presents a challenge, however, in that the newer version may add additional elements that are not present in the older version. In some cases, the elements are simply irrelevant since the requirements they represent are not in scope for older applications, but in other cases, it is necessary to represent the data in order to cater for round-tripping.
A more complex problem arises with resources that are not yet stable (early in the maturity process). If applications have implemented less stable resources, not only do they have the problem of new elements for new requirements, the specification may change in either compatible or incompatible ways, and it may be necessary to carry data elements from past versions forward in order to allow seamless round-tripping.
In order to help implementers with this problem, any element defined in any version of FHIR is automatically assigned an extension URL that uniquely identifies the element and can be used in the relevant FHIR version. The extension URL for an element can automatically be derived:
http://hl7.org/fhir/[version]/StructureDefinition/extension-[Path]
where [version] is taken from this list:
|
FHIR
DSTU2
|
1.0 |
|
FHIR
R3
(STU3,
or
just
R3)
|
3.0 |
|
FHIR
R4
(mixed
STU/Normative)
|
4.0 |
|
FHIR
R4B
(only
STU
changes)
|
4.3 |
|
FHIR
R5
(this
version)
|
5.0 |
This table includes the formal milestone releases for DSTU2 and on, which are the only releases for which this process is defined. Older versions than that are not supported. Technical correction releases are not listed because they will never introduce or change elements. Ballot and interim releases are not supported for use in implementation environments
The [Path] is actually the ElementDefinition.id from the relevant StructureDefinition for the element. This leads to URLs like the following:
http://hl7.org/fhir/4.0/StructureDefinition/extension-Bundle.signature
|
R4
Signature
Element
on
Bundle
|
http://hl7.org/fhir/3.0/StructureDefinition/extension-Patient.animal.species
|
STU3
Species
Element
on
Patient
|
http://hl7.org/fhir/1.0/StructureDefinition/extension-ValueSet.extensible
|
DSTU2
ValueSet.extensible
|
Implementers should be aware of the following issues when using these extensions:
Bundle.entry.resource
,
DomainResource.contained
,
etc.)
http://hl7.org/fhir/5.0/StructureDefinition/extension-Observation.value
for
types
allowed
in
Observation.value
in
R5
that
were
not
allowed
in
an
earlier
http://hl7.org/fhir/5.0/StructureDefinition/extension-...
could
never
appear
in
an
R5
instance.
targetProfile
elements
that
refer
to
resources,
only
those
targetProfile
resources
that
have
URLs
that
exist
in
the
referencing
version
can
exist.
If
a
resource
has
been
renamed,
it
can't
be
used
in
the
prior
release
(note:
this
is
because
there's
no
computable
way
of
determining
what
names
would
be
allowed);
the
alternate-reference
and
alternate-canonical
extensions
may
be
used
in
this
context.
E.g.
if
converting
from
a
version
that
supports
3
target
types
when
the
target
version
only
supports
2
target
types,
any
repetition
that
referred
to
the
non-supported
type
would
be
represented
as
a
reference
or
canonical
instance
where
the
content
would
just
be
the
alternate
extension
(and
a
display,
since
something
must
be
provided).
This table shows the mapping between primitive datatypes across versions:
| R5 | R4 | R3 | DSTU2 |
| base64Binary | base64Binary | base64Binary | base64Binary |
| boolean | boolean | boolean | boolean |
| canonical | canonical | (uri) | (uri) |
| code | code | code | code |
| date | date | date | date |
| dateTime | dateTime | dateTime | dateTime |
| decimal | decimal | decimal | decimal |
| id | id | id | id |
| instant | instant | instant | instant |
| integer | integer | integer | integer |
| markdown | markdown | markdown | markdown |
| oid | oid | oid | oid |
| positiveInt | positiveInt | positiveInt | positiveInt |
| string | string | string | string |
| time | time | time | string |
| time | unsignedInt | unsignedInt | unsignedInt |
| uri | uri | uri | uri |
| url | url | (uri) | (uri) |
| uuid | uuid | uuid | (uri) |
| integer64 | string | string | string |
To Do
There are several different variations when it comes to representing a complex datatype that has no equivalent in an earlier version. This section illustrates those situations.
Example
of
A
complex
datatype
in
a
resource
This is how it appears in R6:
{
"resourceType" : "Immunization",
"status" : "completed",
"vaccineCode" : {
"text" : "something"
},
"patient" : {
"reference" : "Patient/something"
},
"administeredProduct" : {
"reference" : {
"reference" : "Medication/something"
}
},
"occurrenceDateTime" : "2024-01-01T01:01:01Z"
}
This is how the same data appears in R4 using a cross-version extension:
{
"resourceType" : "Immunization",
"status" : "completed",
"vaccineCode" : {
"text" : "something"
},
"patient" : {
"reference" : "Patient/something"
},
"extension" : [{
"url" : "http://hl7.org/fhir/5.0/StructureDefinition/extension-Immunization.administeredProduct",
"extension" : [{
"url" : "reference",
"valueReference" : {
"reference" : "Medication/something"
}
}]
}],
"occurrenceDateTime" : "2024-01-01T01:01:01Z"
}
Note that this is an R5 extension, since valueAttachment was introduced in R5.
A complex datatype in a resource for a choice element
This is how it appears in R6:
{
"resourceType" : "Parameters",
"parameter" : [{
"name" : "ref",
"valueCodeableReference" : {
"concept" : {
"text" : "Something"
}
}
}]
}
This is how the same data appears in R4 using a cross-version extension:
{
"resourceType" : "Parameters",
"parameter" : [{
"name" : "ref",
"extension" : [{
"url" : "http://hl7.org/fhir/5.0/StructureDefinition/extension-Parameters.parameter.value%5Bx%5D",
"extension" : [{
"url" : "_datatype",
"valueString" : "CodeableReference"
},{
"url" : "concept",
"valueCodeableConcept" : {
"text" : "Something"
}
}
}]
}]
}
A complex data type in an extension
Example
of
The
extension
ValueSet.expansion.contains.property.subProperty
http://hl7.org/fhir/StructureDefinition/immunization-procedure
added
is
defined
in
R5:
the
extensions
pack,
but
uses
the
R5
specific
data
type
CodeableReference
.
This
is
how
it
appears
in
R6:
{
"resourceType" : "Immunization",
"status" : "completed",
"vaccineCode" : {
"text" : "something"
},
"patient" : {
"reference" : "Patient/something"
},
"extension" : [{
"url" : "http://hl7.org/fhir/StructureDefinition/immunization-procedure",
"valueCodeableReference" : {
"concept" : {
"text" : "something"
},
"reference" : {
"display" : "something"
}
}
}],
"occurrenceDateTime" : "2024-01-01T01:01:01Z"
}
This is how the same extension appears in R4 using a cross-version representation of the CodeableReference:
{
"resourceType" : "Immunization",
"id" : "xver-immunization2-r4",
"status" : "completed",
"vaccineCode" : {
"text" : "something"
},
"patient" : {
"reference" : "Patient/something"
},
"extension" : [{
"url" : "http://hl7.org/fhir/StructureDefinition/immunization-procedure",
"extension" : [{
"url" : "_datatype",
"valueString" : "CodeableReference"
}, {
"url" : "concept",
"valueCodeableConcept" : {
"text" : "something"
}
}, {
"url" : "reference",
"valueReference" : {
"display" : "something"
}
}]
}],
"occurrenceDateTime" : "2024-01-01T01:01:01Z"
}
A complex data type in an sub-extension
This is how it appears in R6:
{
"resourceType" : "Patient",
"extension" : [{
"url" : "http://hl7.org/fhir/StructureDefinition/patient-sexParameterForClinicalUse",
"extension" : [{
"url" : "value",
"valueCodeableConcept" : {
"coding" : [{
"system" : "http://terminology.hl7.org/CodeSystem/sex-parameter-for-clinical-use",
"code" : "specified"
}]
}
},{
"url" : "supportingInfo",
"valueCodeableReference" : {
"concept" : {
"text" : "Per Registration Questions"
},
"reference" : {
"display" : "DocumentReference/Something"
}
}
}]
}]
}
This is how the same data appears in R4 using a cross-version extension:
{
"resourceType" : "Patient",
"extension" : [{
"url" : "http://hl7.org/fhir/StructureDefinition/individual-genderIdentity",
"extension" : [{
"url" : "supportingInfo",
"extension" : [{
"url" : "_datatype",
"valueString" : "valueCodeableReference"
},{
"url" : "concept",
"valueReference" : {
"text" : "Per Registration Questions"
}
},{
"url" : "reference",
"valueReference" : {
"display" : "DocumentReference/Something"
}
}]
}]
}]
}
}
In
R4,
The
situation
with
required
elements
is
more
complicated.
This
is
when
the
data
that
is
being
represented
using
a
cross-version
extension
is
data
for
an
element
that
is
mandatory
in
the
earlier
version.
The
intent
of
the
mandatory
element
is
that
proper
data
must
be
provided,
but
the
desire
is
to
provide
a
different
form
of
data
using
a
cross-version
extension.
Implementers
should
note
that
wherever
possible,
the
correct
data
should
be
provided.
But
in
the
case
that
this
would
look
like:
is
not
possible,
this
example
shows
how
the
cross-version
extension
should
be
used.
Here is the data in R6 format, a CodeableReference in a Task input parameter:
{
"resourceType" : "Task",
"status" : "draft",
"input" : [{
"type" : { "text" : "code-me-please" },
"valueCodeableReference" : {
"concept" : {
"text" : "Something"
}
}
}]
}
The
representation
of
the
cross-version
extension
is
the
same
in
R4,
but
there
must
also
be
an
actual
Task.input.value
that
is
valid
in
R4.
This
is
done
using
the
Data
Absent
Reason
extension:
{
"resourceType" : "Task",
"id" : "xver-task-r5",
"status" : "draft",
"input" : [{
"type" : { "text" : "code-me-please" },
"_valueBoolean" : {
"extension" : [{
"url" : "http://hl7.org/fhir/5.0/StructureDefinition/extension-ValueSet.expansion.contains.property.subProperty",
"extension" : [{
"url" :"code",
"valueCode" : "sub-prop-code"
},{
"url" : "value",
"valueCode" : "sub-prop-value"
}]
"url" : "http://hl7.org/fhir/StructureDefinition/data-absent-reason",
"valueCode" : "unsupported"
}]
},
"extension" : [{
"url" : "http://hl7.org/fhir/5.0/StructureDefinition/extension-Task.input.value%5Bx%5D",
"extension" : [{
"url" : "_datatype",
"valueString" : "CodeableReference"
}, {
"url" : "concept",
"valueCodeableConcept": {
"text" : "Something"
}
}]
}]
}]
}
}
Implementer Notes:
code
of
unsupported
can
observe
the
presence
of
a
cross-version
extension
to
understand
that
the
system
that
authored
the
resource
had
the
data
available
but
not
a
supported
way
to
represent
in
the
earlier
(or
later)
version.
| Format: | R2 Package | R3 Package | R4 Package | |
| R2 Extensions: | n/a |
hl7.fhir.extensions.r2:3.0.1
|
hl7.fhir.extensions.r2:4.0.1
|
hl7.fhir.extensions.r2:5.0.0
|
| R3 Extensions: |
hl7.fhir.extensions.r3:1.0.2
|
n/a |
hl7.fhir.extensions.r3:4.0.1
|
hl7.fhir.extensions.r3:5.0.0
|
| R4 Extensions: |
hl7.fhir.extensions.r4:1.0.2
|
hl7.fhir.extensions.r4:3.0.1
|
n/a |
hl7.fhir.extensions.r4:5.0.0
|
| R5 Extensions: |
hl7.fhir.extensions.r4:1.0.2
|
hl7.fhir.extensions.r4:3.0.1
|
hl7.fhir.extensions.r4:4.0.1
|
n/a |
Note for balloters: the R5 packages will be created when R5 is finalized. Until then, these are broken links.
This specification is the result of three years of work by HL7, it's standards, government and implementation partners, along with the wider (huge) FHIR implementation community. The FHIR implementation community is now massive, and the pace of publication has slowed (as is evident in the publication history ).
Accordingly, the pace of implementation adoption of new versions is slowing, and it is unclear how quickly R5 will be adopted. HL7 will watch the market and survey it's many partners before deciding how quickly to pursue the next release, and whether the next release will be a restricted branch development from R5 (as R4B was to R4), or whether it will forge ahead with a full new version, which will be Release 6.
Note that for this release, the extensions have been moved out into a separate module and updated versions will be published regularly. See the Extension Version Policy for further information.
Irrespective
of
the
choice
around
publication
speed
and
whether
to
publish
partial
new
branch
versions,
HL7's
general
intent
for
the
Release
6
is
to
move
most
of
the
resources
in
the
Foundation,
Base
and
Clinical
layers
(see
the
'Category'
tab
in
the
Resources
pages
)
to
full
Normative
status,
along
with
a
fwe
few
other
resources
including
e.g.
Questionnaire.
Whatever
HL7
decides
to
do
with
regard
to
the
formal
status
of
the
resources,
the
next
release
will
include
additional
clarifications,
resources,
profiles
and
quality
enhancements
over
the
current
release
based
on
implementation
experience
and
ongoing
development
work.
It
will
also
incorporate
fixes
for
issues
raised
with
the
FHIR
issue
tracker
.
It
may
be
useful
for
implementers
of
this
release
to
review
the
candidate
current
release
(at
http://build.fhir.org
)
to
get
a
sense
of
what
changes
are
likely
coming
and
perhaps
to
find
more
robust
definitions
and
guidance
than
are
available
in
this
release.
Some implementers who are dependent on content that exists in a draft release may choose to implement based on a particular snapshot of the development release, though in doing so, they will limit their potential communication partners. In addition, implementers should be aware that most of the implementation tooling including those provided by HL7 will not support interim versions other than the latest release.
More
information
on
plans
for
Release
5
can
be
found
on
the
HL7
product
director's
blog
.
(Subscribing
to
this
blog
is
a
good
way
to
keep
current
on
significant
events
in
FHIR
development,
including
ballot
and
publication
timelines.)
timelines).
FHIR
®©
HL7.org
2011+.
FHIR
R5
hl7.fhir.core#5.0.0
R6
hl7.fhir.core#6.0.0-ballot3
generated
on
Sun,
Mar
26,
2023
15:26+1100.
Tue,
Apr
1,
2025
12:27+1100.
Links:
Search
|
Version
History
|
Contents
|
Glossary
|
QA
|
Compare
to
R4
|
Compare
to
R4B
R5
|
|
Propose
a
change