Part of the FHIR operations toolkit

Diff & Validate FHIR resources,
locally.

Structural FHIR resource operations for CI pipelines and AI agents. No server. No Java runtime.

Get startedCLI Reference
$npm install -g fhir-resource-diff
bash — fhir-resource-diff demo
CLI v0.4.0
$fhir-resource-diff validate patient.json --fhir-version R4
{
  "valid": false,
  "fhirVersion": "R4",
  "issues": [
    {
      "severity": "error",
      "path": "Patient.birthDate",
      "message": "Value '1980/12/31' does not match FHIR date format (YYYY-MM-DD)",
      "url": "http://hl7.org/fhir/R4/datatypes.html#date"
    },
    {
      "severity": "warning",
      "path": "Patient.identifier[0].system",
      "message": "Reference 'nhs-number' is not a valid absolute URI",
      "url": "http://hl7.org/fhir/R4/datatypes.html#uri"
    }
  ]
}
$fhir-resource-diff compare baseline.json updated.json --format json
{
  "equal": false,
  "diff": [
    {
      "op": "replace",
      "path": "Patient.name[0].given[0]",
      "oldValue": "John",
      "newValue": "Johnny"
    },
    {
      "op": "add",
      "path": "Patient.telecom[1]",
      "newValue": {
        "system": "email",
        "value": "johnny@work.com"
      }
    }
  ]
}
$import { compareResources, validateResource } from 'fhir-resource-diff';
import { compareResources, validateResource } from "fhir-resource-diff";

const result = validateResource(patientJson, { version: "R4" });
if (!result.valid) {
  console.log("Validation errors:", result.issues);
}

// Normalized comparison (ignores formatting/key order differences)
const diffResult = compareResources(beforeJson, afterJson, {
  ignoreMetadata: true
});
console.log(`Equal: ${diffResult.equal}, Deltas: ${diffResult.diff.length}`);

Engineered for Robust Integration

No server, no Java runtime, and zero external downloads. Lightweight core libraries that fit directly into pipelines.

Path-Level Diff

Compare two FHIR resources field by field. Every added, removed, and changed value is tracked with dot-notation paths and array index tracking — including nested CodeableConcepts, extensions, and identifiers.

Structured Validation

Catch common FHIR mistakes before submission — id format, date patterns, reference string shape, known resource types — with severity levels (error, warning, info) and links to HL7 documentation.

CI/CD Native

--exit-on-diff fails a build step when resources diverge. --quiet suppresses stdout for exit-code-only gates. --envelope wraps output in a metadata envelope for automated triage.

AI Agent Friendly

Every command supports stdin pipes, --format json for structured output, and --envelope for metadata wrapping with tool version, FHIR version, timestamps, and HL7 doc URLs.

Multi-Version R4/R4B/R5

Auto-detects target version from fhirVersion or allows explicit overrides. Handles version-specific structural variations under the hood.

Browser Safe

No Node-specific APIs. Runs anywhere: inside CLI wrapper, React apps, Chrome Extensions, Deno, or Cloudflare Workers.

The FHIR Operations Toolkit

A suite of independent CLI engines that compose together seamlessly for development, CI/CD, and agentic workflows.

1. Generate

fhir-test-data

Synthetic patient & clinical resources mapped to 14 locales with check-digit validation.

View Docs ➔
2. Diff & Validate

fhir-resource-diff

Structure-aware diff engine and path-level validation. Fails builds on delta violations.

Active Project
3. Capability Check

fhir-capability-analyzer

Fetch capability statements, compare configurations, and detect profile compliance.

View Docs ➔