This
page
was
published
as
part
of
FHIR
v3.3.0:
R4
Ballot
#1
:
Mixed
Normative/Trial
use
(First
Normative
ballot).
It
has
been
superceded
by
R4
.
For
a
full
list
of
available
versions,
see
the
Directory
of
published
versions
.

2.5.1
Defining
Extensions

This
page
is
candidate
normative
content
for
R4
in
has
been
approved
as
part
of
an
ANSI
standard.
See
the
Infrastructure
Package
.
Once
normative,
it
will
lose
it's
Maturity
Level,
and
breaking
changes
will
no
longer
be
made.
for
further
details.

All
extensions
used
in
resources
require
a
formal
published
definition
which
that
can
be
used
by
application
developers,
developers
or
the
applications
themselves,
to
help
integrate
extensions
into
the
healthcare
process
they
support.

Every
extension
in
a
resource
refers
directly
to
its
definition,
which
is
made
available
as
a
StructureDefinition
.
A
resource
can
be
profiled
to
specify
where
particular
extensions
are
used.
required
or
expected.

Whenever
resources
containing
extensions
are
exchanged,
the
definitions
of
the
extensions
SHALL
be
available
to
all
the
parties
that
share
the
resources.
Each
extension
contains
a
URI
that
references
the
source
of
the
definitions
as
a
StructureDefinition
.
The
source
SHOULD
be
a
literal
reference,
such
as
an
http:
URL
that
refers
to
an
end-point
that
responds
with
the
contents
of
the
definitions
-
preferably
a
FHIR
RESTful
server
supporting
the
Resources
Profile,
StructureDefinition
,
or
a
logical
reference
(e.g.
using
a
urn:)
-
for
instance,
to
a
national
published
standard.
Extensions
may
be
defined
by
any
project
or
jurisdiction,
up
to
and
including
international
standards
organizations
such
as
HL7
itself.

Before
defining
a
new
extension,
attempt
to
reuse
existing
extensions
defined
in
one
of
the
shared
registries
described
below
.
Also
consider
that
some
concepts
may
be
appropriate
to
add
as
part
of
the
core
specification.

2.5.1.1
Core
Elements

Elements
are
included
as
part
of
FHIR
resources
and
data
types
principally
on
the
basis
of
current
world-wide
usage
patterns.
Policy
is
that
if
a
significant
majority
of
systems
throughout
the
world
that
would
use
a
resource
or
data
type
would
use
an
element,
then
that
element
will
be
included
as
part
of
the
resource/data
type.
If
not,
it
will
be
left
to
an
extension.
This
holds
even
if
the
element
is
very
common
or
even
mandatory
in
one
or
two
specific
jurisdictions.

Proposals
suggesting
a
new
core
element
can
be
raised
by
anyone.
(Free
registration
is
required.)
However,
given
the
timelines
for
new
FHIR
releases
as
well
as
the
uncertainties
associated
with
vetting
the
specification
through
a
ballot
process,
it
may
still
be
necessary
to
define
extensions
even
for
elements
that
are
likely
to
be
supported
as
part
of
the
core
specification
in
a
future
release.

2.5.1.2
Context

Extensions
are
always
defined
against
some
particular
context
-
which
elements
they
can
extend.
There
are
three
different
ways
to
specify
which
elements
an
extension
can
be
found
on:

Code

Context
type

Context
format

Examples

fhirpath

A
FHIRPath
expression
that
selects
the
set
of
elements
on
which
the
extension
can
appear

The
FHIRPath
statement
always
starts
from
the
root
of
the
resource
that
might
contain
the
element

Element
Ids
are
unique
within
the
base
specification,
and
within
a
structure
definition.
The
full
path
for
the
element
is
[url]#[elementid].
If
there
is
no
#,
the
Element
id
is
one
defined
in
the
base
specification

The
canonical
URI
URL
of
the
extension,
optionally
followed
by
#code
for
extension
that
appear
within
a
complex
extension

http://hl7.org/fhir/StructureDefinition/device-din

Extensions
SHALL
only
be
used
on
a
target
that
appears
in
their
context
list.

2.5.1.3
Cardinality

