FHIR Bulk Data (a.k.a. Flat FHIR)

Naming things is hard.  Sometimes technologies are given more than one name.  Such is the case with FHIR Bulk Data.  This article is written to explain FHIR Bulk Data at a high level and why it is sometimes called "Flat FHIR".

The FHIR Bulk Data is a draft specification for accessing (you guessed it) FHIR data in bulk.  Unlike regular FHIR, Bulk Data is an asynchronous exchange built atop HTTP.  Some situations where this paradigm may be useful include:
  • When results are very large such as population-level queries.
  • When results are not immediately available and need to be compiled.  HTTP servers and clients usually time out in a minute or two, so any query taking longer than thirty seconds should consider this asynchronous approach.

FHIR Bulk Data responses can represent a population and can therefore be very large. After the initial request is made, an immediate response is returned to the client including the target URL in the response body. The target URL is where the final results can be obtained after they are ready.

When the results are complete, and the client begins to download the contents from the target URL, the results are returned in "Newline Delimited JSON" format.  Newline Delimited JSON is abbreviated as "NDJSON". See http://ndjson.org/ for more information on this specification.  Each line of the NDJSON response is separated by a newline (i.e. "\n").  Each line is still structured data.  It is not a comma-separated-value (CSV) or a fixed-length file.  Those formats are often referred to as "flat files", but they are very different from the structured JSON described in the FHIR Bulk Data proposal.  The fact there is one JSON object, per line is the source of the "Flat FHIR" nickname.

FHIR Bulk Access clients will include the following HTTP headers:
 'Accept': 'application/fhir+ndjson',
 'Prefer': 'respond-async',

To avoid confusion, we recommend the term FHIR Bulk Data over the term Flat FHIR.  Hopefully this short article will help clear things up too.

Additional Resources:

  • FHIR Bulk Data Transfer Privacy and Security Concerns -


Popular posts from this blog

A Punchlist for Consumer Directed Exchange Success

Why Transparent Health Was Created