BabelFHIR-TS

BabelFHIR-TS transforms FHIR® StructureDefinitions into production-ready TypeScript code with full type safety and built-in validation. Unlike generic FHIR type definitions, BabelFHIR-TS generates profile-aware interfaces that understand your Implementation Guide's constraints, extensions, and slicing rules.

Why BabelFHIR-TS?

The FHIR Challenge: Implementation Guides define strict profiles (e.g., US Core, German basisprofil) that constrain base FHIR resources with must-support elements, custom extensions, value set bindings, and cardinality rules. Existing TypeScript libraries can't capture these requirements when you need profile-specific types.

The BabelFHIR-TS Solution: Automatically generates TypeScript interfaces and validation logic directly from StructureDefinition JSON. Your IDE autocompletes must-support fields, flags missing extensions at compile-time, and validates FHIRPath invariants at runtime.

What you get

• Strongly typed interfaces that merge profile constraints with base FHIR types (built on @types/fhir)
• Runtime validation using FHIRPath expressions from the profile—no external validator required for basic checks
• Type-safe extension handling with proper slicing and nested extension support
• Random data builders for testing and development (when class generation is enabled)
• Zero manual mapping—consume any FHIR package or Implementation Guide directly from registries

Use it to build FHIR-compliant APIs, validate incoming resources against profiles, or generate type-safe client SDKs from Implementation Guides.

Key features

• 🎯 Profile-first design – generate interfaces that understand your IG's must-support elements, slices, and extensions
• ⚙️ CLI-first workflow – install globally or run with npx; works against package archives, entire directories, or single .json profiles
• ✅ Built-in validation – every generated class includes an async validate() function that executes profile constraints through FHIRPath (high-level checks only; see details below)
• 🔌 Extension-aware – properly types extension slices, nested extensions, and sidecar _field elements for primitive extensions
• 📦 Package-friendly – re-embeds generated code back into .tgz archives or expands into a target folder for direct consumption
• 🌐 Registry integration – download and process packages directly from Simplifier, HL7, or custom FHIR registries
• ♻️ Caching + cleanup – opt into --no-cache to remove temporary .cache directories after generation

Installation

Install globally (recommended when using the CLI frequently):

npm install -g babelfhir-ts

Or invoke on-demand without a global install:

npx babelfhir-ts --help

Requirements: Node.js 18+ (ESM support) and an internet connection when downloading packages from remote registries.

Quick start

Generate code from a local folder that contains FHIR packages:

babelfhir-ts input/ output/

Process a single package archive and write the generated interfaces back into a new .tgz file:

babelfhir-ts hl7.fhir.us.core-8.0.0.tgz us-core-generated.tgz

Download and process a package directly from a registry (defaults to https://packages.simplifier.net):

babelfhir-ts --package hl7.fhir.us.core@8.0.0

Install a processed package into your current project:

babelfhir-ts install hl7.fhir.us.core@8.0.0

After generation you can import the emitted classes:

import { USCorePatientClass } from "./output/USCorePatientClass";

const patient = USCorePatientClass.random();
const { errors, warnings } = await patient.validate();

CLI reference

babelfhir-ts [options] [<input> [output]]

Supported inputs

• Directory – scan all .tgz, .zip, or .json files inside the folder
• Archive – process a FHIR NPM package in .tgz or .zip format
• StructureDefinition JSON – generate code for a single profile definition

Generated output

For each StructureDefinition the generator produces:

• *.ts interface definitions (extending the canonical FHIR types)
• *Class.ts companions that offer:
  • constructor helpers (empty, random, randomClass)
  • deterministic field filling for required and must-support elements
  • validate() that evaluates FHIR invariant expressions via fhirpath
• optional validation parity artefacts when you run the test suite (npm test validatorParity)

The validator relies on fhirpath.evaluate(...) to enforce profile invariants (including min cardinalities, slices, and custom expressions) without requiring a full FHIR server. It intentionally performs high-level checks only: terminology expansion, reference resolution, and other server-backed logic are out of scope, so keep a downstream validator (e.g., the HL7 Java validator CLI) in your QA pipeline for full conformance.

Scripts for contributors

Caching notes

The generator caches downloaded StructureDefinitions and packages inside .cache/. When you need a clean run, pass --no-cache or manually remove the folder. Temporary downloads land in .temp-* directories and are cleaned up automatically.

License

ISC © Maximilian Nussbaumer