The
cardinality
constraints
asserted
by
the
extension
definition
itself
apply
to
any
contexts
where
the
extension
is
used.

Minimum
Cardinality

If
the
Extension
minimum
cardinality
is
0,
then
the
extension
is
is,
by
default,
optional
anywhere
it
appears.
A
profile
that
defines
the
use
of
an
extension
may
make
the
minimum
cardinality
any
number
up
to
the
maximum
cardinality
of
the
extension
itself.
Example:
Example:
Patient
birthplace
.

If
the
Extension
minimum
cardinality
is
>
1,
then
the
extension
must
have
a
minimum
cardinality
of
at
least
the
minimum
cardinality
in
any
profile
that
defines
the
use
of
the
extension.
The
minimum
cardinality
may
be
any
number
up
to
the
maximum
cardinality
of
the
extension.
Even
with
a
minimum
cardinality
>
0,
the
extension
is
only
required
to
be
present
in
instances
if
the
instances
explicitly
or
implicitly
conform
to
a
profile
that
defines
the
use
of
the
extension.
Example:
CapabilityStatement
Expectation
.

Maximum
Cardinality

If
the
Extension
maximum
cardinality
is
1,
then
the
extension
is
only
allowed
once
on
any
element
on
which
it
appears.
A
profile
that
defines
the
use
of
an
extension
can
only
make
the
maximum
cardinality
1
(or
zero
if
the
minimum
cardinality
is
0,
and
the
profile
constrains
another
profile
that
allows
the
extension).
Example:
Mother's
Maiden
Name
.

If
the
Extension
maximum
cardinality
is
>1,
then
the
extension
is
allowed
up
to
the
specified
number
of
times
on
any
element
on
which
it
appears.
A
profile
that
defines
the
use
of
an
extension
may
make
the
maximum
cardinality
any
value
up
to
the
specified
maximum.
Example:
Patient
Disability
.

Context
Invariants

Extensions
are
also
able
to
define
context
invariants,
which
is
a
rule
that
is
executed
on
the
element
that
contains
the
extension
when
it
is
present
to
check
that
local
requirements
around
cardinality
and
other
business
rules
are
met.

Note
that
since
the
context
invariant
is
only
evaluated
when
the
extension
is
present,
there
is
an
implicit
"line.extension('http://hl7.org/fhir/StructureDefinition/iso21090-ADXP-streetName').exists()
implies"
at
the
start
of
the
expression.
A
context
invariant
that
enforces
that
the
extension
is
present
under
certain
circumstances
cannot
be
defined
in
the
extension
itself
-
it
must
be
defined
in
a
profile
that
makes
use
of
the
extension.

2.5.1.4
Use
of
ElementDefinition
in
Extension
Definitions

An
extension
is
a
wrapper
for
an
identifying
url
and
either
a
value
or
other
extensions.
As
such,
some
of
the
properties
of
the
extension
are
defined
on
the
extension
itself,
while
others
are
defined
on
the
Extension.value
.
This
list
provides
guidance
for
the
correct
usage:

Extension
root
element:

Cardinality

Short,
Definition,
Comments

IsModifier

MustSupport
(is
used
on
invocation
of
the
extension)

Conditions
&
Constraints.
These
SHOULD
never
be
on
url/value[x]

Mappings.
these
SHALL
never
be
on
url/value[x]

Extension.url
Extension.url:

Cardinality
=
1...1
(fixed)

value
=
canonical
url
URL
(fixed)

Extension.value[x]:

Extension.value[x]

Type

Cardinality
for
Simple
extensions
(not
nested):
1...1.
1..1.
Use
0..0
if
nested.
Note
that
the
actual
ED
extension
cardinality
is
defined
by
the
root
element

Binding

MaxLength,
DefaultValue,
Pattern,
Example,
MinValue,
MaxValue

Extension.extension:

Cardinality
for
Complex
extensions
(nested):
0..*,
though
at
least
one
nested
extension
must
be
present.
Use
0..0
if
a
simple
(non-nested
extension)

.extension
is
automatically
sliced
by
url

nested
extensions
can
be
defined
in-line
(as
children
elements
of
Extension.extension),
or
by
reference
(using
.type.profile)

