Skip to content
fhir-resource-diff

Normalize

The normalize command transforms a FHIR resource into a canonical form — trimming whitespace, sorting object keys, and normalising date representations — so that two semantically equivalent resources produce identical JSON output. This is most useful before comparing resources that were serialised by different systems.

Basic usage

Section titled “Basic usage”
Terminal window
fhir-resource-diff normalize patient.json

The normalised JSON is written to stdout by default.

What normalisation does

Section titled “What normalisation does”

The canonical preset (the default) applies:

  • Trim strings — leading and trailing whitespace removed from all string values
  • Sort object keys — keys within each JSON object sorted alphabetically, making key order stable across serialisers
  • Normalise dates — date/time strings brought into a consistent representation where possible

These transformations are non-destructive: the information content of the resource is preserved. The goal is eliminating serialisation noise before a diff, not altering clinical data.

Named presets

Section titled “Named presets”
Terminal window
# canonical (default) — full normalisation
fhir-resource-diff normalize patient.json --preset canonical


# none — no transformations (round-trip through parser only)
fhir-resource-diff normalize patient.json --preset none

Writing to a file

Section titled “Writing to a file”
Terminal window
fhir-resource-diff normalize patient.json --output normalized-patient.json

Without --output, the result is written to stdout.

FHIR version

Section titled “FHIR version”
Terminal window
fhir-resource-diff normalize patient.json --fhir-version R5

The FHIR version is used for version-aware normalisation where applicable. Without --fhir-version, the tool auto-detects from meta.fhirVersion or defaults to R4.

Using normalisation before a diff

Section titled “Using normalisation before a diff”

The typical workflow when comparing resources from different systems:

Terminal window
fhir-resource-diff normalize system-a-output.json --output a-normalized.json
fhir-resource-diff normalize system-b-output.json --output b-normalized.json
fhir-resource-diff compare a-normalized.json b-normalized.json

Or directly in the compare step using --normalize:

Terminal window
fhir-resource-diff compare a.json b.json --normalize canonical

Stdin

Section titled “Stdin”
Terminal window
cat patient.json | fhir-resource-diff normalize - --output normalized.json


# Or pipe the output
fhir-resource-diff normalize patient.json | jq '.name'

See also

Section titled “See also”