Written and maintained by CASRAI Editorial Board
Published
On this page
While most HL7 FHIR R4 resources represent structured clinical concepts using JSON or XML element trees, clinical care and biomedical research routinely generate unstructured or non-FHIR byte streams—including PDF pathology reports, HL7 C-CDA XML documents, JPEG dermatology photographs, audio recordings, and DICOM waveforms. To store and exchange these raw payloads over the same RESTful API, FHIR provides the Binary resource alongside clinical indexing wrappers such as DocumentReference, DiagnosticReport, and (in FHIR R4) Media.
How Does the HL7 FHIR Binary Resource Store Raw PDFs, C-CDA XML, DICOM, and Multimedia?
The FHIR Binary resource is intentionally minimalist: unlike standard domain resources, it does not inherit DomainResource narrative text (`text`), contained resources, or arbitrary extensions. Instead, it consists of three core elements:
contentType(1..1code): The MIME type of the underlying byte payload (bound to BCP 13 / IETF RFC 2046 MIME codes), such asapplication/pdf,application/hl7-v3+xml,text/plain,image/jpeg,application/dicom, oraudio/mpeg.securityContext(0..1Reference(Any)): A reference to another FHIR resource (typically the indexingDocumentReference,DiagnosticReport, orPatient) that supplies the privacy, consent, and access-control context for the binary bytes.data(0..1base64Binary): The raw payload encoded as a Base64 string when serialized inside a JSON or XML FHIR wrapper.
HTTP Accept Header Content Negotiation on the Binary Endpoint
A critical performance feature of any compliant FHIR server is how GET [base]/Binary/[id] responds based on the client’s HTTP Accept header:
- FHIR Wrapper Mode (
Accept: application/fhir+jsonorapplication/fhir+xml): The server returns a JSON or XMLBinaryresource containing `resourceType: “Binary”`, `id`, `contentType`, and the Base64-encoded `data` string (which inflates payload size by approximately 33%). - Native Byte-Stream Mode (
Accept: application/pdf,image/jpeg, or*/*): The server strips the FHIR JSON wrapper and streams the raw native bytes directly in the HTTP response body withContent-Typeset to the stored MIME type, avoiding Base64 encoding/decoding overhead for large documents, audio streams, or imaging files.
How Do DocumentReference and DiagnosticReport Reference a Binary vs. Inline Base64 Data?
Because a standalone Binary resource has no search parameters for patient identity, encounter, author, or LOINC document category, clients never discover clinical files by searching `GET [base]/Binary` directly. Instead, clinical systems index unstructured files using the Attachment data type inside DocumentReference.content.attachment or DiagnosticReport.presentedForm:
| Attachment Pattern | Populated Attachment Elements | Architectural Trade-Offs & SMART on FHIR Governance |
|---|---|---|
Referenced Binary URL (Recommended for large files) |
attachment.contentType, attachment.url (e.g., Binary/doc-9812), attachment.size, attachment.hash (SHA-1) |
Keeps search Bundles lightweight when querying DocumentReference?patient=...; client fetches only the specific Binary files needed. |
| Inline Base64 Data (Small notes or Transaction Bundles) | attachment.contentType, attachment.data (Base64 string) |
Self-contained in a single HTTP request, but bloats search responses if returned across dozens of clinical notes at once. |
SMART on FHIR Scope Enforcement and securityContext
Under ONC 21st Century Cures Act and US Core rules, when a patient or clinician app searches for clinical notes via DocumentReference and follows an attachment.url pointing to [base]/Binary/[id], the authorization server must verify that the caller’s OAuth 2.0 bearer token (`patient/DocumentReference.read` or `patient/Binary.read`) permits access to that specific patient’s file. Populating Binary.securityContext with a reference to the parent DocumentReference or Patient allows the FHIR server to evaluate compartment membership and patient-level access control without inspecting the opaque binary bytes.
Why Did HL7 FHIR R5 Deprecate the Media Resource and Merge It into DocumentReference?
In FHIR DSTU2, STU3, and R4, HL7 maintained two overlapping resources for indexing non-text clinical files:
DocumentReference: Designed around IHE XDS/MHD principles to index clinical documents (PDFs, C-CDA XML, scanned forms, and clinical notes).Media(FHIR R4): Designed to wrap clinical photographs (wound care, dermatology, retinal fundus images), audio dictations, and video clips, adding media-specific elements such asMedia.Modality,Media.view,Media.height,Media.width,Media.frames, andMedia.durationalongsideMedia.content(`Attachment`).
In practice, implementers faced persistent ambiguity over whether a clinical photograph, an endoscopic video clip, or a scanned waveform belonged in Media, DocumentReference, or Observation. In HL7 FHIR R5, theHL7 Orders and Observations and Structured Documents work groups removed the standalone Media resource entirely:
- Image, audio, and video dimension attributes (`height`, `width`, `frames`, `duration`, `pages`) were promoted directly onto the core
Attachmentdata type so any resource using `Attachment` can describe multimedia attributes natively. - Multimedia cataloging and discovery were consolidated into
DocumentReference(for standalone indexed media files and documents) andObservation.valueAttachment(when a photograph, audio clip, or waveform represents the direct result of a clinical observation).
Frequently Asked Questions
When should DICOM medical imaging use FHIR ImagingStudy instead of Binary and DocumentReference?
Full multi-slice diagnostic radiology studies (CT, MRI, PET, and ultrasound series containing hundreds of DICOM SOP Instances) should be indexed using the FHIR ImagingStudy resource and retrieved via native DICOMweb (`WADO-RS`) endpoints rather than wrapping every slice as a FHIR Binary. Binary and DocumentReference are used primarily for single key-image JPEG/PNG snapshots, PDF radiology reports, or IHE XDS.b / MHD document exchange.
How does Attachment.hash verify file integrity when retrieving a FHIR Binary?
In FHIR R4, Attachment.hash is a Base64-encoded SHA-1 hash calculated over the raw unencoded binary bytes (prior to Base64 serialization). When a clinical data pipeline downloads the target Binary resource, recomputing the SHA-1 digest of the received byte stream and comparing it against DocumentReference.content.attachment.hash verifies that the file was not truncated or corrupted in transit.
Can a FHIR Binary resource be created using a direct HTTP POST of raw bytes?
Yes. The FHIR REST specification allows a client to send a standard HTTP POST [base]/Binary where the request body is the raw binary file itself (for example, a raw PDF byte stream) and the HTTP Content-Type header specifies its MIME type (application/pdf), optionally passing the security context via the X-Security-Context HTTP header.







