Foundation
This page is part of the FHIR Specification (v1.6.0:
STU
3 Ballot 4). The current version which supercedes this version is
5.0.0
.
For
a
full
list
of
available
versions,
see
the
Directory
of
published
versions
. For a full list of available versions, see the
Directory of published versions 
.
Page
versions:
. Page versions:
R5
R4B
R4
R3
R2
|
|
|
|
Any resource that is a DomainResource (almost all types of resource) 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 'none', it SHALL reflect all content needed for a human to understand the essential clinical and business information for the resource. I.e. It must 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 is allowed to 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 descriptional 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.
For example, the narrative for a MedicationOrder might include brief summary information about the referenced patient, prescriber and medication. Some resources (e.g. List, Composition) may provide specific rules about what content must (or must not) be included in the resource narrative. Consideration should 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.
Resources 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.
In some cases, a resource may only have text with little or no additional discrete data (as long as all minOccurs=1 elements are satisfied). This may 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 in formation is added later.
Note that
contained
Resources
SHALL
NOT
have
a
narrative
of
their
own.
The
narrative
is
an
XHTML
fragment
with
a
flag
to
indicate
its
relationship
to
the
data:
Resources SHALL NOT have a narrative of their own.
The narrative is an XHTML fragment with a flag to indicate its relationship to the data:
Structure
| Name | Flags | Card. | Type |
|
|---|---|---|---|---|
Narrative
|
Element |
|
||
status
|
1..1 | code |
NarrativeStatus |
|
div
|
I | 1..1 | xhtml |
|
|
Documentation for this format
|
||||
UML
Diagram
UML Diagram
(
Legend
)
JSON
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.extension fhir:Narrative.status [ code ]; # 1..1 generated | extensions | additional | empty fhir:Narrative.div [ fhir:value "[escaped xhtml]"^^xsd:string ]; # 1..1 Limited xhtml content ]
Changes since DSTU2
| Narrative | No Changes |
See the Full Difference for further information
Structure
| Name | Flags | Card. | Type |
|
|---|---|---|---|---|
|
Narrative
|
Element |
|
||
|
status
|
1..1 | code |
NarrativeStatus |
|
|
div
|
I | 1..1 | xhtml |
|
|
Documentation for this format
|
||||
JSON
Template
JSON Template
{
{
// from Element: extension
"
"
"status" : "<code>", // R! generated | extensions | additional | empty
"div" : "(Escaped XHTML)" // R! Limited xhtml content
}
The
contents
of
the
Turtle Template
@prefix fhir: <http://hl7.org/fhir/> . [ # from Element: Element.extension fhir:Narrative.status [ code ]; # 1..1 generated | extensions | additional | empty fhir:Narrative.div [ fhir:value "[escaped xhtml]"^^xsd:string ]; # 1..1 Limited xhtml content ]
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
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 ,
a
body
element, external stylesheet references, deprecated elements, scripts, forms, base/link/xlink, frames, iframes, objects or event related attributes (e.g. 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.
The
div
element
SHALL
have
some
non-whitespace
content
(text
or
an
image).
). 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.
The div element SHALL have some non-whitespace content (text or an image).
<narrative>
<div xmlns="http://www.w3.org/1999/xhtml">This is a simple
example with only plain text</div>
</narrative>
<narrative>
<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
The inner portion of the
div
content is often used for the
innerHTML
content
is
often
used
for
the
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
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. element;
e.g.
"div": "<div>text</div>"is legal, but this is not:
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
Note that the XHTML is contained in general XML so there is no support for HTML entities like
or or
©
etc. Unicode characters SHALL be used instead. Unicode etc.
Unicode
characters
SHALL
be
used
instead.
Unicode
 
substitutes for substitutes
for
. .
The
narrative
content
SHOULD
be
in
the
language
of
the
resource
,
but
there
is
no
reason
to
expect
that
HTML
type
tooling
would
understand
the
resource
The narrative content SHOULD be in the
language of the resource
, but there is no reason to expect that HTML type tooling would understand the resource
language
element.
For
this
reason,
a
element. For this reason, a
lang
attribute on the attribute
on
the
<div>
SHOULD also be used (see
the note in the HTML 5 specification about use of language SHOULD
also
be
used
(see
the
note
in
the
HTML
5
specification
about
use
of
language
).
).
Image source data (the
src
attribute) may refer to an image found in the resource (as a contained
Media
attribute)
may
refer
to
an
image
found
in
the
resource
(as
a
contained
or
or
Binary
resource)
by
its
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="pic1" contentType="image/gif">MEKH....SD/Z</Binary>
</contained>
References
between
the
narrative
and
the
resource
data
(in
either
direction)
are
mediated
by
the
XML
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". 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
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. uniqueness
scope
of
the
resource
that
contains
them.
If
multiple
resources
are
combined
into
a
single
combined
document,
such
as
a
If multiple resources are combined into a single combined document, such as a
Bundle
,
duplicate
values
of
the
, duplicate values of the
id
attribute may occur between resources. This SHALL be managed by applications reading the resources. 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
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.
, 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
and
id
attributes
on
the
XHTML
elements
and
internal
styles
are
applied
using
a
attributes on the XHTML elements and internal styles are applied using a
style
attribute
on
the
XHTML
elements
directly.
In
order
to
minimise
manageability
and
security
issues,
authoring
systems
cannot
specify
the
CSS
stylesheet
to
use
directly.
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:
attribute on the XHTML elements directly.
In order to minimise manageability and security issues, authoring systems cannot specify the CSS stylesheet to use directly. 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
| { 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.
Rendering
systems
SHOULD
respect
any
of
these
rendering
styles
when
they
are
specified
in
the
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 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
are
allowed
to
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
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). 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
Note that rendering systems are allowed to 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.
presentation.
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. 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
span
elements
and
styles,
and
those
that
include
nested
tables
(possibly
with
images)
as
well
make
rendering
consistency
difficult,
and
implementations
SHOULD
avoid
these
The
use
of
styles
e.g.
bolding,
italics
and
color;
SHOULD
NOT
be
sued
as
the
sole
way
to
convey
meaning
or
semantics,
but
should
be
used
in
conjunction
with
other
data
elements
to
ensure
consistent,
long
term
interoperability.
©
HL7.org
2011+.
FHIR
DSTU2
(v1.0.2-7202)
generated
on
Sat,
Oct
24,
2015
07:44+1100.
Links:
Search
|
Version
History
|
Table
of
Contents
|
Compare
to
DSTU1
elements and styles, and those that include nested tables (possibly with images) as well make rendering consistency difficult, and implementations SHOULD avoid these
© HL7.org 2011+. FHIR STU3 Ballot (v1.6.0-9663) generated on Thu, Aug 11, 2016 17:07+1000.
QA Page
Links:
Search
|
|
Version History
|
Table of Contents
|
Compare to DSTU2
|
|
Propose
a
change
try
{
var
currentTabIndex
=
sessionStorage.getItem('fhir-resource-tab-index');
}
catch(exception){
}
if
(!currentTabIndex)
currentTabIndex
=
'0';
$(
'#tabs-Narrative'
).tabs({
active:
currentTabIndex,
activate:
function(
event,
ui
)
{
store(ui.newTab.index());
}
});
function
store(currentTab)
{
document.activeElement.blur();
try
{
sessionStorage.setItem('fhir-resource-tab-index',
currentTab);
}
catch(exception){
}
$(
'#tabs-Narrative'
).tabs('option',
'active',
currentTab);
}
|
Propose a change