This page is part of the FHIR Specification (v1.2.0: STU 3 Draft). 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

• Narrative
• Examples
• Detailed Descriptions

1.16.0 Narrative

FHIR Infrastructure Work Group

Maturity Level: 3

Ballot Status: DSTU 2

Any resource that is a domain resource (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, it SHALL reflect all content needed for a human to understand the essential clinical and business information otherwise encoded within the resource. Resource definitions 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. 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.

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:

• Structure
• UML
• XML
• JSON
• All

Structure

Name	Flags	Card.	Type	Description & Constraints
Narrative			Element	A human-readable formatted text, including images
status		1..1	code	generated | extensions | additional | empty NarrativeStatus (Required)
div	I	1..1	xhtml	Limited xhtml content The narrative SHALL have some non-whitespace content The narrative 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 narrative SHALL contain only the basic html formatting 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
Documentation for this format

UML Diagram

XML Template

<[name] xmlns="http://hl7.org/fhir"> 
 <!-- from Element: extension -->
 <status value="[code]"/><!-- 1..1 generated | extensions | additional | empty -->
 <div xmlns="http://www.w3.org/1999/xhtml"> <!-- Limited xhtml content< --> </div>
</[name]>

JSON Template



{
  // from Element: extension
  "status" : "<code>", // R!  generated | extensions | additional | empty
  "div" : "(Escaped XHTML)" // R!  Limited xhtml content
}

Structure

Name	Flags	Card.	Type	Description & Constraints
Narrative			Element	A human-readable formatted text, including images
status		1..1	code	generated | extensions | additional | empty NarrativeStatus (Required)
div	I	1..1	xhtml	Limited xhtml content The narrative SHALL have some non-whitespace content The narrative 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 narrative SHALL contain only the basic html formatting 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
Documentation for this format

UML Diagram

XML Template

<[name] xmlns="http://hl7.org/fhir"> 
 <!-- from Element: extension -->
 <status value="[code]"/><!-- 1..1 generated | extensions | additional | empty -->
 <div xmlns="http://www.w3.org/1999/xhtml"> <!-- Limited xhtml content< --> </div>
</[name]>

JSON Template

{
  // from Element: extension
  "status" : "<code>", // R!  generated | extensions | additional | empty
  "div" : "(Escaped XHTML)" // R!  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 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.

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 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>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 type tooling would understand the resource language element. For this reason, a lang attribute on the <div> SHOULD also be used (see the note in the HTML 5 specification about use of language ).

1.16.0.1 Image References

Image source data (the src attribute) may refer to an image found in the resource (as a contained Media 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="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 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.

1.16.0.2 Styling the XHTML

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 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:

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:

• bold, italic, underline, strikethrough
• font color, family and size
• background color, text alignment
• whitespace interpretation
• ordered list number format (since it may be referred to in text)

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 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.

1.16.0.3 Clinical Safety Concerns

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:

• complex layered layouts requiring careful testing of the match between the XHTML 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
• 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.