AI agents & automation

fhir-resource-diff is designed for automated tooling. Every command supports stdin pipes, --format json for structured output, and --envelope for metadata wrapping — so agents and test harnesses can work with FHIR payloads without writing temp files.

Validate a payload from memory

An agent can validate a FHIR payload it holds in a variable without writing it to disk:

echo "$FHIR_PAYLOAD" | fhir-resource-diff validate - --format json --fhir-version R4

{
  "valid": true,
  "errors": [],
  "hint": null
}

Use - as the file argument to read from stdin.

Diff actual vs expected with envelope

echo "$ACTUAL_PAYLOAD" | fhir-resource-diff compare - expected.json \
  --format json --envelope --preset metadata

{
  "tool": "fhir-resource-diff",
  "version": "0.2.0",
  "command": "compare",
  "fhirVersion": "R4",
  "timestamp": "2026-03-10T21:00:00.000Z",
  "result": {
    "resourceType": "Patient",
    "identical": false,
    "summary": { "added": 5, "removed": 0, "changed": 3, "typeChanged": 0, "total": 8 },
    "entries": ["..."],
    "documentation": "https://hl7.org/fhir/R4/patient.html"
  }
}

An agent can parse this once and know: what changed, how many changes, what FHIR version, and where to find the HL7 docs — without a second tool call.

TypeScript library — import directly

When you control the runtime, skip the CLI and import the library:

import { parseJson, validate, diff } from "fhir-resource-diff";

const parsed = parseJson(responseBody);
if (!parsed.success) {
  throw new Error(`Invalid FHIR JSON: ${parsed.error}`);
}

const validation = validate(parsed.resource, "R4");
if (validation.valid === false) {
  const errors = validation.errors.filter(e => e.severity === "error");
  // errors[].path points to the problem field
  // errors[].ruleId is stable for suppression or automation
}

const result = diff(parsed.resource, expectedFixture, {
  ignorePaths: ["meta.lastUpdated", "id"],
});
if (!result.identical) {
  // result.entries has the full structured diff
  // result.summary has counts: added, removed, changed, total
  // result.documentation is the HL7 spec URL for this resource type
}

The library is browser-safe — it has no Node.js dependencies and works in React, Vite, Cloudflare Workers, and any bundler.

Pipe from a FHIR server

# Validate a live resource
curl -s https://hapi.fhir.org/baseR4/Patient/592473 \
  | fhir-resource-diff validate - --fhir-version R4

# Compare a live resource against a stored baseline
curl -s https://hapi.fhir.org/baseR4/Patient/592473 \
  | fhir-resource-diff compare - baseline/patient-592473.json \
    --format json --envelope

Envelope format

The --envelope flag (requires --format json) wraps output in a metadata envelope:

{
  "tool": "fhir-resource-diff",
  "version": "0.2.0",
  "command": "validate",
  "fhirVersion": "R4",
  "timestamp": "2026-03-14T15:56:25.686Z",
  "result": {}
}

Fields in the envelope:

Field	Type	Description
`tool`	string	Always `"fhir-resource-diff"`
`version`	string	Tool version at time of run
`command`	string	`"validate"` or `"compare"`
`fhirVersion`	string	FHIR version used (`"R4"`, `"R4B"`, `"R5"`)
`timestamp`	string	ISO 8601 timestamp of the run
`result`	object	The command result (same structure as non-envelope JSON output)

Programmatic patterns

Parse and validate in one pass

import { parseJson, validate } from "fhir-resource-diff";

function checkResource(rawJson: string) {
  const parsed = parseJson(rawJson);
  if (!parsed.success) return { ok: false, reason: parsed.error };

  const result = validate(parsed.resource, "R4");
  const errors = result.errors.filter(e => e.severity === "error");
  return { ok: errors.length === 0, errors };
}

Diff with summary only

import { parseJson, diff, summarizeDiff } from "fhir-resource-diff";

const left = parseJson(rawA);
const right = parseJson(rawB);

if (left.success && right.success) {
  const result = diff(left.resource, right.resource, {
    ignorePaths: ["meta.lastUpdated", "id"],
  });
  const summary = summarizeDiff(result.entries);
  console.log(`${summary.total} differences (${summary.added} added, ${summary.removed} removed, ${summary.changed} changed)`);
}