FHIR versions (R4/R4B/R5)

All builders support FHIR R4, R4B, and R5. The version is set with .fhirVersion() on any builder, or with --fhir-version on the CLI.

Selecting a version

import { createPatientBuilder, createBundleBuilder } from "fhir-test-data";

// R4 (default)
const [r4Patient] = createPatientBuilder().locale("uk").seed(1).build();

// R4B
const [r4bPatient] = createPatientBuilder().locale("uk").seed(1).fhirVersion("R4B").build();

// R5
const [r5Patient] = createPatientBuilder().locale("uk").seed(1).fhirVersion("R5").build();

# CLI
fhir-test-data generate patient --locale uk --fhir-version R5
fhir-test-data generate bundle --locale us --seed 1 --fhir-version R4B

R4 (default)

FHIR R4 is the most widely deployed version and the default for all builders. No additional configuration is needed.

Specification: https://hl7.org/fhir/R4/

R4B

R4B is a maintenance release of FHIR R4 that addresses errata and adds a small set of new resources. For all resource types generated by this library, R4B is structurally identical to R4 — the same fields, the same cardinalities, the same value sets.

Selecting R4B is useful when your FHIR server or validator declares R4B conformance and you want to match the declared version in generated fixtures.

Specification: https://hl7.org/fhir/R4B/

R5

R5 introduces breaking structural changes for two of the resource types this library generates. All other resources are identical to R4.

MedicationStatement → MedicationUsage

In R5, MedicationStatement was renamed to MedicationUsage and the medication field was restructured:

Field	R4/R4B	R5
resourceType	"MedicationStatement"	"MedicationUsage"
Medication field	medicationCodeableConcept	medication.concept
Initial status	"active"	"recorded"

// R4
{
  "resourceType": "MedicationStatement",
  "medicationCodeableConcept": {
    "coding": [{ "system": "http://www.nlm.nih.gov/research/umls/rxnorm", "code": "1049502" }]
  },
  "status": "active"
}

// R5
{
  "resourceType": "MedicationUsage",
  "medication": {
    "concept": {
      "coding": [{ "system": "http://www.nlm.nih.gov/research/umls/rxnorm", "code": "1049502" }]
    }
  },
  "status": "recorded"
}

AllergyIntolerance.type

In R4/R4B, AllergyIntolerance.type is a plain code string ("allergy" or "intolerance"). In R5, it is a CodeableConcept with a coding array.

// R4/R4B
{ "type": "allergy" }

// R5
{
  "type": {
    "coding": [
      {
        "system": "http://hl7.org/fhir/allergy-intolerance-type",
        "code": "allergy",
        "display": "Allergy"
      }
    ]
  }
}

Version adapters

All version-specific transformations are applied in src/core/builders/version-adapters.ts. Individual builders are version-agnostic — they produce R4-shaped resources, and the adapter transforms them to the target version as the final step. This keeps builder code clean and ensures version differences are applied consistently.

Specification: https://hl7.org/fhir/R5/