Reviewing FHIR Diffs in a Pull Request

FHIR fixtures and IG examples live in pull requests. Reviewing a PR that touches Bundle.json is not the same as reviewing a code change — the reviewer needs to see the semantic change, not the character-level noise. Most default PR diff renderers do the wrong thing for FHIR. Adding one CI step and one review convention makes them do the right thing. The site's Resource-vs-resource comparator is the tool a reviewer can paste into. For the wider FHIR framing, deeper FHIR walkthroughs has more.

What The Default Diff Shows

Every character difference
Every whitespace change
Every meta.lastUpdated bump
Every reordering

That is fine for source code. It is not fine for a Bundle where a formatter round-trip touches almost every line.

For the noise-reduction pattern, diffing two FHIR resources without drowning in reference noise is the entry.

Add A CI Step That Emits A Semantic Diff

Every PR that touches a *.json under fixtures/ or examples/ runs:

The formatter (to isolate whitespace changes)
The FHIR-aware diff (to isolate semantic changes)
Post the semantic diff as a PR comment

That comment is what the reviewer reads. The raw diff stays available for reference; the semantic diff is the primary artifact.

Format Before Committing

If your team uses a formatter (per the conventions), pre-commit formatting means the PR diff shows only intentional changes. Combined with the semantic diff, review becomes tractable.

Without pre-commit formatting, every PR touches every line and reviewers cannot see the intent.

Review Categories

Group the changes for the reviewer:

Business content changes (patient's name, an observation's value)
Structural changes (added extensions, sliced fields)
Meta-only changes (should be ignored per policy)
Reference rewrites (may be intentional migration)

Each category needs a different reviewer question. Grouping saves scroll time.

For the meta-ignore policy, ignoring meta.lastUpdated without ignoring the wrong things is the entry.

Handle Very Large Fixtures

Some fixtures are 5 MB Bundles. Reviewing them in a PR renderer is hopeless.

Options:

Split the fixture into per-resource files (loses Bundle context)
Emit a summary "here is what changed" that a human can review
Require the author to explain the change in the PR description

The summary + explanation pattern usually works. Reviewers verify the summary against the description.

Reject PRs With Only Formatting Changes

A PR whose diff is entirely whitespace/formatting should be rejected in favor of a separate reformatting commit. Mixing reformat and semantic change in one PR means the semantic change hides.

Enforce with a "reformat commits must be separate" rule in your contributing guide.

Fixtures That Change Often

Some fixtures update daily as part of a data feed. Reviewing every change is untenable.

Options:

Auto-approve routine changes with an integration test that runs the semantic diff
Escalate only when the diff crosses a size or field threshold
Review only monthly summaries

Pick per fixture type.

Rejection Criteria

Common reasons to reject a fixture PR:

Reference targets in Reference.reference broken by the change
Coded values from an unbound value set
Meta.profile changed without corresponding profile update
Bundle.type changed (transaction vs batch)

Each of these is a red flag that the change was not intentional.

For the merge-conflict framing, when a diff should be a merge conflict is the entry.

Team Convention

Every FHIR team should have a written PR-review checklist for fixture changes. Fixture reviewers use it. Reviewers who see fixture changes for the first time can consult it.

The Short Version

CI emits a semantic diff as a PR comment. Format pre-commit. Group changes by category. Reject formatting-only PRs mixed with semantic changes. Handle large fixtures with summaries. Codify the review checklist.