Skip to main content
v2026.11,986 entries · CC-BY 4.0

HL7 FHIR Binary and Media Resources: Attachments and R5 Changes

How HL7 FHIR Binary and Media resources handle raw PDFs, C-CDA XML, DICOM, and clinical multimedia, link to DocumentReference, and transition in FHIR R5.

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..1 code): The MIME type of the underlying byte payload (bound to BCP 13 / IETF RFC 2046 MIME codes), such as application/pdf, application/hl7-v3+xml, text/plain, image/jpeg, application/dicom, or audio/mpeg.
  • securityContext (0..1 Reference(Any)): A reference to another FHIR resource (typically the indexing DocumentReference, DiagnosticReport, or Patient) that supplies the privacy, consent, and access-control context for the binary bytes.
  • data (0..1 base64Binary): 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+json or application/fhir+xml): The server returns a JSON or XML Binary resource 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 with Content-Type set 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:

  1. DocumentReference: Designed around IHE XDS/MHD principles to index clinical documents (PDFs, C-CDA XML, scanned forms, and clinical notes).
  2. Media (FHIR R4): Designed to wrap clinical photographs (wound care, dermatology, retinal fundus images), audio dictations, and video clips, adding media-specific elements such as Media.Modality, Media.view, Media.height, Media.width, Media.frames, and Media.duration alongside Media.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 Attachment data 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) and Observation.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.

Follow CASRAI

Research-administration guidance, standards updates and independent tool reviews.

Ask CASRAI · full access

Ask about HL7 FHIR Binary and Media Resources: Attachments and R5 Changes

Full access: large monthly usage, up to 10 source passages behind each answer, and MCP and API access for Claude Code, Codex and other CLIs. Cancel any time.

An AI assistant for research: funder rules, compliance, methods and publishing. It links the sources behind its answers and labels answers that come from a web search.

Answers draw on CASRAI's guides and dictionary plus the federal and funder documents we index: Federal Register, Grants.gov, Regulations.gov and UKRI.

Works on this site and inside Claude, Cursor and the AI tools you already use.

Everything CASRAI publishes — this page, the dictionary, the guides and the news — stays open to read, with no account and no card.

Referenced across the research world

University of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logoUniversity of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logo
  • University of Cambridge logo
  • Columbia University logo
  • Crossref logo
  • University of Edinburgh logo
  • Harvard University logo
  • University of Oxford logo
  • Princeton University logo
  • Stanford School of Medicine logo
  • University College London logo
  • ORCID logo

View CASRAI adoption →