Conecion

Practical FHIR notes on SDC form builders and terminology server implementations for healthcare integration teams.

Keeping Resource Order Stable Across Pretty-Printing

Pretty-printing a Bundle should change the whitespace and nothing else. That is the rule. Formatters that helpfully reorder keys, entries, or arrays are not helpful — they turn a formatting operation into a semantic change, and every downstream consumer that cared about the original order sees behavior drift. The site's FHIR JSON tidier preserves order by default and offers an explicit sort option when you want one. For the wider FHIR framing, the conecion healthcare data hub has more.

Two Kinds Of Order

  • Key order — the order of fields inside a resource
  • Array order — the order of entries in an array

Key order is not semantically load-bearing per the JSON spec, but it matters for readability and diffs. Array order is semantically load-bearing in FHIR — Bundle.entry order matters for many workflows, Observation.component order can matter for panels, Contract.term order preserves legal meaning.

The Default Rule

Pretty-print without reordering anything. Whitespace changes; positions do not.

For the diff mechanic that depends on this, diff-friendly formatting for Bundles under version control is the entry.

When Explicit Sort Is Useful

  • Comparing two Bundles that arrived from different producers — sort by resourceType and id for canonical form
  • Producing a normalized snapshot for hashing or signing
  • Building a fixture that should be stable across generation runs

Every one of these is a case where the sort is an explicit, documented step. Not a formatter default.

Bundle.entry Order Is Load-Bearing

Servers process transaction Bundles in the order the client specifies. Search-result Bundles carry an order that matches the sort parameter. Message Bundles are strictly ordered. Reordering Bundle.entry silently is one of the more consequential formatter bugs.

For the reference implications, keeping references intact after pretty-printing is the entry.

Component Order Matters On Some Resources

  • Observation.component — blood pressure has systolic first then diastolic by convention
  • Contract.term — order preserves legal semantics
  • Composition.section — order defines document flow
  • Questionnaire.item — order defines UI rendering

Reordering these produces payloads that validate but present differently.

Sort By Key With Care

Sorting keys alphabetically produces a canonical form useful for hashing but jarring to read. resourceType conventionally appears first, not sorted between note and subject. A key sorter that respects convention (resourceType, id, then alphabetical rest) reads better.

The tidier offers a "canonical sort" option that follows this convention. For the base pattern, why an unformatted Bundle costs you more time than a formatted one covers the format-first argument.

Signing And Hashing Need Explicit Canonical Form

Digital signatures and payload hashes require a canonical form — same input always produces the same byte sequence. Pretty-printing is not that form; canonical JSON with sorted keys and no whitespace is.

If your workflow includes signing, use RFC 8785 (JCS) canonical form for signing input, and format for humans separately. Do not conflate the two.

Verification After Pretty-Print

A well-written formatter can be verified: parse the output, compare to parsed input. If any structural difference exists, the formatter changed semantics. That check catches formatter bugs early.

Never trust a formatter you have not verified on your payloads.

Team Handling Of Sort

Pin the team's sort policy. Options:

  • Never sort — default, preserve original order
  • Canonical sort on save — every commit uses the same order
  • Sort only for signing — signing pipeline sorts, editing does not

Each is defensible. Mixing them silently is not. For the conventions side, formatting conventions your team should pin down is the entry.

The Short Version

Pretty-print without reordering. Sort explicitly when the workflow needs a canonical form. Never let a formatter reorder Bundle.entry, Observation.component, or Contract.term silently. Verify the formatter round-trips your payloads without semantic change.

Blueprint-schematic diagram of a Bundle with key order and array order preserved during pretty-printing and an explicit canonical sort path shown separately, drawn as flat schematic lines with red accents on cream paper

Sources