Skip to content
fhir-resource-diff

Getting started

fhir-resource-diff is a CLI and library for comparing and validating FHIR JSON resources — fast, local, no infrastructure dependencies.

Install

Section titled “Install”
Terminal window
# Global install (recommended for CLI use)
npm install -g fhir-resource-diff
# or
pnpm add -g fhir-resource-diff


# Project-local (for library use or CI)
pnpm add -D fhir-resource-diff

First commands

Section titled “First commands”

Validate a resource

Section titled “Validate a resource”
Terminal window
fhir-resource-diff validate patient.json
# → valid

With a specific FHIR version:

Terminal window
fhir-resource-diff validate patient.json --fhir-version R4
valid
  ℹ For full FHIR schema validation, use the official HL7 FHIR Validator
    → https://confluence.hl7.org/display/FHIR/Using+the+FHIR+Validator

The note about the HL7 Validator is always shown when --fhir-version is specified — it’s a footer about scope, not a finding about your resource.

Compare two resources

Section titled “Compare two resources”
Terminal window
fhir-resource-diff compare expected.json actual.json
ResourceType: Patient
Status: 3 difference(s) found


Changed:
  birthDate: "1974-12-25" → "1974-12-26"
  name[0].given[0]: "Peter" → "Pete"


Added:
  telecom[2].system

Look up a resource type

Section titled “Look up a resource type”
Terminal window
fhir-resource-diff info Patient
Patient (base)
FHIR versions: R4, R4B, R5
Documentation:
  R4:  https://hl7.org/fhir/R4/patient.html
  R4B: https://hl7.org/fhir/R4B/patient.html
  R5:  https://hl7.org/fhir/R5/patient.html

Quick wins

Section titled “Quick wins”

CI gate — fail a build step when resources diverge:

Terminal window
fhir-resource-diff compare expected.json actual.json --exit-on-diff --quiet

JSON output for automation:

Terminal window
fhir-resource-diff compare a.json b.json --format json

Ignore noisy metadata fields:

Terminal window
fhir-resource-diff compare a.json b.json --preset metadata

Pipe from a FHIR server:

Terminal window
curl -s https://hapi.fhir.org/baseR4/Patient/592473 \
  | fhir-resource-diff validate - --fhir-version R4

Run from source (contributors)

Section titled “Run from source (contributors)”

No build step needed during development:

Terminal window
git clone https://github.com/dnlbox/fhir-resource-diff.git
cd fhir-resource-diff
pnpm install


pnpm cli -- compare examples/patient-a.json examples/patient-b.json
pnpm cli -- validate examples/patient-a.json

The -- separator after pnpm cli is required so pnpm passes flags to the script rather than consuming them.

Next steps

Section titled “Next steps”