Foundation
FHIR
Infrastructure
Work
Group
| Maturity Level : Normative | Standards Status : Normative |
|
This
page
has
been
approved
as
part
of
an
ANSI
standard.
See
the
Infrastructure
Package
for
further
details.
|
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
four
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 |
|---|---|
|
|
This
|
For
all
content
marked
with
one
of
the
The |
|
| 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. |
|
|
This
|
| 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 .
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 new elements are introduced into normative resources in future versions - they will undergo a period of trial use as appropriate.
Note: it is also possible that some resources in the future will be labeled as 'trial use', but contain some elements labeled as 'normative'. There is no resource like this in this specification, though all Trial Use resources contain normative content from Resource and DomainResource , and the Data types .
This
release
(Release
3)
is
4)
has
a
mix
of
Normative
and
Trial
Use
Specification,
though
a
little
of
the
content,
and
also
includes
some
Draft
content
(where
marked
specifically
at
the
top
of
the
page)
is
Draft
.
For
Release
4,
some
content
is
Normative
.
page).
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 resource or profile (artifact) has been published on the current build. This level is synonymous with Draft |
| FMM 1 | PLUS the artifact produces no warnings during the build process and the responsible WG 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 | PLUS 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 FMG |
| FMM 3 |
PLUS
+
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 |
PLUS
the
artifact
has
been
tested
across
its
scope
(see
below),
published
in
a
formal
publication
(e.g.
Trial-Use
),
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 | the artifact has been published in two formal publication release cycles at FMM1+ (i.e. Trial-Use level) and has been implemented in at least 5 independent production systems in more than one country |
| Normative | the artifact is now considered stable |
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.
For
further
information,
and
discussion,
see
the
FHIR
Confluence
page
.
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: publication.major.minor.revision.
| publication |
|
| major |
|
| minor |
|
| revision |
|
Additional notes:
)
-
does
not
conform
to
this
version
policy,
in
that
the
version
is
not
updated
as
changes
are
made.
To
indicate
this,
the
revision
is
always
"cb"
e.g.
3.1.cb
immediately
after
the
publication
of
Release
3
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 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.
The following kinds of changes may be made to the specification:
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.
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.
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 data types 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 data type 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. |
| 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 |
|
| Data Types |
Except
as
described
in
the
preceding
paragraph,
Data
types
will
not
be
removed
or
changed
except
as
allowed
above
for
elements.
New
data
types
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
data
types
may
be
added
to
elements
which
are
already
expressed
as
a
choice
of
data
types
only
if
those
elements
are
optional
(minimum
cardinality
=
0).
|
| Value Constraints | The allowed list of Data types will not be added, removed or changed. Invariants, regular expressions, fixed values and patterns will not be added, removed or changed. |
| 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 data types 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 change |
| 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. |
NOTE: In rare circumstances, HL7 may approve changes that technically break one of the above rules in situations where there is a high level of confidence that the change will not impact existing implementers. Such deviations from these declared rules will involve broad notification, extensive community consultation and reviews by multiple levels of HL7 governance processes.
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 data types, 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:
This technique can be used with all versions of FHIR, including R2 and R3:
|
FHIR
DSTU2
|
1.0 |
|
FHIR
R3
(STU3,
or
just
R3)
|
3.0 |
|
FHIR
R4
(this
version)
|
4.0 |
Note that this extension framework only applies back to DSTU2. 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)
This table shows the mapping between primitive data types across versions:
| R4 | R3 | DSTU2 |
| base64Binary | base64Binary | base64Binary |
| boolean | boolean | boolean |
| canonical | (uri) | (uri) |
| code | code | code |
| date | date | date |
| dateTime | dateTime | dateTime |
| decimal | decimal | decimal |
| id | id | id |
| instant | instant | instant |
| integer | integer | integer |
| markdown | markdown | markdown |
| oid | oid | oid |
| positiveInt | positiveInt | positiveInt |
| string | string | string |
| time | time | time |
| unsignedInt | unsignedInt | unsignedInt |
| uri | uri | uri |
| url | (uri) | (uri) |
| uuid | uuid | (id) |
Formal Definitions for extensions:
| Format: | R2 Package | R3 Package | R4 Package |
| R2 Extensions: | n/a |
hl7.fhir.extensions.r2:3.0.1
|
|
| R3 Extensions: |
hl7.fhir.extensions.r3:1.0.2
|
n/a` |
|
| R4 Extensions: |
hl7.fhir.extensions.r4:1.0.2
|
hl7.fhir.extensions.r4:3.0.1
|
n/a |
Note for balloters: these packages will be created when R4 is finalized. Until then, these are broken links.
While
implementation
of
this
mixed
Normative
and
Trial
Use
release
is
occurring,
development
will
be
progressing
on
the
next
release.
This
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
the
STU
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
the
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.
The next major publication of FHIR will be Release 5. It is our hope release 5 will include more Normative content, including more of the core patient summary clinical content. Other content, including most if not all clinical knowledge/reasoning, care planning, and financial resources, are likely to remain at the Trial Use level as they are not expected to meet the criteria for Normative.
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.)
There will be additional releases of FHIR with a frequency of somewhere between 18 and 24 months for the foreseeable future. These releases will include maintenance on Normative content, new content (e.g. in the public health, financial or clinical research spaces), revisions to trial use content reflecting implementer feedback and increasing maturity on Trial Use artifacts and the migration of additional content to normative status. As well, HL7 will continue to focus to providing additional guidance through the publication of implementation guides and profiles where consensus can be found at the international level.
FHIR
®©
HL7.org
2011+.
FHIR
Release
4
(v4.0.0)
CI
Build
hl7.fhir.core#4.1.0
(GitHub
760b133f)
generated
on
Thu,
Dec
27,
2018.
QA
Page
Fri,
Oct
11,
2019
20:38+0000.
Links:
Search
|
Version
History
|
Table
of
Contents
|
Credits
QA
Page
|
Compare
to
R3
R4
|
|
Propose
a
change