FHIR DocumentReference

DocumentReference acts as a metadata wrapper that points to a clinical document's location rather than embedding the full content. This separation allows systems to query and retrieve documents efficiently without transmitting large binary payloads.

• Stores a URL reference to the actual document via content.attachment.url
• Supports external storage systems like XDS repositories, cloud buckets, or on-premise file servers
• Enables lazy loading—metadata is fetched first, content only when needed
• Reduces network overhead in high-volume clinical workflows

DocumentReference captures structured context about a document's clinical purpose, making it machine-readable for automated routing and classification systems.

• type: LOINC-coded document kind (e.g., 11506-3 for Progress Note)
• category: High-level grouping such as clinical-note, imaging-report, or discharge-summary
• context: Links to the clinical encounter, facility, and period of service
• custodian: Identifies the organization legally responsible for the document
• authenticator: References the clinician who verified the document's accuracy

The docStatus and status elements track where a document sits in its clinical workflow, which is critical for downstream systems that must distinguish drafts from finalized records.

• current: The document is the latest active version and available for clinical use
• superseded: Replaced by a newer version; retained for audit trail
• entered-in-error: Created mistakenly and should be disregarded
• preliminary: Content is not yet verified; may change before finalization
• amended: The document has been legally corrected post-authentication

Every DocumentReference is anchored to a specific patient and optionally to the clinical encounter that generated it, ensuring accurate record linkage.

• subject: Mandatory reference to the Patient resource—guarantees patient identity binding
• encounter: Optional link to the Encounter resource for visit-level granularity
• author: References the practitioner, device, or organization that created the document
• Supports patient matching algorithms by providing deterministic demographic anchors
• Enables longitudinal record assembly across multiple encounters and facilities

The relatesTo element defines explicit relationships between documents, enabling systems to navigate document lineages and replacement chains.

• replaces: This document supersedes and replaces a prior version
• transforms: This document was derived from another (e.g., a structured report from a dictated note)
• signs: This document provides a digital signature for a referenced document
• appends: This addendum supplements an existing document without altering the original
• Critical for amendment handling and addendum processing workflows

DocumentReference supports multiple content representations through the content array, accommodating diverse clinical document formats.

• Each content element includes a MIME type (contentType) such as application/pdf, text/plain, or application/xml for CDA documents
• data: Inline base64-encoded content for small documents
• url: External reference for large files stored in XDS repositories or cloud storage
• hash: SHA-256 checksum for hash-based deduplication and integrity verification
• Supports multiple renditions of the same document (e.g., PDF and structured XML)