Bundle recipes

Overview

The default generate bundle command composes a realistic Bundle for you. When a pipeline test needs a specific Bundle shape — a fixed resource mix, particular codes and values, and a known reference graph — define a recipe instead.

Recipes are composition rules, not clinical scenario models. You choose the resources, codes, values, and reference wiring; fhir-test-data handles deterministic generation, the FHIR resource builders, deep-merged field overrides, and reference resolution.

fhir-test-data generate bundle --recipe ./lab-result-basic.yaml --seed 42

Recipe format

A recipe is a YAML or JSON document with a name, optional defaults, and an ordered list of resources. Later resources can reference earlier ones by their id alias.

name: lab-result-basic
locale: uk
fhirVersion: R4
bundle:
  type: transaction
resources:
  - type: Patient
    id: patient
  - type: Encounter
    id: encounter
    fields:
      subject: patient
  - type: Observation
    id: hba1c
    fields:
      subject: patient
      encounter: encounter
      category:
        - coding:
            - system: http://terminology.hl7.org/CodeSystem/observation-category
              code: laboratory
              display: Laboratory
      code:
        coding:
          - system: http://loinc.org
            code: "4548-4"
            display: HbA1c
      valueQuantity:
        value: 7.2
        unit: "%"
        system: http://unitsofmeasure.org
        code: "%"
  - type: DiagnosticReport
    id: report
    fields:
      subject: patient
      encounter: encounter
      code:
        coding:
          - system: http://loinc.org
            code: "55454-3"
            display: Hemoglobin A1c in Blood
      result:
        - hba1c

Fields

Field	Required	Description
name	yes	Human-readable recipe name, used in diagnostics.
locale	no	Default locale for identifiers, names, and addresses. Overridden by --locale.
fhirVersion	no	Default FHIR version (R4 | R4B | R5). Overridden by --fhir-version. Default R4.
bundle.type	no	Bundle type (transaction, collection, searchset, …). Default transaction.
resources	yes	Ordered, non-empty list of resource entries.

Resource entries

Field	Required	Description
type	yes	Resource type to generate: Patient, Practitioner, PractitionerRole, Organization, Observation, Condition, AllergyIntolerance, MedicationStatement, Encounter, DiagnosticReport.
id	yes	Alias other entries use to reference this resource. Must be unique.
count	no	Number of resources to generate for this entry. Cannot be combined with a fields.id override.
fields	no	Object deep-merged into the generated resource after builder defaults.

Reference wiring

Reference fields resolve recipe aliases to the generated resource’s urn:uuid: reference automatically. Supported reference fields include subject, encounter, performer, result, organization, and practitioner.

In the example above, Observation.subject: patient becomes a reference to the generated Patient, and DiagnosticReport.result: [hba1c] becomes a reference to the generated Observation. An unknown alias, or an alias that resolves to multiple resources, is a recipe error.

Any non-reference fields value is deep-merged into the generated resource, so you can pin exact codes, categories, and values while letting the builder fill in the rest.

Overriding recipe defaults

CLI flags win over recipe defaults, so one recipe can drive multiple locales and versions:

fhir-test-data generate bundle --recipe ./lab-result-basic.yaml \
  --locale us --fhir-version R5 --count 2 --seed 42

With a fixed --seed, the same recipe produces byte-identical Bundles across runs and machines — suitable for committing as regression fixtures.

Starter recipes

Ready-to-use recipes ship with the package under examples/recipes/:

• lab-result-basic.yaml — Patient, Encounter, Observation, DiagnosticReport.
• condition-medication-basic.yaml — Patient, Condition, MedicationStatement.
• diagnostic-workup-basic.yaml — Patient, Practitioner, Organization, Encounter, Observation, DiagnosticReport.

Library API

The same behavior is available programmatically via createBundleFromRecipe:

import { createBundleFromRecipe, type BundleRecipe } from "fhir-test-data";

const recipe: BundleRecipe = {
  name: "lab-result-basic",
  locale: "uk",
  fhirVersion: "R4",
  bundle: { type: "transaction" },
  resources: [
    { type: "Patient", id: "patient" },
    { type: "Observation", id: "hba1c", fields: { subject: "patient" } },
  ],
};

// Returns an array of Bundles (one per `count`, default 1).
const [bundle] = createBundleFromRecipe(recipe, { seed: 42 });

createBundleFromRecipe(recipe, options) accepts seed, locale, fhirVersion, and count in options, each overriding the recipe’s defaults. Invalid recipes throw a BundleRecipeError with a message pointing at the offending field.