Every FHIR deployment eventually has a first attachment incident. A workflow ships that lets clinicians upload a scanned document as an Observation.valueAttachment, or that stores clinical PDFs inline in DocumentReference. The workflow works fine for a month, and then the storage graph tilts sharply upward and someone in finance asks what changed. What changed is that attachments arrived.
Attachments are the storage line that ambushes deployments most often. For related walkthroughs, additional FHIR walkthroughs collects the surrounding material.
Why the Ambush Is So Sharp
An average Observation is around three kilobytes. An Observation with an inline PDF attachment carries the base three kilobytes plus the attachment payload. A two-megabyte PDF makes the resource seven hundred times larger than its non-attachment sibling.
Multiply that across a workflow that generates a few hundred attachments per day, and the storage curve gets a new slope overnight. A pass through the site's FHIR storage bill projector can bracket the impact when attachment volume is entered explicitly.
Where Attachments Actually Land
FHIR supports three placements for attachment data:
- Inline base64 in the resource itself (
Attachment.data). - External reference to a URL (
Attachment.url). - A binary resource pointed at by the URL.
Each pattern has a storage implication. Inline base64 lands in the FHIR database, inflates the resource, and compounds with history. External references keep the attachment out of the FHIR store but require the external store to be reliable. Binary resources sit in the FHIR store but are usually stored on separate tables or object storage.
The Inline Base64 Trap
Inline base64 is the most convenient pattern to implement and the most expensive to run. Every resource update duplicates the attachment payload into a new history row. A resource with a two-megabyte inline attachment and five updates generates ten megabytes of history from one attachment.
For the specific interaction with history growth, history table vs current state: doubling your storage bill quietly covers the shape.
The External Reference Pattern
The disciplined pattern is to store attachments on object storage and reference them from FHIR resources via Attachment.url. Object storage is cheaper per gigabyte than FHIR database storage, and the reference does not inflate the resource.
The trade is operational: the object store has to be highly available, versioned, and secured with access controls that match the FHIR store. Deployments that skip the operational work discover it during an incident.
DocumentReference Is a Wrapper
DocumentReference is often used to wrap a clinical document. Under the hood the document lives in a Binary resource or on object storage. The DocumentReference itself is small; the referenced document is not.
Sizing plans should track DocumentReference count and average document size as separate line items. The count grows linearly with clinical workflow; the size grows with the type of document being stored. For the resource-level footprint framing, per-resource storage footprint: what actually takes space covers the base numbers.
Tiering Attachments Explicitly
Cold storage for attachments is almost always the right choice at scale. Recent attachments live on standard object storage; older ones migrate to lower-cost tiers. Access patterns for attachments favor this: reads are rare after the first thirty days.
For the tiering framing, cold vs hot FHIR data: tiering strategies that hold up is the accompanying reference.
The Explicit Attachment Policy
Every FHIR deployment should carry an explicit attachment policy. Which placement is allowed. What size limits are enforced. What tiering rules apply. What retention window is honored.
For the wider hidden-cost framing, the FHIR storage costs you forgot to budget collects the missing lines. The attachment policy is the shortest path to preventing an ambush that would otherwise arrive with the next quarter's invoice.
Sources
- HL7 FHIR core specification of the Attachment datatype - HL7 FHIR core specification of the Attachment datatype covering inline vs URL placement