A pretty-printer should never touch reference strings. Sounds obvious. In practice, formatters that normalize URL casing, resolve relative paths, or reformat urn:uuid: values silently break Bundle semantics. Reference integrity depends on byte-for-byte preservation of every reference field. The site's FHIR JSON tidier leaves references untouched. For the wider FHIR framing, more healthcare interoperability notes has more.

What A Reference Actually Is

Reference.reference is a URL string. Case-sensitive. Character-exact. It can be:

• Relative — Patient/123
• Absolute — https://server/Patient/123
• Version-specific — Patient/123/_history/5
• URN — urn:uuid:6b1e...
• Identifier-based fallback via Reference.identifier

Every one of those is a byte-exact string that receivers compare against. A formatter that changes any character breaks resolution.

What Formatters Sometimes Do

• Lowercase URL schemes — HTTPS:// becomes https://
• Normalize trailing slashes — Patient/123/ becomes Patient/123
• Resolve .. and . in paths
• Change URN casing
• Percent-encode characters that were previously not encoded

Each of these is a normalization operation on strings. Each looks harmless. Each can break reference resolution in a transaction Bundle.

For the base ordering rule, keeping resource order stable across pretty-printing is the entry.

The urn:uuid: Case Is Specific

Transaction Bundles use urn:uuid: in Bundle.entry.fullUrl and the receiver rewrites them to real ids. The urn:uuid: prefix is case-sensitive per the URN spec, but the UUID itself is defined as lowercase.

A formatter that uppercases the UUID (or the URN scheme) can produce a URN that some parsers reject. The safe rule: do not touch URN strings.

The System URL Case

Identifier.system and Coding.system carry URLs that identify namespaces. Some are HL7-canonical: http://loinc.org, http://snomed.info/sct. Some are private-domain URLs. All are case-sensitive.

Formatter normalization that lowercases the entire URL breaks matches against value sets bound to the exact URL. The URL is an identifier, not a network location.

For the escape-sequence side, the escape sequences pretty-printers get wrong covers the character-level pitfalls.

Verification Round-Trip

Every formatter should be tested: parse the output back to a data structure, compare against the parsed input. If the two structures differ, the formatter changed semantics.

For reference fields specifically, add a targeted test:

• Walk the Bundle for every Reference.reference and Reference.identifier string
• Compare each byte-for-byte pre- and post-format
• Fail the test on any change

That two-minute test catches an entire class of hard-to-debug incidents.

Case-Sensitive Comparison Downstream

Receivers compare references case-sensitively. That is not a bug; that is the URN and URL spec. Producers that emit inconsistent casing produce payloads that fail resolution.

Fix at the producer, not the receiver. Do not case-normalize at the formatter.

Preserved Whitespace In References

References never contain whitespace, and no formatter should insert it. But some formatters wrap long URLs across multiple lines — that inserts newlines into the string value, which then must be escaped as \n, which then may or may not roundtrip.

Do not wrap reference strings.

Team Convention

Every team should have a written rule: "the formatter does not modify Reference.reference, Reference.identifier, fullUrl, or system URLs." Add it to your formatting conventions.

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

The Short Version

References are byte-exact identifiers. Formatters must not touch them. Verify with a round-trip test that compares every reference string pre- and post-format. Never wrap references across lines. Never normalize URL casing. The formatter changes whitespace and only whitespace.

Sources

• HL7 canonical FHIR references chapter - HL7 canonical FHIR references chapter