---
type: "doc"
title: "FHIR Documents"
source: "source/documents.html"
---
\[%settitle FHIR Documents%\] \[%file newheader%\] \[%file newnavbar%\]

# FHIR Documents

| Responsible Owner: [\[%wgt fhir%\]]([%wg fhir%]) Work Group | [Standards Status](versions#std-process):[Normative](versions#std-process) |
| --- | --- |

FHIR resources can be used to build documents that represent a composition: a coherent set of information that is a statement of healthcare information, including clinical observations and services. A document is a set of resources with a fixed presentation that is authored and/or attested by humans, organizations and devices.

A FHIR document instance is a [Bundle](bundle) of type `document` that starts with a [Composition](composition) and contains specific frozen versions of other resources. Changes to a document Bundle may risk invalidating the attestation present within the document. Implementations SHOULD have policies around when documents can be 'updated' (new version of the same instance) vs. when a distinct document needs to be created, as well as what types of change are permitted, in order to retain attestation validity. These rules might vary based on the type of document (e.g., legal documents, clinical documents, etc.).

Documents built in this fashion may be exchanged between systems and persisted in document storage and management systems, including systems such as [IHE XDS](https://wiki.ihe.net/index.php/Cross-Enterprise_Document_Sharing).

Applications that declare support for FHIR documents with [CapabilityStatement.document](capabilitystatement-definitions#CapabilityStatement.document) are asserting conformance to the rules defined on this page.

FHIR documents may serve clinical purposes (focused on patient healthcare information) and non-clinical purposes (e.g., practice guidelines, patient handouts, etc.). HL7 has plans to develop profiles in the future giving additional guidance on appropriate representation of clinical documents in general, specific types of clinical documents (e.g., Consolidated CDA), and other non-clinical documents (Death Certificate, Medication Registration Information).

FHIR documents are not intended to capture unbounded data sets such as all data stored in an EHR. Rather, consider the [Bulk Data](http://hl7.org/fhir/uv/bulkdata/) specification for use cases requiring access to such data sets.

Note that FHIR defines both this document format (a document bundle containing a Composition resource and potentially other resources) and a [DocumentReference resource](documentreference). FHIR documents are used for documents that are authored and assembled in FHIR, while the DocumentReference resource is for general references to documents (which may include FHIR documents as well as PDFs, CDAs, etc.).

-   [Example discharge summary](document-example-dischargesummary): [XML](document-example-dischargesummary.xml) or [JSON](document-example-dischargesummary.json)

## Document Structure

All documents have the same structure: a [Bundle](bundle) of resources of [type](bundle-definitions#Bundle.type) "document" that has a [Composition](composition) resource as the first resource in the bundle, followed by a series of other resources, referenced from the `Composition` resource, that provide the supporting details for the document. The bundle gathers all the content of the document into a single XML or JSON document which may be signed and managed as required. The resources may include both human readable and computer processable portions. In addition, the bundle may include [CSS stylesheets](http://www.w3.org/Style/CSS/Overview.en.html), [Provenance](provenance) statements including signatures.

The composition resource is the foundation of the clinical document, it:

-   provides identity and its purpose, and sets the context of the document
-   carries key information such as the subject and author, and who attests to the document
-   divides the document up into a series of sections, each with their own narrative

Resources referenced by the Composition as listed below SHALL be included in the bundle when the document is assembled:

<%res-ref-list Composition%>

When these resources reference other resources, the referenced resources SHOULD also be included in the bundle. Omitting referenced resources could compromise the integrity and wholeness of the document, especially when considering that documents have legal retention periods that may be longer than the life of the FHIR server where the reference(s) point to.

In rare cases the referenced resources in Composition can also be contained resources within Composition provided that the resource(s) in question meets the restrictions for the use of contained resources (see [Contained Resources](references#contained) for more information).

The document bundle SHALL include only:

1.  The composition set: the single Composition resource, and the resources it links to
2.  The supporting information: Any resources that are part of the graph of resources that reference or are referenced from the composition set, either directly or indirectly (e.g., recursively in a chain). Such references SHALL use [Reference.reference](references#Reference), [canonical](references#canonical) or a [URI](datatypes#uri) See [Graph-connected Bundles](bundle#graphs) for further details.
3.  Supporting Collateral: A Binary resource containing a stylesheet (as described below)

There are two key identifiers in the document:

-   The document identifier (mandatory) found in _Bundle.identifier_. It is globally unique for this instance of the document, and is never re-used, including for other documents derived from the same composition
-   The Composition identifier (optional) in _Composition.identifier_. It is the same for all documents that are derived from this composition

The document has several dates in it:

-   The document date (mandatory) found in _Bundle.timestamp_. It identifies when the document bundle was assembled from the underlying resources
-   The Composition date (mandatory) found in _Composition.date_. It is when the author wrote the document logically
-   The Attestation dates (optional). These are found in _Composition.attester.time_ and is when the document was witnessed by the attesters. This would usually be at the same time as the composition date or afterwards
-   The Composition last modified time (optional). This is found in _Composition.meta.lastUpdated_ for the composition and is the last date of change of the composition. This must be >= the composition date

If there is a need to have a digital signature on a Document Bundle, this may be accomplished using the rules laid out in the [digital signatures](signatures) page.

Note that the document may be represented in either XML or JSON and interconverted between these or have its character encoding changed, all the while remaining the same document. Any additional documents derived from the same Composition SHALL have a different Bundle.identifier.

### Document Presentation

When the document is presented for human consumption, applications SHOULD present the collated narrative portions in order:

1.  The [subject resource](composition-definitions#Composition.subject) Narrative
2.  The [Composition](composition) resource Narrative
3.  The [section.text](composition-definitions#Composition.section.text) Narratives

If the document is presented in a different order from that given above, it might not represent the original attested content. Implementation Guides may restrict document narrative and display behavior further.

The presentation of the document is called the 'attested content' of the document. The text of resources outside Composition and the subject resource are not considered attested content (e.g., a [Condition](condition) resource). Specifically, the `Composition.attester` attests to the presented form of the document.

The Composition resource narrative should summarize the important parts of the document header that are required to establish clinical context for the document (other than the subject, which is displayed in its own right). To actually build the combined narrative, simply append all the narrative <div> fragments together.

The narrative of the subject resource (typically a Patient), referenced in 'Composition.subject' should clearly identify the subject and typically includes fields like name, identifier, etc.

The [XML Tools reference implementation](downloads#refimpl) includes a XSLT transform that converts an XML document into browser-ready XHTML.

In addition to the [basic style rules about Narratives](narrative#css), which must be followed, a document can reference or contain one or more stylesheets that contain additional styles that apply to the collated narrative. This is done by asserting stylesheet links on the Bundle:

<Bundle xmlns="http://hl7.org/fhir">
  <!-- metadata and type -->
  <link>
    <relation value="stylesheet"/>
    <url value="\[uri\]"/>
  </link>
</Bundle>

The `url` can be an absolute reference to a CSS stylesheet or a relative reference to a Binary resource that carries a CSS stylesheet. Stylesheet references can only refer to a CSS stylesheet - other forms of stylesheet are not acceptable.

Relative (internal) references SHOULD be used for stylesheets, because the viewer may be unable to resolve external content at the time of viewing, due to technical problems or local policy decisions.

Any stylesheet referenced or used SHALL NOT alter the presentation in such a way that it changes the clinical meaning of the content.

Unless otherwise agreed in local trading partner agreements, applications displaying the collated narrative SHOULD use the stylesheets specified by the document (see [security note](security#stylesheet)). Parties entering into a trading agreement to do otherwise should consider the implications this action will have on their long-term scope for document exchange very carefully. If the parties agree to use stylesheets that are not contained in the document, then it may be that they will never be able to share their documents safely in a more general context, such as a regional or national EHR or a global personal health record.

## Document Profiles

[Document profiles](profiling) are used to describe documents for a particular purpose. Document profiles may make rules about:

-   The content of the Composition resource, including
-   The structure of the sections in the composition
-   Which resources are to be included in the bundle along with the resources that are directly referenced in the Document resource

Applications should consider publishing [Capability Statements](capabilitystatement) that identify document types they support. Documents can identify a profile that they conform to by placing a profile identifier in the `Bundle.meta.profile` element - see [Profile Tags](resource#meta) for a discussion of the utility of this.

## Document Handling Obligations

The authors/constructors and processors of Clinical Documents, whether human or software, have obligations that they must satisfy.

### Author/Constructor Obligations

A document constructor is an application that creates a document. An author is a human, organization or device that uses the constructor to create a document. Between them, the constructor and the author may create new content resources and/or assemble already existing content resources while performing their tasks. They also have the following responsibilities:

-   To assure that the document SHALL contain valid composition that conforms to the rules described here and that only links to other valid resources
-   To assure that the content of document SHALL conform to any declared [Profiles](profiling) (see below).
-   Ensure that the attesters are properly aware of the presentation of the document to which they are attesting

### Processor Obligations

A document processor is an application and/or human user that receives documents and extracts data from them or makes decisions because of them. The documents may be received directly from a document constructor, accessed via a document management system or forwarded by a third party. The document processor is responsible for ensuring that received documents are processed and/or rendered in accordance to this specification. A document processor has the obligation to assure that the following rules are followed:

-   When storing/transmitting a document, any method may be used as long as the bundled document can be (re-)assembled with sufficient integrity to validate a digital signature
-   When presenting the narrative of the document, the rules described above SHALL be followed
-   Resources or data from the document may be extracted for additional uses, but such data is no longer considered to be attested by the document author
-   Wherever the data from the document is displayed to a user, there SHOULD always be a way for the user to access a presentation of the original document

In addition to these obligations, document receivers SHOULD carefully track the source of documents for new documents that supersede existing documents, particularly when the documents represent compositions that have been retracted. When documents have been replaced, they SHOULD either withdraw data extracted from superseded documents or warn users when they view the document or data taken from it.

## Document End-Points

There are several different RESTful end-points used when working with documents. The use of the various end-points can best be described by considering the consequences of posting to them:

| **End-Point** | **Type of Content** | **Description** |
| --- | --- | --- |
| [\[baseurl\]/Bundle](bundle) | Document Bundle | This works like a normal end-point for managing a type of resource, but it works with whole document bundles - i.e., a read operation returns a bundle, an update gets a bundle and a search returns a bundle of bundles. Note that if documents are POSTed using a [create](http#create) interaction the Bundle.id will change, but the Bundle.identifier will not. See [Serving Bundles using the RESTful API](bundle#rest) for further comment |
| [\[baseurl\]/Composition](composition) | Composition Resource | The normal end-point for managing composition resources. This can be used while building a document or after breaking a document up into its constituent resources or when using compositions separately from documents |
| [\[baseurl\]/Binary](binary) | Document Bundle | Just store the entire document as a sequence of bytes and return exactly that sequence when requested. There is no way to find content in the /Binary end-point, so usually this would be associated with a [Document Reference](documentreference) so that applications can find and process the document, though this is not required |
| [\[baseurl\]](http#transaction) (e.g., a transaction) | Document Bundle | Ignore the fact that the bundle is a document and process all of the resources that it contains as individual resources. Clients SHOULD not expect that a server that receives a document submitted using this method will be able to reassemble the document exactly. (Even if the server can reassemble the document (see below), the result cannot be expected to be in the same order, etc. Thus a document signature will very likely be invalid.). See [Accepting other Bundle types](http#other-bundles) for further details |

Note: While these end-points are defined for use with document-related resources and document bundles, it is not necessary to use them. Documents may be transferred between systems using any method desired. In addition, servers and/or specifications may define additional [operations](operations) for handling documents beyond the options described above.

### Generating a Document

A client can ask a server to generate a fully bundled document from a composition resource. For details, see [Generate Document Operation](composition-operations).

\[%file newfooter%\]