View raw Markdown
type: resourceresource: DocumentReference

DocumentReference

Introduction

Scope and Usage

Note to Balloters: To ensure this resource is ready for Normative status, we are seeking ballot comment on the substantive content. The key changes made since R5 include:

  • Addition of the following elements:

  • DocumentReference.related

  • Updates to the following elements:

  • DocumentReference.bodySite has been changed to DocumentReference.bodyStructure

A DocumentReference resource is used to index a document, clinical note, and other binary objects such as a photo, video, or audio recording, including those resulting from diagnostic or care provision procedures, to make them available to a healthcare system. A document is some sequence of bytes that is identifiable, establishes its own context (e.g., what subject, author, etc. can be presented to the user), and has defined update management. The DocumentReference resource can be used with any document format that has a recognized mime type and that conforms to this definition.

Typically, DocumentReference resources are used in document indexing systems, such as IHE XDS and as profiled in IHE Mobile Access to Health Documents.

DocumentReference contains metadata, inline content or direct references to documents such as:

Boundaries and Relationships

This resource captures data that might not be in FHIR format. The document can be any object (e.g. file), and is not limited to the formal HL7 definitions of Document. This resource may be a report with unstructured text or a report that is not expressed in a DiagnosticReport. The DiagnosticReport is appropriate to reflect a set of discrete results (Observations) and associated contextual details for a specific report, and within those results any further structure within the Observation instances. The DocumentReference resource may be an Observation whose value is audio, video or image data. This resource is the preferred representation of such forms of information as it exposes the metadata relevant for interpreting the information. There is some overlap potential such as a scan of a CBC report that can either be referenced by way of a DocumentReference, or included in a DiagnosticReport as a presentedForm together with the structured, discrete data. In some cases, a single in-system entity may be represented as both resources if they provide relevant metadata or workflow-specific attributes. Specific implementation guides would further clarify which approach is more appropriate.

This resource is able to contain medical images in a DICOM format. These images may also be made accessible through an ImagingStudy or ImagingSelection resource, which provides a direct reference to the image to a WADO-RS server. For such images, the WADO-RS framework is a preferred method for representing the images - the WADO-RS service may include rendering the image with annotations and display parameters from an associated DICOM presentation state, for instance. On the other hand, the DocumentReference resource allows for a robust transfer of an image across boundaries where the WADO-RS service is not available. For this reason, medical images can also be represented in a DocumentReference resource, but the DocumentReference.content.attachment.url should provide a reference to a source WADO-RS service for the image.

FHIR defines both a document format and this document reference. FHIR documents are for documents that are authored and assembled in FHIR. DocumentReference is intended for general references to any type of media file including assembled documents.

The document that is a target of the reference can be a reference to a FHIR document served by another server, or the target can be stored in the special FHIR Binary Resource, or the target can be stored on some other server system. The document reference is also able to address documents that are retrieved by a service call such as an XDS.b RetrieveDocumentSet, or a DICOM WADO-RS exchange, or an HL7 V2 message query - though the way each of these service calls works must be specified in some external standard or other documentation.

A DocumentReference describes some other document. This means that there are two sets of provenance information relevant here: the provenance of the document, and the provenance of the document reference. Sometimes, the provenance information is closely related, as when the document producer also produces the document reference, but in other workflows, the document reference is generated later by other actors. In the DocumentReference resource, the meta content refers to the provenance of the reference itself, while the content described below concerns the document it references. Like all resources, there is overlap between the information in the resource directly, and in the general Provenance resource. This is discussed as part of the description of the Provenance resource.

Notes

Implementation Notes

StructureDefinition

Elements (Simplified)

Mappings

Implementation Guide

implementationguide-DocumentReference-core.xml

<?xml version="1.0" encoding="UTF-8"?>

<ImplementationGuide xmlns="http://hl7.org/fhir" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://hl7.org/fhir ../../publish/ImplementationGuide.xsd">
  <id value="DocumentReference-core"/>
  <identifier>
    <system value="urn:ietf:rfc:3986"/>
    <value value="urn:oid:2.16.840.1.113883.4.642.30.4"/>
  </identifier>
  <version value="0.01"/>
  <name value="DocumentReferenceHL7Extensions"/>
  <title value="Document Reference  H L7  Extensions"/>
  <status value="draft"/>
  <date value="2022-03-16T10:00:00+10:00"/>
  <publisher value="Health Level Seven, Inc. - OO WG"/>
  <description value="Defines common extensions used with or related to the DocumentReference resource"/>
</ImplementationGuide>

Operations

Full Operations

Resource Packs

list-DocumentReference-packs.xml

<?xml version="1.0" encoding="UTF-8"?>

<List xmlns="http://hl7.org/fhir" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://hl7.org/fhir ../../publish/List.xsd">
  <id value="DocumentReference-packs"/>
  <status value="current"/>
  <mode value="working"/>
  <entry>
    <item>
      <reference value="ImplementationGuide/DocumentReference-core"/>
    </item>
  </entry>
</List>

Search Parameters

Full Search Parameters

Examples

Full Examples

Mapping Exceptions

documentreference-event-mapping-exceptions.xml

Divergent Elements

Unknown does not represent "other" - one of the defined statuses must apply. Unknown is used when the authoring system is not sure what the current status is. | resource=This is the status of the DocumentReference object, which might be independent from the docStatus element.

This element is labeled as a modifier because the status contains the codes that mark the document or reference as not currently valid.

The recorded date is NOT intended to be the same as a database.createdTimestamp - that would be captured as part of resource.meta or possibly Provenance.

It is possible for the same event to be disclosed to different systems at different times. E.g. a patient might tell two different clinicians about a historical event at different visits. If the disclosure is from the patient rather than record transfer from clinician A to B, the recorded date would be the date each respective clinician put the data in their record. If the data flowed from clinician A to B, the recorded date would remain the recorded date as initially set in clinician A's system. | resource=Referencing/indexing time is used for tracking, organizing versions and searching. Provide the most precise timestamp available.

Unmapped Elements

documentreference-fivews-mapping-exceptions.xml

Divergent Elements

Unmapped Elements