Foundation
This
page
is
part
of
the
Continuous
Integration
Build
of
FHIR
Specification
(v4.0.1:
R4
-
Mixed
Normative
and
STU
)
in
it's
permanent
home
(it
will
always
(will
be
available
incorrect/inconsistent
at
this
URL).
The
current
version
which
supercedes
this
version
is
5.0.0
.
For
a
full
list
of
available
versions,
see
times).
See
the
Directory
of
published
versions
.
Page
versions:
R5
R4B
R4
R3
R2
|
Responsible
Owner:
FHIR
Infrastructure
Work
Group
|
Standards Status : Normative |
This exchange specification is based on generally agreed common requirements across healthcare - covering many jurisdictions, domains, and different functional approaches. It is common for specific implementations to have valid requirements that are not part of these agreed common requirements. Incorporating all valid requirements would make this specification very cumbersome and difficult to implement. Instead, this specification expects that additional valid requirements will be implemented as extensions.
As such, extensibility is a fundamental part of the design of this specification. Every element in a resource can 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.
To
make
the
use
of
extensions
safe
and
manageable,
managable,
there
is
strict
governance
applied
to
the
definition
and
use
of
extensions.
Although
any
implementer
can
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
datatype
element
that
may
be
present
any
number
of
times.
This
include
one
or
more
"extension"
child
elements.
The
extension
is
the
content
model
of
the
either
simple
or
complex
.
Simple
extensions
have
only
a
value
and
no
nested
extensions.
Complex
extensions
contain
one
or
more
nested
extensions
and
no
value.
An
extension
as
it
appears
in
each
resource:
can
not
have
both
a
value
and
nested
extensions.
The Extension definition is shown below:
Structure
| Name | Flags | Card. | Type |
Description
&
Constraints
Filter:
|
|---|---|---|---|---|
Extension
|
|
Element |
Optional
Extensions
Element
+ Rule: Must have either extensions or value[x], not both Elements defined in Ancestors: id , extension |
|
url
|
Σ | 1..1 | uri |
identifies
the
meaning
of
the
extension
|
value[x]
|
Σ C | 0..1 | * |
Value
of
extension
|
|
Documentation
for
this
format
|
||||
UML Diagram ( Legend )
XML Template
<extension|modifierExtension xmlns="http://hl7.org/fhir" url="identifies the meaning of the extension (uri)"> <!-- from Element: extension --><</value[x]><value[x]><!-- I 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 55:
"valueBase64Binary" : "<base64Binary>"
">
">"
">"
">"
">"
">
">"
">"
">
">"
">"
">"
">"
">"
">"
">"
">"
">"
" }
" }
" }
" }
" }
" }
" }
" }
" }
" }
" }
" }
" }
" }
" }
" }
" }
" }
" }
" }
" }
" }
" }
" }
" }
" }
" }
" }
" }
" }
" }
"valueBoolean" : <boolean>,
"valueCanonical" : "<canonical>",
"valueCode" : "<code>",
"valueDate" : "<date>",
"valueDateTime" : "<dateTime>",
"valueDecimal" : <decimal>,
"valueId" : "<id>",
"valueInstant" : "<instant>",
"valueInteger" : <integer>,
"valueInteger64" : "<integer64>",
"valueMarkdown" : "<markdown>",
"valueOid" : "<oid>",
"valuePositiveInt" : "<positiveInt>",
"valueString" : "<string>",
"valueTime" : "<time>",
"valueUnsignedInt" : "<unsignedInt>",
"valueUri" : "<uri>",
"valueUrl" : "<url>",
"valueUuid" : "<uuid>",
"valueAddress" : { Address },
"valueAge" : { Age },
"valueAnnotation" : { Annotation },
"valueAttachment" : { Attachment },
"valueCodeableConcept" : { CodeableConcept },
"valueCodeableReference" : { CodeableReference },
"valueCoding" : { Coding },
"valueContactPoint" : { ContactPoint },
"valueCount" : { Count },
"valueDistance" : { Distance },
"valueDuration" : { Duration },
"valueHumanName" : { HumanName },
"valueIdentifier" : { Identifier },
"valueMoney" : { Money },
"valuePeriod" : { Period },
"valueQuantity" : { Quantity },
"valueRange" : { Range },
"valueRatio" : { Ratio },
"valueRatioRange" : { RatioRange },
"valueReference" : { Reference },
"valueSampledData" : { SampledData },
"valueSignature" : { Signature },
"valueTiming" : { Timing },
"valueContactDetail" : { ContactDetail },
"valueDataRequirement" : { DataRequirement },
"valueExpression" : { Expression },
"valueParameterDefinition" : { ParameterDefinition },
"valueRelatedArtifact" : { RelatedArtifact },
"valueTriggerDefinition" : { TriggerDefinition },
"valueUsageContext" : { UsageContext },
"valueAvailability" : { Availability },
"valueExtendedContactDetail" : { ExtendedContactDetail },
"valueVirtualServiceDetail" : { VirtualServiceDetail },
"valueDosage" : { Dosage },
"valueMeta" : { Meta },
}
Turtle Template
@prefix fhir: <http://hl7.org/fhir/> . [# from Element: fhir: # . One of these 50 fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ]# from Element: fhir:extension fhir:url [ uri ] ; # 1..1 identifies the meaning of the extension # value[x] : 0..1 I Value of extension. One of these 55 fhir:value [ a fhir:Base64Binary ; base64Binary ] fhir:value [ a fhir:Boolean ; boolean ] fhir:value [ a fhir:Canonical ; canonical ] fhir:value [ a fhir:Code ; code ] fhir:value [ a fhir:Date ; date ] fhir:value [ a fhir:DateTime ; dateTime ] fhir:value [ a fhir:Decimal ; decimal ] fhir:value [ a fhir:Id ; id ] fhir:value [ a fhir:Instant ; instant ] fhir:value [ a fhir:Integer ; integer ] fhir:value [ a fhir:Integer64 ; integer64 ] fhir:value [ a fhir:Markdown ; markdown ] fhir:value [ a fhir:Oid ; oid ] fhir:value [ a fhir:PositiveInt ; positiveInt ] fhir:value [ a fhir:String ; string ] fhir:value [ a fhir:Time ; time ] fhir:value [ a fhir:UnsignedInt ; unsignedInt ] fhir:value [ a fhir:Uri ; uri ] fhir:value [ a fhir:Url ; url ] fhir:value [ a fhir:Uuid ; uuid ] fhir:value [ a fhir:Address ; Address ] fhir:value [ a fhir:Age ; Age ] fhir:value [ a fhir:Annotation ; Annotation ] fhir:value [ a fhir:Attachment ; Attachment ] fhir:value [ a fhir:CodeableConcept ; CodeableConcept ] fhir:value [ a fhir:CodeableReference ; CodeableReference ] fhir:value [ a fhir:Coding ; Coding ] fhir:value [ a fhir:ContactPoint ; ContactPoint ] fhir:value [ a fhir:Count ; Count ] fhir:value [ a fhir:Distance ; Distance ] fhir:value [ a fhir:Duration ; Duration ] fhir:value [ a fhir:HumanName ; HumanName ] fhir:value [ a fhir:Identifier ; Identifier ] fhir:value [ a fhir:Money ; Money ] fhir:value [ a fhir:Period ; Period ] fhir:value [ a fhir:Quantity ; Quantity ] fhir:value [ a fhir:Range ; Range ] fhir:value [ a fhir:Ratio ; Ratio ] fhir:value [ a fhir:RatioRange ; RatioRange ] fhir:value [ a fhir:Reference ; Reference ] fhir:value [ a fhir:SampledData ; SampledData ] fhir:value [ a fhir:Signature ; Signature ] fhir:value [ a fhir:Timing ; Timing ] fhir:value [ a fhir:ContactDetail ; ContactDetail ] fhir:value [ a fhir:DataRequirement ; DataRequirement ] fhir:value [ a fhir:Expression ; Expression ] fhir:value [ a fhir:ParameterDefinition ; ParameterDefinition ] fhir:value [ a fhir:RelatedArtifact ; RelatedArtifact ] fhir:value [ a fhir:TriggerDefinition ; TriggerDefinition ] fhir:value [ a fhir:UsageContext ; UsageContext ] fhir:value [ a fhir:Availability ; Availability ] fhir:value [ a fhir:ExtendedContactDetail ; ExtendedContactDetail ] fhir:value [ a fhir:VirtualServiceDetail ; VirtualServiceDetail ] fhir:value [ a fhir:Dosage ; Dosage ] fhir:value [ a fhir:Meta ; Meta ] ]
Changes since Release 3
Changes from both R4 and R4B
| Extension | |
| Extension.url |
|
| Extension.value[x] |
|
See the Full Difference for further information
Structure
| Name | Flags | Card. | Type |
Description
&
Constraints
Filter:
|
|---|---|---|---|---|
|
Extension
|
|
Element |
Optional
Extensions
Element
+ Rule: Must have either extensions or value[x], not both Elements defined in Ancestors: id , extension |
|
|
url
|
Σ | 1..1 | uri |
identifies
the
meaning
of
the
extension
|
|
value[x]
|
Σ C | 0..1 | * |
Value
of
extension
|
|
Documentation
for
this
format
|
||||
XML Template
<extension|modifierExtension xmlns="http://hl7.org/fhir" url="identifies the meaning of the extension (uri)"> <!-- from Element: extension --><</value[x]><value[x]><!-- I 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 55:
"valueBase64Binary" : "<base64Binary>"
">
">"
">"
">"
">"
">
">"
">"
">
">"
">"
">"
">"
">"
">"
">"
">"
">"
" }
" }
" }
" }
" }
" }
" }
" }
" }
" }
" }
" }
" }
" }
" }
" }
" }
" }
" }
" }
" }
" }
" }
" }
" }
" }
" }
" }
" }
" }
" }
"valueBoolean" : <boolean>,
"valueCanonical" : "<canonical>",
"valueCode" : "<code>",
"valueDate" : "<date>",
"valueDateTime" : "<dateTime>",
"valueDecimal" : <decimal>,
"valueId" : "<id>",
"valueInstant" : "<instant>",
"valueInteger" : <integer>,
"valueInteger64" : "<integer64>",
"valueMarkdown" : "<markdown>",
"valueOid" : "<oid>",
"valuePositiveInt" : "<positiveInt>",
"valueString" : "<string>",
"valueTime" : "<time>",
"valueUnsignedInt" : "<unsignedInt>",
"valueUri" : "<uri>",
"valueUrl" : "<url>",
"valueUuid" : "<uuid>",
"valueAddress" : { Address },
"valueAge" : { Age },
"valueAnnotation" : { Annotation },
"valueAttachment" : { Attachment },
"valueCodeableConcept" : { CodeableConcept },
"valueCodeableReference" : { CodeableReference },
"valueCoding" : { Coding },
"valueContactPoint" : { ContactPoint },
"valueCount" : { Count },
"valueDistance" : { Distance },
"valueDuration" : { Duration },
"valueHumanName" : { HumanName },
"valueIdentifier" : { Identifier },
"valueMoney" : { Money },
"valuePeriod" : { Period },
"valueQuantity" : { Quantity },
"valueRange" : { Range },
"valueRatio" : { Ratio },
"valueRatioRange" : { RatioRange },
"valueReference" : { Reference },
"valueSampledData" : { SampledData },
"valueSignature" : { Signature },
"valueTiming" : { Timing },
"valueContactDetail" : { ContactDetail },
"valueDataRequirement" : { DataRequirement },
"valueExpression" : { Expression },
"valueParameterDefinition" : { ParameterDefinition },
"valueRelatedArtifact" : { RelatedArtifact },
"valueTriggerDefinition" : { TriggerDefinition },
"valueUsageContext" : { UsageContext },
"valueAvailability" : { Availability },
"valueExtendedContactDetail" : { ExtendedContactDetail },
"valueVirtualServiceDetail" : { VirtualServiceDetail },
"valueDosage" : { Dosage },
"valueMeta" : { Meta },
}
Turtle Template
@prefix fhir: <http://hl7.org/fhir/> . [# from Element: fhir: # . One of these 50 fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ] fhir: ]# from Element: fhir:extension fhir:url [ uri ] ; # 1..1 identifies the meaning of the extension # value[x] : 0..1 I Value of extension. One of these 55 fhir:value [ a fhir:Base64Binary ; base64Binary ] fhir:value [ a fhir:Boolean ; boolean ] fhir:value [ a fhir:Canonical ; canonical ] fhir:value [ a fhir:Code ; code ] fhir:value [ a fhir:Date ; date ] fhir:value [ a fhir:DateTime ; dateTime ] fhir:value [ a fhir:Decimal ; decimal ] fhir:value [ a fhir:Id ; id ] fhir:value [ a fhir:Instant ; instant ] fhir:value [ a fhir:Integer ; integer ] fhir:value [ a fhir:Integer64 ; integer64 ] fhir:value [ a fhir:Markdown ; markdown ] fhir:value [ a fhir:Oid ; oid ] fhir:value [ a fhir:PositiveInt ; positiveInt ] fhir:value [ a fhir:String ; string ] fhir:value [ a fhir:Time ; time ] fhir:value [ a fhir:UnsignedInt ; unsignedInt ] fhir:value [ a fhir:Uri ; uri ] fhir:value [ a fhir:Url ; url ] fhir:value [ a fhir:Uuid ; uuid ] fhir:value [ a fhir:Address ; Address ] fhir:value [ a fhir:Age ; Age ] fhir:value [ a fhir:Annotation ; Annotation ] fhir:value [ a fhir:Attachment ; Attachment ] fhir:value [ a fhir:CodeableConcept ; CodeableConcept ] fhir:value [ a fhir:CodeableReference ; CodeableReference ] fhir:value [ a fhir:Coding ; Coding ] fhir:value [ a fhir:ContactPoint ; ContactPoint ] fhir:value [ a fhir:Count ; Count ] fhir:value [ a fhir:Distance ; Distance ] fhir:value [ a fhir:Duration ; Duration ] fhir:value [ a fhir:HumanName ; HumanName ] fhir:value [ a fhir:Identifier ; Identifier ] fhir:value [ a fhir:Money ; Money ] fhir:value [ a fhir:Period ; Period ] fhir:value [ a fhir:Quantity ; Quantity ] fhir:value [ a fhir:Range ; Range ] fhir:value [ a fhir:Ratio ; Ratio ] fhir:value [ a fhir:RatioRange ; RatioRange ] fhir:value [ a fhir:Reference ; Reference ] fhir:value [ a fhir:SampledData ; SampledData ] fhir:value [ a fhir:Signature ; Signature ] fhir:value [ a fhir:Timing ; Timing ] fhir:value [ a fhir:ContactDetail ; ContactDetail ] fhir:value [ a fhir:DataRequirement ; DataRequirement ] fhir:value [ a fhir:Expression ; Expression ] fhir:value [ a fhir:ParameterDefinition ; ParameterDefinition ] fhir:value [ a fhir:RelatedArtifact ; RelatedArtifact ] fhir:value [ a fhir:TriggerDefinition ; TriggerDefinition ] fhir:value [ a fhir:UsageContext ; UsageContext ] fhir:value [ a fhir:Availability ; Availability ] fhir:value [ a fhir:ExtendedContactDetail ; ExtendedContactDetail ] fhir:value [ a fhir:VirtualServiceDetail ; VirtualServiceDetail ] fhir:value [ a fhir:Dosage ; Dosage ] fhir:value [ a fhir:Meta ; Meta ] ]
Changes since Release 3
Changes from both R4 and R4B
| Extension | |
| Extension.url |
|
| Extension.value[x] |
|
See the Full Difference for further information
Notes:
url
is
a
mandatory
attribute
/
property
and
identifies
a
retrievable
extension
definition
that
defines
the
content
and
meaning
of
the
extension
Extension.url
or
on
Element.id
;
see
ElementDefinition.representation
for
background
url
SHALL
be
a
URL,
not
a
URN
extension
StructureDefinition.differential.element[0].code
)
valueCode
is
fhir:value
,
and
the
type
(
Code
)
is
indicated
in
an
additional
assertion,
such
as
...
a
fhir:Code
.
See
FHIR
RDF
Property
Names
for
further
explanation.
Here is an example of an extension in XML ( see definition ):
<name>
<extension url="http://hl7.org/fhir/StructureDefinition/iso-21090-EN-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 name use code of "Indigenous" (defined in ISO 21090, but very rarely used in practice).
In JSON, extensions are represented similarly:
{
"extension" : [{
"url" : "http://hl7.org/fhir/StructureDefinition/iso-21090-EN-use",
"valueCode" : "I"
}],
"text" : "Chief Red Cloud"
"extension": [
{
"url": "http://hl7.org/fhir/StructureDefinition/iso-21090-EN-use",
"valueCode": "I"
}
],
"text": "Chief Red Cloud"
}
In RDF (Turtle), the same extension looks like this:
...
fhir:extension (
[
fhir:url [
fhir:l <http://hl7.org/fhir/StructureDefinition/iso-21090-EN-use> ;
fhir:v "http://hl7.org/fhir/StructureDefinition/iso-21090-EN-use"^^xsd:anyURI
] ;
fhir:value [
a fhir:code ;
fhir:v "I"
]
]
) ;
fhir:text [ fhir:v "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 definition of the extension.
Note
that
the
JSON
representation
for
extensions
on
primitive
data
types
datatypes
is
handled
differently.
See
Representing
primitive
types
in
JSON
for
further
information.
Extensions can also contain extensions, either because the extension definition itself defines complex content - that is, a nested tree of values in the extension - or because the extension is extended with an additional extension defined separately.
In the case where an extension defines complex content, the identity of the parts of the extension are local/relative to the reference to the extension definition.
As an example, consider extending a patient with information about citizenship ( see definition ) containing 2 fields: code and period. In XML:
<Patient>
<extension url="http://hl7.org/fhir/StructureDefinition/patient-citizenship" >
<extension url="code" >
<valueCodeableConcept>
<coding>
<system value="urn:iso:std:iso:3166" />
<code value="DE" />
</coding>
</valueCodeableConcept>
</extension>
<extension url="period" >
<valuePeriod>
<start value="2009-03-14" />
</valuePeriod>
</extension>
</extension>
<!-- other data for patient -->
</Patient>
Or in JSON:
{
"resourceType" : "Patient",
"extension" : [{
"url" : "http://hl7.org/fhir/StructureDefinition/patient-citizenship",
"extension" : [{
"url" : "code",
"valueCodeableConcept" : {
"coding" : [{
"system" : "urn:iso:std:iso:3166",
"code" : "DE"
}]
}
}, {
"url" : "period",
"valuePeriod" : {
"start" : "2009-03-14"
}
}]
}]
"resourceType": "Patient",
"extension": [
{
"url": "http://hl7.org/fhir/StructureDefinition/patient-citizenship",
"extension": [
{
"url": "code",
"valueCodeableConcept": {
"coding": [
{
"system": "urn:iso:std:iso:3166",
"code": "DE"
}
]
}
},
{
"url": "period",
"valuePeriod": {
"start": "2009-03-14"
}
}
]
}
]
}
This extension can be extended again, by adding a "passport-number" extension:
The
passport
number
is
defined
as
a
separate
extension
(e.g.
(e.g.,
by
an
implementing
organization,
not
in
this
specification)
rather
than
part
of
the
official
citizenship
extension.
The
URL
of
the
extension
is
thus
different.
In
XML:
<Patient>
<extension url="http://hl7.org/fhir/StructureDefinition/patient-citizenship" >
<extension url="code" >
<valueCodeableConcept>
<coding>
<system value="urn:iso:std:iso:3166" />
<code value="DE" />
</coding>
</valueCodeableConcept>
</extension>
<extension url="period" >
<valuePeriod>
<start value="2009-03-14" />
</valuePeriod>
</extension>
<extension url="http://acme.org/fhir/StructureDefinition/passport-number" >
<valueString value="12345ABC" />
</extension>
<!-- other data for patient -->
</extension>
</Patient>
or in JSON:
{"resourceType" : "Patient", "extension" : [{ "url" : "http://hl7.org/fhir/StructureDefinition/patient-citizenship", "extension" : [{ "url" : "code", "valueCodeableConcept" : { "coding" : [{ "system" : "urn:iso:std:iso:3166", "code" : "DE" }] } },{ "url" : "period", "valuePeriod" : { "start" : "2009-03-14" } }, { "url": "http://acme.org/fhir/StructureDefinition/passport-number", "valueString": "12345ABC" }] }]"resourceType": "Patient", "extension": [ { "url": "http://hl7.org/fhir/StructureDefinition/patient-citizenship", "extension": [ { "url": "code", "valueCodeableConcept": { "coding": [ { "system": "urn:iso:std:iso:3166", "code": "DE" } ] } }, { "url": "period", "valuePeriod": { "start": "2009-03-14" } }, { "url": "http://acme.org/fhir/StructureDefinition/passport-number", "valueString": "12345ABC" } ] } ] }
Note that this passport number extension is shown here as an example defined by a fake organization, and not appropriate for re-use by implementers.
Primitive datatypes can carry extensions. The extensions may appear in place of the value of the primitive datatype. The XML , JSON and RDF pages describe how this looks in those respective formats. Implementers should be aware that a mandatory primitive datatype (i.e., mininum cardinality=1) may be present with extensions but no value. Type use case are extensions such as DataAbsentReason , nullFlavor and expression .
However, the use of an extension such as DataAbsentReason cannot be used to bypass a required binding requirements.
Note that this restriction also applies to extensible bindings on Coding and CodeableConcept datatypes. The use of an extension such as DataAbsentReason cannot be used to bypass a required or extensible binding requirements. For example, if a value set includes the concept of "unknown", then a DataAbsentReason of "unknown" cannot be sent without sending a Coding with the "unknown" concept. (In which case also sending an 'unknown' code would be inappropriate and unnecessary.)
There are some cases where the information provided in an extension 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:
Such extensions are known as "modifier extensions". For further information, see the definition of what makes an element - or an extension - a modifier . If modifier extensions are present, an application is restricted in its ability to safely process the resource unless it knows what the extension means for its own use of the data.
Implementers
SHOULD
avoid
the
use
of
modifier
extensions
where
possible.
Any
use
should
be
carefully
considered
against
its
possible
downstream
consequences.
Inclusion
of
modifier
extensions
in
an
instance
would
be
expected
to
significantly
limit
the
ability
of
other
systems
to
process
the
instance.
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
such
cases.
Implementers
who
are
introducing
an
extension
and
are
uncertain
whether
the
extension
should
be
marked
as
a
modifier
are
encouraged
to
raise
the
question
on
chat.fhir.org
.
This
specification
allows
for
such
modifier
elements
to
be
included
at
the
base
of
a
resource
or
domain
resource,
in
any
elements
that
do
not
have
a
data
type
(e.g.
datatype
(e.g.,
the
elements
that
correspond
to
classes
in
the
resource
UML
diagrams),
and
on
a
few
specially
selected
data
types
datatypes
.
Other
data
types
datatypes
and
elements
inside
data
types
datatypes
SHALL
NOT
have
modifier
extensions,
and
extensions
SHALL
NOT
have
modifier
extensions
internally
(except
for
the
reusable
structures
allowed
to
appear
in
extensions,
listed
above).
Whether
extensions
are
considered
modifiers
or
not
is
based
on
the
isModifier
flag
on
the
root
element
in
the
extension
definition
(the
element
definition
with
path
"Extension"
in
the
generated
snapshot).
If
this
is
true,
then
the
extension
SHALL
only
be
contained
in
the
modifierExtension
element.
If
this
is
false,
then
the
extension
SHALL
only
be
contained
in
the
extension
element.
Note
that
complex
extensions
are
allowed
to
have
elements
in
the
complex
extension
that
are
marked
Is-Modifier
=
true
,
which
means
that
these
elements
modify
the
extension
value
itself.
Internal
extensions
like
this
marked
"Is-Modifier"
are
still
represented
using
the
extension
element,
not
modifierExtension
because
the
impact
of
the
modifier
element
is
expected
to
be
known
by
applications
that
understand
the
containing
extension.
Modifier
extensions
SHALL
NOT
change
the
meaning
of
any
elements
on
Resource
or
DomainResource
(including
cannot
change
the
meaning
of
modifierExtension
itself).
Is-modifier
elements
not
defined
as
part
of
an
extension's
definition
cannot
be
conveyed.
conveyed
(e.g.,
an
extension
cannot
have
a
modifier
extension
in
it).
When
defining
a
new
modifier
extension,
it
is
designated
as
being
a
'modifier'
rather
than
a
'regular'
extension
by
setting
the
isModifier
element
on
the
root
'element'
for
the
StructureDefinition
to
'true'.
Only
extensions
that
are
defined
as
being
modifiers
can
appear
in
modifierExtension.
A
regular
extension
cannot
be
'constrained'
to
be
a
modifier.
In
XML,
these
modifier
elements
are
represented
using
an
element
named
modifierExtension
,
which
has
the
same
content
as
the
extension
element
documented
above:
Example: There's no element on MedicationRequest to write an "anti-prescription" - an instruction not to take a medication for a particular period. 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:
<MedicationRequest>
<modifierExtension url="http://example.org/fhir/StructureDefinition/anti-prescription">
<valueBoolean value="true"/>
</modifierExtension>
<!-- ... other content ... -->
</MedicationRequest>
Or in JSON:
{
"resourceType" : "MedicationRequest",
"modifierExtension" : [{
"url" : "http://example.org/fhir/StructureDefinition/anti-prescription",
"valueBoolean" : true
}],
"resourceType": "MedicationRequest",
"modifierExtension": [
{
"url": "http://example.org/fhir/StructureDefinition/anti-prescription",
"valueBoolean": true
}
],
.. other content ...
}
See the RDF page for an example in RDF (Turtle).
Implementations processing the data in resources SHALL check for modifiers anywhere they could appear, and if a modifier extension is present on a data element that the application 'processes', SHALL do one of these things:
extensions
or
generated
,
display
the
narrative
and
don't
process
the
discrete
data
Processing
For
the
purpose
of
this
page,
processing
the
data
of
a
resource
typically
means
is
taken
to
mean
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
modifier
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 because of the existence of the modifier extension or has determined that the modifier does not impact on the system's computational functions. Note that this assessment needs to be repeated each time a system's computational behavior changes
#2 : This means that implementations are not inherently required to "support" a modifier extension in any meaningful way - they can 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 does not know). Applications might also be able to ignore a modifier extension if they know that it is safe to do so in their own context, though this would not usually be the case.
Implementations SHALL ensure that they do not process data containing unrecognized modifier extensions. Where a modifier appears on a child element within the resource rather than on the resource as a whole, the system can choose to process the resource but exclude the element containing the modifier from processing. i.e., treat the element with the modifier as if it were missing. This approach can only work if the processing can safely function with incomplete data. Caution needs to be taken if doing this for elements that have a 'meaning if missing'.
Note
that
implementations
might
be
able
to
be
sure,
due
to
their
implementation
environment
(e.g.
(e.g.,
specific
trading
partner
agreement),
that
modifier
extensions
will
never
occur,
and
can
therefore
meet
the
requirement
to
check
for
modifiers
at
the
design
stage.
However,
since
integration
and
deployment
options
often
change,
applications
SHOULD
always
check
for
modifier
extensions
when
processing
resources.
#3 : One way to warn the user is to download the extension definition from the given URL, and then use the defined display name to present the extension to the user. An error message could look something like this:
Note that the narrative of the resource SHALL contain modifying 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.
An
application
only
needs
to
concern
itself
with
modifier
extensions
on
elements
that
it
processes.
Take,
for
example,
a
case
where
a
procedure
resource
has
a
modifier
extension
on
one
of
the
performer
elements
indicating
that
they
did
not
participate
in
the
procedure.
If
an
application
is
not
using
the
performer
details
at
all,
the
fact
that
one
of
the
performers
has
a
modifier
extension
is
irrelevant
and
the
application
is
free
to
ignore
it.
If
the
application
does
process
the
performers,
and
it
sees
the
modifier
extension,
it
must
act
in
one
of
the
ways
outlined
above.
Here is the prescription example from above with narrative:
<MedicationRequest xmlns="http://hl7.org/fhir">
<text>
<status value="generated"/>
<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... -->
<modifierExtension url="http://example.org/fhir/StructureDefinition/anti-prescription">
<valueBoolean value="true"/>
</modifierExtension>
<!-- ...data... -->
</MedicationRequest>
Implementation Guides might place limitations on the appearance of modifier extensions within instances that comply with the implementation guide.
In
some
cases,
implementers
might
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
datatype
mandatory,
it
is
possible
to
provide
an
extension
that
explains
why
the
primitive
value
is
not
present:
<uri> <extension url="http://hl7.org/fhir/StructureDefinition/data-absent-reason"><valueCode="unknown"/><valueCode value="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
datatype
has
no
value.
It
is
not
valid
to
create
a
fictional
piece
of
data
for
the
primitive
value,
and
then
add
an
extension
indicating
that
the
data
has
been
constructed
to
meet
the
data
rules.
This
would
be
both
a
bad
idea
as
well
as
a
modifier
extension,
which
is
not
allowed
on
simple
data
types.
datatypes.
Note: This section describes the use of "non-modifier extensions", except where "modifier extensions" are explicitly mentioned (see Modifier Extensions above for details).
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 determine how the data in extensions should be handled, along with the implicit obligations that surround the information.
For
this
reason,
local
requirements
that
manifest
as
extensions
are
an
obstacle
to
integration
and
interoperability.
The
more
the
requirements
are
shared
(i.e.
(i.e.,
regional
or
national
scale),
the
less
of
an
obstacle
the
extensions
(and
the
requirements
they
represent)
will
represent.
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 defines some basic rules that are intended to make management of these situations easier, but it 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:
FHIR
®©
HL7.org
2011+.
FHIR
Release
4
(Technical
Correction
#1)
(v4.0.1)
R6
hl7.fhir.core#6.0.0-ballot3
generated
on
Fri,
Sat,
Nov
1,
2019
09:37+1100.
QA
Page
8,
2025
11:28+0000.
Links:
Search
|
Version
History
|
Table
of
Contents
|
Credits
Glossary
|
QA
|
Compare
to
R3
R4
|
Compare
to
R5
|
Compare
to
Last
Ballot
|
|
Propose
a
change