The compact FHIR Bundle that arrived on the wire is optimized for bytes. That is the right shape for transport. It is the wrong shape for every human who has to read it. Every incident where a developer opens a Bundle in a text editor and squints for ten minutes before finding the offending element is one where a pretty-printed version would have saved that time. The site's FHIR JSON tidier is the paste-in tool for exactly this. For the wider setting, the conecion FHIR library has more.

Where Human Time Actually Gets Spent

• Diagnosing a validation failure — you need to see the element the pointer references
• Reviewing a change to a stored Bundle — you need to see what changed
• Understanding a payload during onboarding — you need to see the shape
• Pairing with a colleague on an incident — you need to point at fields together
• Writing an integration test with a fixture — you need to construct a readable payload

Every one of these tasks is faster with formatted JSON. Every one is achingly slow with a single-line 40kb blob.

The Cost Adds Up Faster Than It Looks

Ten minutes per incident. Five incidents per week per developer. Ten developers on a team. That is roughly 40 hours per week of pure formatting friction across a typical FHIR team.

Every hour of it is preventable with a formatter that runs on paste-in.

What A Good Formatter Does

• Indents each nested level with a consistent width
• Puts one element per line for readability
• Preserves key ordering (unless explicitly asked to sort)
• Preserves array ordering (that is often load-bearing)
• Handles escape sequences correctly

The FHIR tidier at /playground/tidy-fhir-json/ does each of these. For the deep dive on ordering, keeping resource order stable across pretty-printing is the entry.

The Diff Case

A formatted Bundle produces a readable diff against a previous formatted version. An unformatted Bundle produces a diff that is one giant line marked changed. Version control on Bundles depends on formatting.

For the diff-specific patterns, diff-friendly formatting for Bundles under version control is the entry.

The Onboarding Case

New engineers reading their first FHIR payload should not have to hunt for elements. A formatted payload teaches the shape. An unformatted one teaches learned helplessness — the response is "it works, don't look at it."

Format from day one and your onboarding notes get shorter.

The Support Case

Support tickets with unformatted payloads take twice as long to triage. The engineer opens the payload, formats it in their head, then hunts. Formatting on paste-in is a small tool that pays for itself the first hour.

The Wire Case Still Applies

Nothing about pretty-printing changes what goes on the wire. Servers and clients still exchange compact JSON. The formatter is a tool for humans reading captured payloads, not a change to the protocol.

For the memory implications of formatting very large Bundles, pretty-printing large Bundles without blowing memory is the entry.

Team Conventions

Every team has an implicit convention (two-space indent, sort keys, sort array entries by some field). The teams that write the convention down have fewer "what did that Bundle look like when we deployed it" incidents.

For the conventions checklist, formatting conventions your team should pin down is the entry.

The Short Version

Unformatted JSON is right for the wire. Formatted JSON is right for humans. The gap between them costs hours per week. Format at every point a human reads the payload — in diffs, in support tools, in tests, in onboarding materials. The tidier does the mechanical work; the conventions live with your team.

Sources

• HL7 canonical FHIR Bundle resource specification - HL7 canonical FHIR Bundle resource specification