Release
4B
5
Foundation
This
page
is
part
of
the
FHIR
Specification
(v4.3.0:
R4B
(v5.0.0:
R5
-
STU
).
The
This
is
the
current
published
version
which
supercedes
in
it's
permanent
home
(it
will
always
be
available
at
this
version
is
5.0.0
.
URL).
For
a
full
list
of
available
versions,
see
the
Directory
of
published
versions
.
Page
versions:
R5
R4B
R5
R4B
R4
R3
R2
|
FHIR
Infrastructure
Work
Group
|
Maturity Level : Normative | Standards Status : Normative |
Any resource that is a DomainResource (all resources except Bundle , Parameters and Binary ) may include a human-readable narrative that contains a summary of the resource and may be used to represent the content of the resource to a human.
If
narrative
is
present
with
a
status
other
than
'empty',
it
SHALL
reflect
all
content
needed
for
a
human
to
understand
the
essential
clinical
and
business
information
for
the
resource.
It
SHALL
be
safe
to
render
only
the
narrative
of
the
resource
without
displaying
any
of
the
resource's
discrete/encoded
information.
Resource
definitions
and/or
profiles
on
resources
MAY
define
what
content
should
be
represented
in
the
narrative
to
ensure
clinical
safety.
The
narrative
for
a
resource
MAY
contain
additional
information
that
is
not
in
the
structured
data,
including
human-edited
content.
Such
additional
information
SHALL
be
in
the
scope
of
the
definition
of
the
resource,
though
it
is
common
for
the
narrative
to
include
additional
descriptive
information
extracted
from
other
referenced
resources
when
describing
references.
Narrative
for
a
resource
SHOULD
include
summary
information
about
any
referenced
resources
that
would
be
required
for
a
consumer
of
the
resource
to
be
able
to
understand
the
key,
essential
information
about
a
resource
without
retrieving
any
additional
resources.
If
the
Narrative.status
=
extensions,
the
narrative
SHALL
reflect
the
impact
of
all
modifier
extensions
that
extend
elements
that
are
themselves
described
by
the
narrative.
Narrative
MAY
include
generated
content
from
other
resources
and
still
be
considered
generated.
For
example,
the
narrative
for
a
MedicationRequest
might
include
brief
summary
information
about
the
referenced
patient,
prescriber
and
medication.
Some
resources
(e.g.
List)
can
provide
specific
rules
about
what
content
must
(or
must
not)
be
included
in
the
resource
narrative.
Consideration
would
be
given
to
the
fact
that
referenced
resources
may
be
updated
without
updating
referencing
resources,
so
the
proportion
of
content
of
a
referenced
resource
included
in
a
referencing
resource
should
be
limited.
Systems
MAY
choose
how
narrative
is
generated,
including
how
much
de-referencing
to
perform,
but
SHALL
NOT
assume
that
the
resource
is
rendered
in
any
particular
context
when
generating
narrative,
since
resources
will
be
used
in
multiple
contexts.
Resource
instances
that
permit
narrative
SHOULD
always
contain
narrative
to
support
human-consumption
as
a
fallback.
Structured
data
SHOULD
NOT
generally
contain
information
of
importance
to
human
readers
that
is
omitted
from
the
narrative.
Creators
of
FHIR
resources
should
not
assume
that
systems
will
render
(or
that
humans
will
see)
data
that
is
not
in
the
narrative.
However,
in
strictly
managed
trading
systems
where
all
systems
share
a
common
data
model
and
additional
text
is
unnecessary
or
even
a
clinical
safety
risk,
the
narrative
may
be
omitted.
Implementers
should
give
careful
consideration
before
doing
this,
as
it
will
mean
that
such
resources
can
only
be
understood
in
the
limited
trading
environment.
Closed
trading
partner
environments
are
very
likely
to
open
up
during
the
lifetime
of
the
resources
they
define.
Also,
many
workflow
steps
involving
finding
and
aggregating
resources
are
much
more
difficult
or
tedious
if
the
resources
involved
do
not
have
their
own
text.
A
resource
MAY
only
have
text
with
little
or
no
additional
discrete
data
(as
long
as
all
minOccurs=1
elements
are
satisfied).
This
can
be
necessary
for
data
from
legacy
systems
where
information
is
captured
as
a
"text
blob"
or
where
text
is
additionally
entered
raw
or
narrated
and
encoded
information
is
added
later.
The
narrative
is
an
XHTML
fragment
with
a
flag
to
indicate
its
relationship
to
the
data:
Structure
| Name | Flags | Card. | Type |
Description
&
Constraints
|
|---|---|---|---|---|
Narrative
|
N | Element |
Human-readable
summary
of
the
resource
(essential
clinical
and
business
information)
Elements defined in Ancestors: id , extension |
|
status
|
1..1 | code |
generated
|
extensions
|
additional
|
empty
Binding: NarrativeStatus ( Required ) |
|
div
|
|
1..1 | xhtml |
Limited
xhtml
content
+ Rule: The narrative SHALL contain only the basic html formatting elements and attributes described in chapters 7-11 (except section 4 of chapter 9) and 15 of the HTML 4.0 standard, <a> elements (either name or href), images and internally contained style attributes + Rule: The narrative SHALL have some non-whitespace content |
|
Documentation
for
this
format
|
||||
UML Diagram ( Legend )
XML Template
JSON Template
{
// from Element: extension
"status" : "<code>", // R! generated | extensions | additional | empty
"div" : "(Escaped XHTML)" // R! Limited xhtml content
}
Turtle Template
@prefix fhir: <http://hl7.org/fhir/> . [ # from Element: Element.extensionfhir: fhir:fhir:status [ code ] ; # 1..1 generated | extensions | additional | empty fhir:div [ fhir:value "[escaped xhtml]"^^xsd:string ] ; # 1..1 Limited xhtml content ]
Changes since Release 3
Structure
| Name | Flags | Card. | Type |
Description
&
Constraints
|
|---|---|---|---|---|
|
Narrative
|
N | Element |
Human-readable
summary
of
the
resource
(essential
clinical
and
business
information)
Elements defined in Ancestors: id , extension |
|
|
status
|
1..1 | code |
generated
|
extensions
|
additional
|
empty
Binding: NarrativeStatus ( Required ) |
|
|
div
|
|
1..1 | xhtml |
Limited
xhtml
content
+ Rule: The narrative SHALL contain only the basic html formatting elements and attributes described in chapters 7-11 (except section 4 of chapter 9) and 15 of the HTML 4.0 standard, <a> elements (either name or href), images and internally contained style attributes + Rule: The narrative SHALL have some non-whitespace content |
|
Documentation
for
this
format
|
||||
JSON Template
{
// from Element: extension
"status" : "<code>", // R! generated | extensions | additional | empty
"div" : "(Escaped XHTML)" // R! Limited xhtml content
}
Turtle Template
@prefix fhir: <http://hl7.org/fhir/> . [ # from Element: Element.extensionfhir: fhir:fhir:status [ code ] ; # 1..1 generated | extensions | additional | empty fhir:div [ fhir:value "[escaped xhtml]"^^xsd:string ] ; # 1..1 Limited xhtml content ]
If narrative is present with a status other than 'empty', it SHALL reflect all content needed for a human to understand the essential clinical and business information for the resource. It SHALL be safe to render only the narrative of the resource without displaying any of the resource's discrete/encoded information. Resource definitions and/or profiles on resources MAY define what content should be represented in the narrative to ensure clinical safety.
The
narrative
for
a
resource
MAY
contain
additional
information
that
is
not
in
the
structured
data,
including
human-edited
content.
Such
additional
information
SHALL
be
in
the
scope
of
the
definition
of
the
resource,
though
it
is
common
for
the
narrative
to
include
additional
descriptive
information
extracted
from
other
referenced
resources
when
describing
references.
Narrative
for
a
resource
SHOULD
include
summary
information
about
any
referenced
resources
that
would
be
required
for
a
consumer
of
the
resource
to
be
able
to
understand
the
key,
essential
information
about
a
resource
without
retrieving
any
additional
resources.
If
the
Narrative.status
=
extensions,
the
narrative
SHALL
reflect
the
impact
of
all
modifier
extensions
that
extend
elements
that
are
themselves
described
by
the
narrative.
Narrative
MAY
include
generated
content
from
other
resources
and
still
be
considered
generated.
For example, the narrative for a MedicationRequest might include brief summary information about the referenced patient, prescriber and medication. Some resources (e.g. List) can provide specific rules about what content must (or must not) be included in the resource narrative. Consideration would be given to the fact that referenced resources may be updated without updating referencing resources, so the proportion of content of a referenced resource included in a referencing resource should be limited.
Systems MAY choose how narrative is generated, including how much de-referencing to perform, but SHALL NOT assume that the resource is rendered in any particular context when generating narrative, since resources will be used in multiple contexts.
Resource instances that permit narrative SHOULD always contain narrative to support human-consumption as a fallback. Structured data SHOULD NOT generally contain information of importance to human readers that is omitted from the narrative. Creators of FHIR resources should not assume that systems will render (or that humans will see) data that is not in the narrative. However, in strictly managed trading systems where all systems share a common data model and additional text is unnecessary or even a clinical safety risk, the narrative may be omitted. Implementers should give careful consideration before doing this, as it will mean that such resources can only be understood in the limited trading environment. Closed trading partner environments are very likely to open up during the lifetime of the resources they define. Also, many workflow steps involving finding and aggregating resources are much more difficult or tedious if the resources involved do not have their own text.
A resource MAY only have text with little or no additional discrete data (as long as all minOccurs=1 elements are satisfied). This can be necessary for data from legacy systems where information is captured as a "text blob" or where text is additionally entered raw or narrated and encoded information is added later.
| FHIR Name | Value Domain | XML Representation | JSON representation |
|---|---|---|---|
| xhtml |
XHTML
with
rules
as
defined
below.
No
extensions
are
possible,
and
the
id
property
becomes
and
xml:id
on
the
root
element
which
is
an
xhtml
div
| xhtml:div - XHTML is included directly | JSON string encoding the XHTML div |
| There is no intrinsic length limit | XML Definition | JSON Definition |
The
contents
of
the
div
element
are
an
XHTML
fragment
that
SHALL
contain
only
the
basic
HTML
formatting
elements
described
in
chapters
7-11
(except
section
4
of
chapter
9)
and
15
of
the
HTML
4.0
standard,
<a>
elements
(either
name
or
href),
images
and
internally
contained
style
attributes.
The
XHTML
content
SHALL
NOT
contain
a
head
,
a
body
element,
external
stylesheet
references,
deprecated
elements,
scripts,
forms,
base/link/xlink,
frames,
iframes,
objects
or
event
related
attributes
(e.g.
onClick
).
This
is
to
ensure
that
the
content
of
the
narrative
is
contained
within
the
resource
and
that
there
is
no
active
content.
Such
content
would
introduce
security
issues
and
potentially
safety
issues
with
regard
to
extracting
text
from
the
XHTML.
Note
that
even
with
these
restrictions,
there
are
still
several
important
security
risks
associated
with
displaying
the
narrative.
The div element SHALL have some non-whitespace content (text or an image).
<narrative>
<status value="additional"/>
<div xmlns="http://www.w3.org/1999/xhtml">This is a simple
example with only plain text</div>
</narrative>
<narrative>
<status value="additional"/>
<div xmlns="http://www.w3.org/1999/xhtml">
<p>
This is an <i>example</i> with some <b>xhtml</b> formatting.
</p>
</div>
</narrative>
The
inner
portion
of
the
div
content
is
often
used
for
the
innerHTML
property
in
a
browser.
In
order
to
simplify
this
kind
of
processing,
when
the
narrative
is
represented
in
JSON,
it
SHALL
be
encoded
so
that
the
characters
between
the
first
'>'
and
the
last
'<'
delimiters
is
the
content
of
the
<div>
element;
e.g.
"div": "<div xmlns=\"http://www.w3.org/1999/xhtml\">text</div>"
is legal, but this is not:
"div": "<?xml ...><div>text</div>"
Note
that
the
XHTML
is
contained
in
general
XML
so
there
is
no
support
for
HTML
entities
like
or
©
etc.
Unicode
characters
SHALL
be
used
instead.
Unicode
 
substitutes
for
.
The
narrative
content
SHOULD
be
in
the
language
of
the
resource
,
but
there
is
no
reason
to
expect
that
HTML
enabled
tooling
would
understand
the
resource
language
element.
For
this
reason,
a
lang
attribute
on
the
<div>
SHOULD
also
be
used
if
language
is
declared
on
the
resource
(see
the
note
in
the
HTML
5
specification
about
use
of
language
).
A narrative may contain content from multiple languages. This is always possible in that the narrative may contain ad-hoc content in any language, often with inline translation provided - this is not unusual in clinical systems when dealing with patients/care providers speaking multiple languages. Some resources - specially standing documentation such as preparation notes - will contain the same documentation in several different languages.
Resources
containing
the
same
information
in
multiple
different
languages
should
use
a
div
element
with
an
XHTML
lang
attribute
in
the
root
div.
By
default,
all
languages
will
be
displayed
to
a
user,
but
multi-language
aware
applications
can
filter
the
content
by
language
and
only
display
the
language
that
ia
is
relevant
to
or
chosend
chosen
by
the
patient.
See
the
W3C
documentation
on
Language
declarations
for
further
information.
Image
source
data
(the
src
attribute)
may
refer
to
an
image
found
in
the
resource
(as
a
contained
Media
DocumentReference
or
Binary
resource)
by
its
id
:
<Patient xmlns="http://hl7.org/fhir">
<text>
<status value="generated"/>
<div xmlns="http://www.w3.org/1999/xhtml">
<p>... <img src="#pic1"/>. ....</p>
</div>
</text>
<contained>
<Binary><id value="pic1"/><contentType value="image/gif"/><data value="MEKH....SD/Z"/></Binary>
</contained>
</Patient>
Implementation Note: In the context of a browser displaying the narrative,
imgtags with asrcattribute starting with '#' need to be pre-processed by either replacing the img src with adata:value, or hosting the binary content somewhere accessible to the browser, or intercepting the browser's events to provide the source of the image.
References
between
the
narrative
and
the
resource
data
(in
either
direction)
are
mediated
by
the
XML
id
/
idref
attributes.
in
JSON,
the
property
"id"
is
used
which
is
equivalent
to
the
XML
attribute
"id".
The
id
attribute
SHALL
have
a
unique
value
within
the
resource
with
regard
to
any
other
id
attributes:
the
uniqueness
and
resolution
scope
of
these
id
references
is
within
the
resource
that
contains
them.
Contained
resources
are
included
in
the
id
uniqueness
scope
of
the
resource
that
contains
them.
If
multiple
resources
are
combined
into
a
single
combined
document,
such
as
a
Bundle
,
duplicate
values
of
the
id
attribute
may
occur
between
resources.
This
SHALL
be
managed
by
applications
reading
the
resources.
Since
images
that
are
not
contained
in
the
resource
cannot
be
guaranteed
to
be
available
when
the
resource
is
presented
to
a
user,
the
source
for
any
images
that
are
an
essential
part
of
the
narrative
SHOULD
always
be
embedded
as
a
data:
url
,
in
an
attachment
or
a
contained
resource
The XHTML fragment in the narrative may be styled using cascading stylesheets with either external or internal styles. External styles are applied using the class and id attributes on the XHTML elements and internal styles are applied using a style attribute on the XHTML elements directly.
In order to minimize manageability and security issues, authoring systems cannot specify the CSS stylesheet to use directly, unless the stylesheet is included in a FHIR Document. Instead, the application that displays the resource provides the stylesheets. This means that the rendering system chooses what styles can be used, but the authoring system must use them in advance. Authoring systems can use these classes, which SHALL be supported by all rendering systems:
| bold | Bold Text | { font-weight: bold } |
| italics | Italics Text | { font-style: italic } |
| underline | Underlined Text | { text-decoration: underline } |
| strikethrough | Strikethrough Text | { text-decoration: line-through } |
| left | Left Aligned | { text-align : left } |
| right | Right Aligned | { text-align : right } |
| center | Center Aligned | { text-align : center } |
| justify | Justified | { text-align : justify } |
| border-left | Border on the left | { border-left: 1px solid grey } |
| border-right | Border on the right | { border-right: 1px solid grey } |
| border-top | Border on the top | { border-top: 1px solid grey } |
| border-bottom | Border on the bottom | { border-bottom: 1px solid grey } |
| arabic | List is ordered using Arabic numerals: 1, 2, 3 | { list-style-type: decimal } |
| little-roman | List is ordered using little Roman numerals: i, ii, iii | { list-style-type: lower-roman } |
| big-roman | List is ordered using big Roman numerals: I, II, III | { list-style-type: upper-roman } |
| little-alpha | List is ordered using little alpha characters: a, b, c | { list-style-type: lower-alpha } |
| big-alpha | List is ordered using big alpha characters: A, B, C | { list-style-type: upper-alpha } |
| disc | List bullets are simple solid discs | { list-style-type: disc } |
| circle | List bullets are hollow discs | { list-style-type : circle } |
| square | List bullets are solid squares | { list-style-type: square } |
| unlist | List with no bullets | { list-style-type: none } |
Note: for testing purposes, there is an example resource that includes all of these styles. It is also available as XHTML and a standard stylesheet that includes all of these styles. Use of styles not on this list will require an arrangement between producing and consuming systems.
Authoring systems may refer to additional classes, but cannot rely on the fact that they will be supported. If the additional classes are critical for safe rendering, trading partner agreements will be required.
Authoring systems may also use internal styles using the style attribute. This has the advantage of not depending on external interpretation, but also has the side effect of making content more difficult to manage when rendering, so applications should use this approach with care.
Authoring systems may fix the following styling aspects of the content:
These
style
properties
are
specified
in-line
using
the
style
attribute.
Rendering
systems
SHOULD
respect
any
of
these
rendering
styles
when
they
are
specified
in
the
style
attribute,
although
appropriate
interpretation
is
allowed
in
certain
contexts
(e.g.
a
low-contrast
display
for
dark
rooms
or
a
high-contrast
display
for
the
visually
impaired
may
adjust
colors
accordingly).
Note that rendering systems can ignore or override any of the internal or external styles described above, but SHOULD be careful to ensure that this is only done in the context of well-maintained trading partner agreements, as altering the presentation of the text may create clinical safety issues.
Authors MAY specify additional styles and style properties as specified in the CSS specification, but these are extensions to this specification and renderers are not required to heed them. It SHOULD be safe to view the narrative without these additional styling features available.
Note that there are additional rules around styling for documents presentation.
In some contexts, it is useful to link between the two representations of the same content: structured data, and human readable narrative. This can be used to assert that the text is a representation of the data, or specifically that the data is derived from some particular text. This specification defines the extensions narrativeLink and originalText to establish these links. Here's an example of using originalText:
{
"resourceType" : "Condition",
"text" : {
"status" : "generated",
"div": "<div xmlns=\"http://www.w3.org/1999/xhtml\">There is a history of <span id=\"a1\">Asthma</span></div>"
},
"code" : {
"coding" : {
"system" : "http://snomed.info/sct",
"code" : "195967001",
"display" : "Asthma (disorder)"
},
"extension" : [{
"url" : "http://hl7.org/fhir/StructureDefinition/originalText",
"valueUrl" : "#a1"
}]
}
}
This indicates that the word "Asthma" in the narrative is the original text from which the SNOMED CT code "asthma" was derived by some text processing method. Typically, this method is associated with resources built from CDA documents. The same method can be used to reference across resource boundaries, e.g. between a resource and the composition that represents it:
<Bundle xmlns="http://hl7.org/fhir">
<entry>
<fullUrl value="http://example.org/fhir/Composition/abcdefghij"/>
<Composition>
<id value="c1"/>
<text>
<div xmlns="http://www.w3.org/1999/xhtml">
...
<p>There is a history of <span id="a1">Asthma</span></p>
...
</div>
</text>
<section>
...
<text>
<div xmlns="http://www.w3.org/1999/xhtml">
...
<p>There is a history of <span id="a1">Asthma</span></p>
...
</div>
</text>
</section>
</Composition>
</entry>
<entry>
<Condition>
<code>
<extension url="http://hl7.org/fhir/StructureDefinition/originalText">
<valueUrl value="http://example.org/fhir/Composition/abcdefghij#a1"/>
</extension>
<coding>
<system value="http://snomed.info/sct"/>
<code value="195967001"/>
<display value="Asthma (disorder)"/>
</coding>
</code>
</Condition>
</entry>
</Bundle>
Health care records are often associated with legislative and business requirements for very long retention times (up to a century) and extreme risk aversion with regards to inconsistent display across a variety of devices, rendering engines, and display constraints. Although the narrative is allowed to use the standard XHTML and CSS features as described above, implementations are encouraged to show restraint when using the features available. Even when trading partner arrangements limit the current requirements made on a system, experience shows that these trading arrangements will likely broaden over time.
In particular:
div
and
span
elements
and
styles,
and
those
that
include
nested
tables
(possibly
with
images)
as
well,
make
rendering
consistency
difficult,
and
implementations
SHOULD
avoid
these
FHIR
®©
HL7.org
2011+.
FHIR
Release
4B
(v4.3.0)
hl7.fhir.r4b.core#4.3.0
R5
hl7.fhir.core#5.0.0
generated
on
Sat,
May
28,
2022
12:58+1000.
Sun,
Mar
26,
2023
15:26+1100.
Links:
Search
|
Version
History
|
Table
of
Contents
|
Glossary
|
QA
Page
|
Compare
to
R4
|
Compare
to
R4B
|
|
Propose
a
change