This page is part of the FHIR Specification (v0.4.0: DSTU 2 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.18.0 Narrative

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

Resources SHOULD always contain narrative to support human-consumption as a fallback. However, in a 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 consider carefully before doing this, as it will mean that these 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. In addition, 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		1..1	Element	A human-readable formatted text, including images
status		1..1	code	generated | extensions | additional 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

UML Diagram

to do

XML Template

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

JSON Template



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

Structure

Name	Flags	Card.	Type	Description & Constraints
Narrative		1..1	Element	A human-readable formatted text, including images
status		1..1	code	generated | extensions | additional 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

UML Diagram

todo

XML Template

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

JSON Template

{
  // from Element: extension
  "status" : "<code>", // R! generated | extensions | additional
  "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 - this 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 character content between the first ">" and the last "<" characters 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 and so there is no support for HTML entities like &nbsp; or &copy; etc. Unicode characters SHALL be used instead. Unicode &#160; substitutes for &nbsp;.

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 (and see the note in the HTML 5 specification about use of language).

1.18.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 it's 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 piece document, such as an bundle, duplicate values of the id attribute may occur between resources. This SHALL be managed by applications reading the resources.

Since that are not contained in the resource cannot be guaranteed to be 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.18.0.2 Styling the XHTML

The XHTML fragment in the narrative may be styled using cascading stylesheets using 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 do not 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 these styles. It's also available as XHTML and a standard stylesheet that includes all these styles.

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, though appropriate interpretation is allowed (e.g. a low-contrast display for dark room contexts 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 honor them. It SHOULD be safe to view the narrrative without these additional styling features available.

Note that there is additional rules around styling for documents presentation.

1.18.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 be restrained in using the features available. Even where trading partner arrangements limit the current requirements made on a system, experience shows that these trading arrangements will gradually 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 utilized as the sole way to convey meaning or semantics, but should be used in conjunction with other FHIR resources to ensure consistent, long term interoperability.