DocumentReference — Clinical document pointer
PDF report, clinical photo, CDA, ePub: DocumentReference is the FHIR pointer to any clinical document. The IHE XDS gateway in REST mode.
Purpose
DocumentReference is the metadata of a clinical document stored somewhere (HTTP URL, inline base64, IHE XDS). It carries type (LOINC), category, author, authenticator, custodian, context (Encounter, Period), links to previous documents (replaces, appends, signs, transforms), and the effective pointer to the content (content[].attachment).
Key fields
| Field | Type | Cardinality | Role |
|---|---|---|---|
identifier | Identifier[] | 0..* | External identifiers. |
version | string | 0..1 | Business version. |
basedOn | Reference(Any)[] | 0..* | Parent requests. |
status | code | 1..1 | Mandatory. current, superseded, entered-in-error. |
docStatus | code | 0..1 | Editorial state: preliminary, final, amended, entered-in-error. |
modality | CodeableConcept[] | 0..* | Production modality. |
type | CodeableConcept | 0..1 | Document type (LOINC). |
category | CodeableConcept[] | 0..* | High-level category (clinical-note, lab, radiology…). |
subject | Reference(...) | 0..1 | Patient or other subject. |
context | Reference(...)[] | 0..* | Contexts (Encounter, EpisodeOfCare, Period). |
event | CodeableReference[] | 0..* | Documented events. |
bodySite | CodeableReference[] | 0..* | Anatomical sites. |
facilityType | CodeableConcept | 0..1 | Facility type. |
practiceSetting | CodeableConcept | 0..1 | Practice setting. |
period | Period | 0..1 | Covered period. |
date | instant | 0..1 | Entry date. |
author | Reference(...)[] | 0..* | Author(s). |
attester | BackboneElement[] | 0..* | Attesters. |
custodian | Reference(Organization) | 0..1 | Custodian organization. |
relatesTo | BackboneElement[] | 0..* | Document links: replaces, transforms, signs, appends. |
description | markdown | 0..1 | Description. |
securityLabel | CodeableConcept[] | 0..* | Confidentiality labels. |
content | BackboneElement[] | 1..* | Mandatory. Attachment(s) + IHE format(s). |
JSON example
Final chest CT report that appends a preliminary report:
{
"resourceType": "DocumentReference",
"id": "dr-radio-report-001",
"identifier": [{
"system": "urn:oid:1.2.34",
"value": "DR-2026-RADIO-001"
}],
"status": "current",
"docStatus": "final",
"type": {
"coding": [{
"system": "http://loinc.org",
"code": "11503-0",
"display": "Medical records"
}, {
"system": "http://loinc.org",
"code": "59776-5",
"display": "Procedure note"
}]
},
"category": [{
"coding": [{
"system": "http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category",
"code": "clinical-note"
}]
}],
"subject": { "reference": "Patient/doe-john" },
"date": "2026-05-15T16:00:00+02:00",
"author": [
{ "reference": "Practitioner/dr-radiologist-bernard" }
],
"authenticator": { "reference": "Practitioner/dr-radiologist-bernard" },
"custodian": { "reference": "Organization/radiology-dept" },
"relatesTo": [{
"code": {
"coding": [{
"system": "http://hl7.org/fhir/document-relationship-type",
"code": "appends"
}]
},
"target": { "reference": "DocumentReference/dr-radio-prelim-001" }
}],
"description": "Chest CT report 2026-05-15, pulmonary embolism excluded",
"content": [{
"attachment": {
"contentType": "application/pdf",
"language": "en-US",
"url": "https://docs.hospital-1.example.org/reports/2026/05/RADIO-001.pdf",
"size": 245678,
"hash": "...",
"title": "Chest CT report",
"creation": "2026-05-15T15:45:00+02:00"
},
"format": {
"system": "http://ihe.net/fhir/ValueSet/IHE.FormatCode.codesystem",
"code": "urn:ihe:rad:TEXT"
}
}],
"context": [
{ "reference": "Encounter/enc-radio-2026-05-15" }
]
}Common pitfalls
- Confusing
statusanddocStatus— status = resource lifecycle (current/superseded), docStatus = editorial document state (preliminary/final). - No
category— makes search difficult: querying all radiology reports for a patient without category is slow. - Inline base64 for large files — an inline 5 MB PDF bloats the resource. Prefer external URL + Binary.
- Missing
relatesTo— without a link to the previous version, the editorial history is lost. - No
authenticator— without a document signer, reduced legal value (signed=false).
Related resources
- Composition — FHIR-native document vs external document.
- Binary — referenced raw content.
- DiagnosticReport — can contain a DocumentReference in
presentedForm. - Encounter — context.
- Consent — signed PDF.