DSTU2
This
page
is
part
of
the
FHIR
Specification
(v0.0.82:
(v1.0.2:
DSTU
1).
2).
The
current
version
which
supercedes
this
version
is
5.0.0
.
For
a
full
list
of
available
versions,
see
the
Directory
of
published
versions
.
Page
versions:
R5
R4B
R4
R3
R2
|
FHIR
Infrastructure
| Maturity Level : 3 | Ballot Status : DSTU 2 |
This
exchange
specification
is
based
on
generally
agreed
common
requirements
across
healthcare
-
covering
many
jurisdictions,
domains,
and
different
functional
approaches.
As
such,
it
It
is
common
for
specific
implementations
to
have
valid
requirements
that
will
are
not
be
directly
included
in
this
specification.
part
of
these
agreed
common
requirements.
Incorporating
all
of
these
requirements
would
make
this
specification
very
cumbersome
and
difficult
to
implement.
Instead,
this
specification
expects
that
these
additional
distinct
requirements
will
be
implemented
as
extensions.
As such, extensibility is a fundamental part of the design of this specification. Every element in a resource may have extension child elements to represent additional information that is not part of the basic definition of the resource. Applications should not reject resources merely because they contain extensions, though they may need to reject resources because of the specific contents of the extensions.
Note that, unlike in many other specifications, there can be no stigma associated with the use of extensions by any application, project, or standard - regardless of the institution or jurisdiction that uses or defines the extensions. The use of extensions is what allows the FHIR specification to retain a core simplicity for everyone.
In order to make the use of extensions safe and manageable, there is a strict governance applied to the definition and use of extensions. Though any implementer is allowed to define and use extensions, there is a set of requirements that must be met as part of their use and definition.
Every
element
in
a
resource
or
data
type
includes
an
optional
"extension"
child
element
that
may
be
present
any
number
of
times.
The
extension
elements
appear
as
the
first
set
of
children,
prior
to
any
other
defined
child
elements.
This
is
the
content
model
of
the
extension
as
it
appears
in
each
resource:
UML Diagram
XML Template
<extension|modifierExtension xmlns="http://hl7.org/fhir" url="identifies the meaning of the extension (uri)"><!-- from Element: extension -->
<</value[x]> </[name]><value[x]><!-- 0..1 * Value of extension --></value[x]> </extension|modifierExtension>
JSON Template
{
// from Element: extension
"url" : "<uri>", // R! identifies the meaning of the extension
// value[x]: Value of extension. One of these 23:
"valueInteger" : <integer>
"valueDecimal" : <decimal>
"valueDateTime" : "<dateTime>"
"valueDate" : "<date>"
"valueInstant" : "<instant>"
"valueString" : "<string>"
"valueUri" : "<uri>"
"valueBoolean" : <boolean>
"valueCode" : "<code>"
"valueBase64Binary" : "<base64Binary>"
"valueCoding" : { Coding }
"valueCodeableConcept" : { CodeableConcept }
"valueAttachment" : { Attachment }
"valueIdentifier" : { Identifier }
"valueQuantity" : { Quantity }
"valueRange" : { Range }
"valuePeriod" : { Period }
"valueRatio" : { Ratio }
"valueHumanName" : { HumanName }
"valueAddress" : { Address }
"valueContactPoint" : { ContactPoint }
"valueSchedule" : { Schedule }
"valueReference" : { Reference }
}
XML Template
<extension|modifierExtension xmlns="http://hl7.org/fhir" url="identifies the meaning of the extension (uri)">
JSON Template
{
// from Element: extension
"url" : "<uri>", // R! identifies the meaning of the extension
// value[x]: Value of extension. One of these 23:
"valueInteger" : <integer>
"valueDecimal" : <decimal>
"valueDateTime" : "<dateTime>"
"valueDate" : "<date>"
"valueInstant" : "<instant>"
"valueString" : "<string>"
"valueUri" : "<uri>"
"valueBoolean" : <boolean>
"valueCode" : "<code>"
"valueBase64Binary" : "<base64Binary>"
"valueCoding" : { Coding }
"valueCodeableConcept" : { CodeableConcept }
"valueAttachment" : { Attachment }
"valueIdentifier" : { Identifier }
"valueQuantity" : { Quantity }
"valueRange" : { Range }
"valuePeriod" : { Period }
"valueRatio" : { Ratio }
"valueHumanName" : { HumanName }
"valueAddress" : { Address }
"valueContactPoint" : { ContactPoint }
"valueSchedule" : { Schedule }
"valueReference" : { Reference }
}
Notes:
An
extension
would
contain
other
extensions
instead
Here
is
an
example
of
an
extension
in
XML:
<name>
<extension url="http://hl7.org/fhir/StructureDefinition/iso-21090-name-use" >
<valueCode value="I" />
</extension>
<text value="Chief Red Cloud"/>
</name>
In
this
example,
the
name
with
text
=
"Chief
Red
Cloud"
is
extended
to
have
a
value
where
name
use
code
of
"Indigenous"
(defined
in
ISO
21090,
but
very
rarely
used
in
practice).
In JSON, extensions are represented similarly:
"name" : {
"extension" : [{
"url" : "http://hl7.org/fhir/StructureDefinition/iso-21090-name-use",
"valueCode" : "I"
}],
"text" : "Chief Red Cloud"
}
Making
the
types
explicit
in
the
representation
means
that
all
systems
can
read
and
write
(and
therefore
store
and/or
exchange)
extensions
correctly
without
needing
to
access
the
original
definition
of
the
extension.
Note that the JSON represenation for extensions on primitive data types is handled differently. See Representing primtive types in JSON for further information.
Extensions
can
also
contain
extensions,
either
because
the
extension
definition
itself
defines
complex
content
(i.e.
-
that
is,
a
nested
tree
of
values
in
the
extension,
or
because
the
extension
has
multiple
parts
rather
than
a
simple
data
type).
If
is
extended
with
an
additional
extension
defined
separately.
In
the
value
first
case,
the
identity
of
the
parts
of
the
extension
itself
needs
extending,
those
extensions
go
in
are
local/relative
to
the
content
of
reference
to
the
value[x]
element.
extension
definition.
Here
is
As
an
example
of
example,
consider
extending
a
name
patient
with
a
simple
extension
an
opt-in
status
for
a
tribal
name:
clinical
trial,
with
3
fields:
clinical
trial
number,
period
of
involvement,
and
a
reason
for
enrollment.
In
XML:
<Patient>
<extension url="http://hl7.org/fhir/StructureDefinition/patient-clinicalTrial" >
<extension url="NCT" >
<valueString value="123456789" />
</extension>
<extension url="period" >
<valuePeriod>
<start value="2009-03-14" />
</valuePeriod>
</extension>
<extension url="reason" >
<valueCodeableConcept>
<coding>
<system value="http://acme.org/codes/general" />
<code value="tt14j" />
</coding>
</valueCodeableConcept>
</extension>
</extension>
<text value="Chief Red Cloud"/>
</name>
<!-- other data for patient -->
</Patient>
or
Or
in
JSON:
{
"resourceType" : "Patient",
"extension" : [{
"url" : "http://hl7.org/fhir/StructureDefinition/patient-clinicalTrial",
"extension" : [{
"url" : "NCT",
"valueString" : "123456789"
}, {
"url" : "period",
"valuePeriod" : {
"start" : "2009-03-14"
}
}, {
"url" : "reason",
"valueCodeableConcept" : {
"coding" : {
"system" : "http://acme.org/codes/general",
"code" : "tt14j",
}
}
}]
}]
... other data for patient ...
}
The
proper
use
of
As
the
URL
value
suggests,
this
extension
is
discussed
below.
defined
as
part
of
this
specification
.
Extending
This
can
be
extended
again,
by
adding
a
patient
with
an
opt-in
status
for
"registrar"
extension:
The
registrar
is
defined
as
a
clinical
trial,
with
3
fields:
status,
date
separate
extension
(e.g.
by
an
implementing
organization),
rather
than
part
of
recording,
and
person
who
recorded:
the
official
clinical-trial
extension.
The
URL
of
the
extension
is
different:
<Patient><extension url="http://acme.org/fhir/Profile/main#trial-status" > <extension url="http://acme.org/fhir/Profile/main#trial-status-code" > <valueCode value="unsure" /><extension url="http://hl7.org/fhir/StructureDefinition/patient-clinicalTrial" > <extension url="NCT" > <valueString value="123456789" /> </extension><extension url="http://acme.org/fhir/Profile/main#trial-status-date" > <valueDate value="2009-03-14" /><extension url="period" > <valuePeriod> <start value="2009-03-14" /> </valuePeriod> </extension><extension url="http://acme.org/fhir/Profile/main#trial-status-who" > <valueResource> <reference value="Practitioner/example" /> </valueResource><extension url="reason" > <valueCodeableConcept> <coding> <system value="http://acme.org/codes/general" /> <code value="tt14j" /> </coding> </valueCodeableConcept> </extension> </extension> <extension url="http://acme.org/fhir/StructureDefinition/registrar" > <valueReference> <reference value="Practitioner/example" /> </valueReference> </extension> <!-- other data for patient --> </Patient>
or in JSON:
{
"resource-type" : "Patient",
"extension" : [
{
"url" : "http://acme.org/fhir/Profile/main#trial-status",
"extension" : [
{
"url" : "http://acme.org/fhir/Profile/main#trial-status-code",
"valueCode" : "unsure"
},
{
"url" : "http://acme.org/fhir/Profile/main#trial-status-date",
"valueDate" : "2009-03-14"
},
{
"url" : "http://acme.org/fhir/Profile/main#trial-status-who",
"valueResource" : {
"reference" : "Practitioner/example"
"resourceType" : "Patient",
"extension" : [{
"url" : "http://hl7.org/fhir/StructureDefinition/patient-clinicalTrial",
"extension" : [{
"url" : "NCT",
"valueString" : "123456789"
}, {
"url" : "period",
"valuePeriod" : {
"start" : "2009-03-14"
}
}, {
"url" : "reason",
"valueCodeableConcept" : {
"coding" : {
"system" : "http://acme.org/codes/general",
"code" : "tt14j",
}
}
]
}
],
... other data for patient...
}
},{
"url" : "http://acme.org/fhir/StructureDefinition/registrar",
"valueReference" : {
"reference" : "Practitioner/example"
}
}]
}]
... other data for patient ...
}
There are some cases where the information provided in extensions modifies the meaning of the element that contains it. Typically, this means information that qualifies or negates the primary meaning of the element that contains it. Some examples:
Implementers
should
avoid
the
use
of
modifier
extensions
where
possible.
Any
use
should
be
carefully
considered
against
its
possible
downstream
consequences.
However,
implementers
are
often
forced
into
these
situations
by
the
business
arrangements
around
the
use
of
resources,
so
this
specification
creates
a
framework
for
handling
these.
these
cases.
If
modifier
extensions
are
present,
an
application
cannot
safely
process
the
resource
unless
it
knows
what
the
extension
means
for
its
own
use
of
the
data.
This
specification
allows
for
such
modifier
elements
to
be
included
at
the
base
of
a
resource
or
in
any
elements
that
do
not
have
a
data
type
(e.g.
the
elements
that
correspond
to
classes
in
the
resource
UML
diagrams),
diagrams).
Elements
that
are
data
types,
or
that
are
inside
data
types
SHALL
NOT
have
modifier
extensions.
In
XML,
these
modifier
elements
are
represented
using
an
element
named
"modifierExtension",
which
has
same
content
as
the
extension
element
documented
above.
above:
Example: There's no element on MedicationOrder to write an "anti-prescription" - an instruction not to take a medication for a particular time. Classical clinical recording systems do not record this as a prescription - but one particular system does, and these "anti-prescription" records need to be shared within the institution where this happens, as they are an important part of the workflow. Hence, applications are allowed to extend a resource with data like this:
<MedicationOrder>
<modifierExtension url="http://example.org/fhir/StructureDefinition/anti-prescription">
<valueBoolean value="true"/>
</modifierExtension>
<!-- ... other content ... -->
</MedicationOrder>
Or in JSON:
{
"resourceType" : "MedicationOrder",
"modifierExtension" : [{
"url" : "http://example.org/fhir/StructureDefinition/anti-prescription",
"valueBoolean" : "true"
}],
.. other content ...
}
Implementations processing the data in resources SHALL check for modifiers anywhere they may appear, and if a modifier extension is present, SHALL do one of these things:
Note
that
processing
Processing
the
data
of
a
resource
typically
means
copying
or
filtering
data
out
of
a
resource
for
use
in
another
context
(display
to
a
human,
decision
support,
exchange
in
another
format
where
not
all
information
is
included,
or
storing
it
for
this
kind
of
use).
Servers
and
background
processes
that
simply
move
whole
resources
around
unchanged
are
not
"processing
the
data
of
the
resource",
and
therefore
these
applications
are
not
required
to
check
for
unknown
extensions.
1.12.6.0.2.1
Summary:
Conformance
Rules
for
Modifier
Extensions
A
modifierExtension
SHALL
only
modify
the
element
which
it
contains
and/or
its
children
It
SHALL
always
be
safe
to
show
the
narrative
to
humans;
any
modifier
extension
SHALL
be
represented
in
the
narrative.
Applications
SHALL
always
check
for
modifierExtensions
when
processing
the
data
from
any
element
that
may
carry
one.
If
a
modifierExtension
they
do
not
understand
is
found,
the
application
SHALL
either
refuse
to
process
the
resource
or
affected
element,
or
provide
an
appropriate
warning
to
its
users
1.12.6.0.2.2
Example
Example:
Because
of
a
lack
of
clinical
consensus,
there's
no
element
on
Procedure
for
any
expression
of
certainty
around
the
expression
of
the
Allergy/Intolerance.
Some
systems
mark
their
entries
as
"unlikely"
or
"probable".
Applications
are
allowed
to
extend
a
resource
with
data
like
this:
extensions.
#1
:
When
an
application
understands
this
extension,
it
means
that
some
developer
has
provided
appropriate
instructions
for
what
to
do
with
the
data
contained
in
it.
Note
that
there
is
no
obligation
that
it
because
of
the
application
do
anything
at
all
with
existence
of
the
data
modifier
extension.
#2
:
This
means
that
implementations
are
not
inherently
required
to
"support"
a
modifier
extension
in
any
meaningful
way
-
they
may
achieve
this
understanding
by
rejecting
instances
that
contain
this
extension
(a
server,
for
instance,
could
return
a
HTTP
422
status
code
with
an
OperationOutcome
if
a
client
PUTs
or
POSTs
a
modifier
extension
it
can
does
not
know.
Applications
may
also
be
able
to
ignore
it
a
modifier
extension
if
they
can
know
that
this
is
safe
to
do
in
its
own
context,
though
this
would
not
usually
be
the
case.
When
an
application
Note
that
doesn't
understand
this
extension
tries
to
process
this
resource,
it
is
required
implementations
may
be
able
to
either
refuse
be
sure,
due
to
process
their
implementation
environment
(e.g.
specific
trading
partner
agreement),
that
modifier
extensions
will
never
occur,
and
can
therefore
meet
the
resource
(or
containing
element),
or
provide
an
appropriate
warning
requirement
to
its
users.
Either
of
these
courses
of
action
is
potentially
difficult.
check
for
modifiers
at
the
design
stage.
However,
since
integration
and
deployment
options
often
change
subsequently,
applications
SHOULD
always
check
for
modifier
extensions
when
processing
resources
anyway.
#3
:
One
option
way
to
warn
the
user
is
to
download
the
profile
that
defines
the
extension
(from
definition
from
the
given
URL),
find
the
name
of
the
extension,
URL,
and
then
use
the
defined
display
name
to
display
present
the
extension
to
the
user.
An
error
message
could
look
something
like
this:
Note that the narrative of the resource SHALL contain this qualifying information, so it is safe to show this to the user as an expression of the resource's content. A warning dialog box could be extended to offer the user the choice to see the original narrative.
Here
is
an
the
prescription
example
showing
a
statement
that
a
particular
surgeon
did
not
perform
an
operation:
from
above
with
narrative:
<Procedure xmlns="http://hl7.org/fhir"><MedicationOrder xmlns="http://hl7.org/fhir"> <text> <status value="generated"/><div xmlns="http://www.w3.org/1999/xhtml">Routine appendicectomy for Fred Smith performed By Susan Taylor. Note: This operation was not performed by Dr Lakin</div><div xmlns="http://www.w3.org/1999/xhtml"> <p><b>Note: This prescription is an instruction NOT to take a medication</b></p> <!-- snip actual narrative --> </div> </text> <!-- ...data... --><performer> <modifierExtension> <url value="http://example.org/fhir/extensions#didNotPerform"/> <valueBoolean value="true"/> </modifierExtension> <person> <reference value="Practitioner/example"/> <display value="Dr Lakin"/> </person> </performer><modifierExtension url="http://example.org/fhir/StructureDefinition/anti-prescription"> <valueBoolean value="true"/> </modifierExtension> <!-- ...data... --></Procedure></MedicationOrder>
An
application
only
needs
to
concern
itself
with
modifierExtensions
on
elements
that
it
processes.
Take,
for
example,
the
case
above
where
a
procedure
resource
has
a
modifierExtension
on
one
of
the
performer
elements
indicating
that
they
did
not
participate
in
the
procedure.
In
this
case,
if
an
application
is
not
reading
the
performers
of
using
the
operation
performer
details
at
all,
the
fact
that
one
of
the
performers
has
a
modifierExtension
is
irrelevant
and
the
application
is
free
to
ignore
it.
If
it
does
process
the
performers,
and
it
sees
the
modifier
extension,
it
must
act
in
one
of
the
ways
outlined
above.
In some cases, implementers may find that they do not have appropriate data for an element with minimum cardinality = 1. In this case, the element must be present, but unless the resource or a profile on it has made the actual value of the primitive data type mandatory, it is possible to provide an extension that explains why the primitive value is not present:
<uri><extension url="http://hl7.org/fhir/Profile/general-extensions#data-absent-reason"><extension url="http://hl7.org/fhir/StructureDefinition/data-absent-reason"> <valueCode="unknown"/> </extension> </uri>
In this example, instead of a value, a data missing code is provided. Note that it is not required that this particular extension be used. This extension is not a modifier extension, because the primitive data type has no value.
It is not valid to create a fictional piece of data for the primitive value, and then to add an extension indicating that the data has been constructed to meet the data rules. This would be both a bad idea, and also a modifier extension, which is not allowed on data types.
Extensions are a way of allowing local requirements to be reflected in a resource using a common information based approach so that all systems can confidently process them using the same tools. However, when it comes to processing the information, applications will be constrained in their ability to handle extensions by the degree to which they are informed about them.
While
the
structured
definition
of
an
extension
should
always
be
available
(see
below
for
details),
the
mere
availability
of
a
definition
does
not
automatically
mean
that
applications
know
how
to
handle
them
correctly
-
generally,
human
decisions
are
required
to
be
made
around
how
the
data
in
extensions
contain
should
be
handled,
along
with
the
implicit
obligations
that
around
surround
the
information.
For this reason, local requirements that manifest as extensions are an obstacle to integration. The more the requirements are shared (i.e. regional or national scale), the less impact they will have. The consistent representation, definition and registration of extensions that this specification defines cannot resolve that problem - it only provides a framework within which such local variations can be handled more easily.
When it comes to deploying applications that support local requirements, situations will very likely arise where different applications exchanging information with each other are supporting different sets of extensions. This specification makes some basic rules that are intended to make management of these situations easier, but they cannot resolve them.
The degree to which a system can retain unknown extensions is a function of the type of system it is: a general purpose FHIR server, or a middleware engine would be expected to retain all extensions, while an application that manages patient registration through a user interface can only retain extensions to the degree that the information in them is part of the set managed by the user. Other applications will fall somewhere between these two extremes.
Use the following rules as a guideline for handling resources:
©
©
HL7.org
2011+.
FHIR
DSTU
(v0.0.82.2943)
DSTU2
(v1.0.2-7202)
generated
on
Tue,
Sep
30,
2014
18:10+1000.
Sat,
Oct
24,
2015
07:44+1100.
Links:
What's
a
DSTU?
Search
|
Version
History
|
Table
of
Contents
|
Compare
to
DSTU1
|
|
Propose
a
change