2.5.1.5
Publishing
Extension
Definitions

As
well
as
defining
the
base
element
structure
for
resources,
HL7
also
publishes
extensions,
including
as
part
of
this
specification
.
HL7
publishes
such
data
definitions
as
extensions
rather
than
as
part
of
the
base
resource
structure
to
keep
the
base
resource
structure
simple
and
concise,
and
to
allow
implementers
freedom
from
needing
to
engage
with
an
entire
world's
worth
of
functionality
up
front.
Note
that
HL7
does
not
generally
define
"modifier"
extensions
-
if
HL7
publishes
an
element
that
modifies
the
meaning
of
other
elements,
it
will
generally
be
part
of
the
resource
content
itself,
since
everyone
has
to
understand
the
extension
anyway.

Before
extensions
can
be
used
in
instances,
their
definition
SHALL
be
published.
HL7
maintains
two
extension
registries:

HL7
approved
extensions,
approved
by
an
appropriate
part
of
the
HL7
community
following
a
review
process,
and
which
that
have
formal
standing

Provided
as
a
service
to
the
community,
where
anyone
can
register
an
extension

Users
are
encouraged
to
register
their
extensions
in
the
second
registry,
though
this
is
not
required.
All
that
is
required
is
that
the
extension
is
published
in
a
context
that
is
available
for
users
of
the
extension.
So,
for
example,
if
a
particular
extension
is
only
used
within
a
single
institution,
the
definition
of
the
extension
can
be
placed
on
the
institution's
intranet.
However
since,
by
their
nature,
resources
tend
to
travel
well,
it's
always
better
to
use
publish
it
on
a
public
facing
web
site.
Using
the
HL7
FHIR
registry
or
other
publicly
accessible
extension
registries.
registries
not
only
publishes
the
extension,
but
also
makes
it
easy
to
find
and
encourages
reuse
and
therefore
consistency
across
implementations.

HL7
extension
definitions
may
be
balloted
alongside
resource
content
as
part
of
the
FHIR
specification
or
may
be
published
as
part
of
separate
specifications.
When
HL7
publishes
extension
definitions
as
part
of
the
FHIR
specification,
these
extensions
SHALL
be
used
for
this
data
whenever
the
data
is
represented
in
instances.
Applications
SHOULD
use
other
HL7-defined
extensions
published
to
represent
equivalent
data
in
the
interest
of
maximum
interoperability.

To
minimize
complexity
for
implementers,
HL7
will
not
elevate
widely
adopted
extensions
(defined
by
HL7
or
other
organizations)
to
be
content
defined
in
a
core
resource
in
future
versions
of
the
resource
unless
there
is
widespread
endorsement
of
such
a
migration
from
the
implementer
community.
This
policy
ensures
that
widespread
adoption
of
an
extension
does
not
result
in
a
forced
migration
to
a
core
element.
Extensions
labeled
as
draft
may
be
moved
in
either
direction,
but
after
extensions
are
finalized
as
normative
they
won't
be
moved.

In
some
cases,
an
HL7
work
group
or
other
body
may
publish
a
profile
whose
sole
purpose
is
to
define
extensions
expected
to
be
needed
by
implementers
in
a
particular
context;
e.g.
extensions
needed
to
map
a
particular
set
of
HL7
v2
segments
or
a
HL7
v3
model.

Implementations
are
encouraged
to
share
their
extensions
with
HL7
and
register
them
with
the
HL7
extension
registry.
The
domain
committees
will
work
to
elevate
the
extensions
into
HL7
published
extensions
or,
if
adopted
by
a
broad
enough
portion
of
the
implementer
community,
into
the
base
resource
structure
itself.

To
avoid
interoperability
issues,
extensions
SHALL
NOT
change
their
definition
once
published.
(Small
clarifications
to
descriptions
that
do
not
affect
interoperability
are
permitted.)
Rather
than
modifying
an
existing
extension,
a
new
extension
should
be
introduced.
Revisions
to
an
extension
may
extend
the
set
of
contexts
in
which
the
extension
apply
but
SHALL
not
NOT
remove
or
constrain
any
context
previously
listed