FHIR DocumentReference Resource: US Core Clinical Notes, LOINC Codes, and DiagnosticReport Comparison

The FHIR DocumentReference resource is the metadata indexing resource in HL7 Fast Healthcare Interoperability Resources (FHIR) used to catalog, search, and retrieve clinical documents, unstructured narrative notes, C-CDA summaries, and scanned PDFs. Under the ONC/ASTP 21st Century Cures Act regulations and the US Core Implementation Guide, DocumentReference serves as the primary mechanism for exchanging clinical notes across electronic health record (EHR) APIs and health information exchanges.

What Is the FHIR DocumentReference Resource?

In HL7 FHIR R4 (https://hl7.org/fhir/R4/documentreference.html), a DocumentReference does not store narrative clinical text directly in top-level string fields. Instead, it acts as a searchable metadata envelope—modeled on the IHE Cross-Enterprise Document Sharing (XDS.b) registry entry—that describes a document’s provenance, clinical context, and LOINC classification while pointing to the underlying byte payload via content.attachment.

Key elements required or marked as Must Support in the US Core DocumentReference Profile include:

• status (1..1): Tracks the lifecycle state of the metadata reference itself (current, superseded, or entered-in-error).
• docStatus (0..1): Tracks the clinical completion state of the underlying document (preliminary, final, amended, or entered-in-error).
• type (1..1): Identifies the specific clinical note type using LOINC codes (for example, 11506-3 for a Progress Note or 18842-5 for a Discharge Summary).
• category (1..*): Categorizes the document; US Core mandates support for the code clinical-note from http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category.
• content.attachment (1..*): Contains the MIME type (contentType, such as text/plain, text/html, application/pdf, or application/xml for C-CDA) and either a dereferenceable URL (attachment.url pointing to a FHIR Binary endpoint) or inline Base64-encoded bytes (attachment.data).
• context.encounter and context.period: Links the clinical note to the corresponding FHIR Encounter and clinical service timestamps.

When Should You Use FHIR DocumentReference vs DiagnosticReport?

A central architectural question in clinical data engineering is whether a clinical report belongs in DocumentReference or DiagnosticReport (https://hl7.org/fhir/R4/diagnosticreport.html). While both resources can carry narrative text or PDF attachments, their semantic scope and structural schemas differ:

Dimension	DocumentReference	DiagnosticReport
Primary Clinical Scope	Provider-authored clinical notes (H&P, Progress, Consultation, Discharge, Procedure notes), C-CDA documents, and patient-uploaded PDFs.	Findings and interpretations of diagnostic investigations (Laboratory, Radiology, Pathology, and Cardiology studies).
Discrete Result Linking	Does not link to discrete atomic Observation resources.	Links directly to discrete numeric or coded Observation resources via DiagnosticReport.result.
Attachment Element	DocumentReference.content[].attachment (mandatory 1..*).	DiagnosticReport.presentedForm[] (optional 0..*).
US Core Category Codes	clinical-note	LP29684-5 (Radiology), LP29708-2 (Cardiology), LP7839-6 (Pathology), LAB (Laboratory).

The US Core Clinical Notes Dual-Exposure Rule

Because historical EHR architectures vary in how they store narrative radiology, pathology, and cardiology reports—some storing them as scanned documents and others as diagnostic result records—the HL7 US Core Clinical Notes Guidance (https://hl7.org/fhir/us/core/clinical-notes.html) establishes a strict interoperability rule:

• five Core Clinical Note Types in DocumentReference: EHR servers must expose Consultation Notes (11488-4), Discharge Summaries (18842-5), History & Physical Notes (34117-2), Procedure Notes (28570-0), and Progress Notes (11506-3) via DocumentReference.
• Three Diagnostic Report Categories in DiagnosticReport: EHR servers must expose Cardiology (LP29708-2), Pathology (LP7839-6), and Radiology (LP29684-5) narratives via DiagnosticReport.
• Dual Exposure for Narrative/Scanned Reports: When a diagnostic report is stored as an unstructured narrative or scanned PDF, US Core encourages (and many certified EHRs implement) exposing the same underlying Binary URL through both DiagnosticReport.presentedForm.url and DocumentReference.content.attachment.url so client applications never miss critical diagnostic narratives.

How Do You Retrieve Clinical Notes via FHIR DocumentReference?

Retrieving unstructured clinical notes for clinical NLP pipelines (such as ClinicalBERT phenotyping) or patient record aggregation follows a two-step RESTful pattern:

1. Query Metadata References: Search DocumentReference by patient, category, and optional LOINC type or date range:

   GET [base]/DocumentReference?patient=12345&category=clinical-note&type=http://loinc.org|11506-3

2. Dereference or Decode the Attachment: Inspect content[0].attachment in each returned resource:
   • If attachment.data is populated, Base64-decode the string directly into UTF-8 text or binary PDF bytes.
   • If attachment.url points to a relative or absolute Binary/[id] endpoint, execute an authenticated GET [base]/Binary/[id] request with an HTTP Accept header matching attachment.contentType (e.g., Accept: text/plain or Accept: application/pdf) to retrieve the raw clinical note.

Frequently Asked Questions

What is the FHIR DocumentReference resource?

The FHIR DocumentReference resource is a metadata index that describes the type, author, encounter context, and completion status of a clinical document or narrative note while providing a pointer (content.attachment.url) or inline Base64 payload (content.attachment.data) for the actual document content.

When should you use FHIR DocumentReference vs DiagnosticReport?

Use DocumentReference for clinician-authored clinical notes (Progress Notes, Discharge Summaries, History & Physicals, Consultation Notes, and Procedure Notes) and C-CDA summaries, and use DiagnosticReport for laboratory, radiology, pathology, and cardiology studies that combine discrete Observation results with narrative interpretations.

How do you retrieve clinical notes via FHIR DocumentReference?

First query GET /DocumentReference?patient=[id]&category=clinical-note to retrieve the metadata bundle, then either Base64-decode content.attachment.data or send an authenticated GET request to the Binary/[id] URL specified in content.attachment.url.