Every FHIR team has implicit conventions about how Bundles get formatted. Every team also has "why does that file look different" conversations in code review. The gap between the two is time spent debating instead of shipping. Writing the conventions down is a one-afternoon investment that pays off every review afterward. The site's FHIR JSON tidier is one implementation of a convention; the document that pins it down is your team's. For the wider FHIR framing, the FHIR reference shelf has more.

The Ten Conventions To Write Down

• Indent width (2 or 4 spaces — pick one)
• Line-length cap (80, 100, 120, 160, or unlimited)
• Newline convention (LF only, final newline required)
• Key ordering (preserve original or canonical sort)
• Array ordering (never reorder Bundle.entry, Observation.component, etc.)
• Escape rules (do not escape /, preserve UTF-8 vs unicode form)
• Trailing comma policy (never — invalid JSON)
• File extension (.json — never .txt or .bundle)
• Repository formatter (the exact tool everyone uses)
• Pre-commit enforcement (yes or no)

Ten decisions. Each takes five minutes to make. Together they end most of the formatting debates.

For the diff-friendliness side, diff-friendly formatting for Bundles under version control is the entry.

Write It Where Reviewers Can Find It

• A CONTRIBUTING.md in the repository root
• A section in the team's engineering wiki
• A pinned message in the FHIR-related channel

Not in a design doc from three quarters ago. Not in a Slack thread. Somewhere that new engineers see on day one.

Encode In Editor Config

• .editorconfig in the repository root
• Language-server settings for the formatter tool
• IDE settings for the specific extensions your team uses

The right pattern is that unformatted commits are impossible because the editor formats on save.

Encode In Pre-Commit

A pre-commit hook that runs the formatter and rejects on mismatch is the mechanism that makes conventions load-bearing. Without it, drift accumulates.

The hook takes one afternoon to set up. It saves a category of review conversations forever.

Encode In CI

Redundant with pre-commit but useful for shared repositories where contributors may not run the hooks locally. CI rejects unformatted PRs. Same idea, different enforcement point.

For the line-length choices behind the "cap" convention, line-length choices that survive code review is the entry.

Handle Migration Deliberately

Existing repositories usually have inconsistent formatting. Fixing it retroactively:

• Land one big formatter-run commit that touches every Bundle
• Add the pre-commit hook in the same PR
• Communicate to the team so nobody rebases across the reformat

That reformat commit will show up in git blame for every line. Some teams tag it as blame-ignore; others live with it.

Escape-Sequence Rules Deserve A Bullet

• Do not escape forward slashes
• Preserve UTF-8 vs unicode-escape form
• Verify surrogate pairs roundtrip

Each is a common formatter difference; each is worth pinning down. For the deep dive, the escape sequences pretty-printers get wrong is the entry.

Reference Rules Deserve A Bullet

• Formatter must not touch Reference.reference, Reference.identifier, fullUrl, or system URLs
• Verify with a byte-comparison test after formatting

Reference integrity is the load-bearing part. Everything else is aesthetic.

Review The Conventions Yearly

Team preferences shift. Tools evolve. Line-length caps that made sense on 15" monitors do not make sense on 27" monitors.

Schedule a yearly review. Update the document. Retire conventions that stopped mattering.

The Short Version

Ten decisions written down and enforced beat implicit conventions every time. Encode in editor config, pre-commit, and CI. Handle migration deliberately. Review yearly. The tidier is one implementation; the document is what makes it your team's.

Sources

• HL7 canonical FHIR JSON representation specification - HL7 canonical FHIR JSON representation specification