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.

What you get

• Strongly typed interfaces that merge profile constraints with base FHIR types (types come from @types/fhir)
• Compiled output by default — packages ship JavaScript (.js) plus TypeScript declarations (.d.ts)
• 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
• Fast and lightweight—minimal runtime deps; only fhirpath is required for validators
• Type-safe FHIR client — generated client extends @babelfhir-ts/client-r4 with profile-specific methods (e.g., .usCorePatient(), .pASClaim()) on top of base R4 resource accessors
• Install any FHIR profile as a node module—use babelfhir-ts install to add Implementation Guides directly to your project

Continuous Validation

Every pull request runs two independent CI pipelines that validate generated code against real-world FHIR Implementation Guides. For each IG, the pipeline:

1. Downloads the FHIR package from a registry
2. Generates TypeScript interfaces, validators, and classes
3. Compiles the output with tsc (zero errors required)
4. Generates empty() and random() test resources for every profile
5. Validates those resources against two external FHIR validators

Tested Implementation Guides

Validation with Firely .NET SDK

The first pipeline validates generated resources using the Firely .NET SDK validator (v3.1.0). Results are published as live badges:

Validation with HL7 Java Validator

The second pipeline validates using the official HL7 FHIR Validator (v6.9.1), the reference implementation for FHIR conformance checking:

Terminology validation requires a tx server. The pipeline uses --tx-server https://tx.fhir.org/r4 during generation to expand ValueSets and produce valid codes.

📊 Full Report

Installation

npm install -g babelfhir-ts

Or on-demand: npx babelfhir-ts --help

Requirements: Node.js 18+ and an internet connection for remote registries.

Quick Start

# Generate from a local folder
babelfhir-ts input/ output/

# Download and process from a registry
babelfhir-ts --package hl7.fhir.us.core@8.0.0

# Install as a project dependency
babelfhir-ts install hl7.fhir.us.core@8.0.0

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

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

CLI Reference

BabelFHIR-TS: Generate TypeScript interfaces from FHIR StructureDefinitions

Usage:
  babelfhir-ts [options] [<input> [output]]
  babelfhir-ts install [--package] <pkg@version|path> [--registry <url>] [options]

Arguments:
  input   Input can be:
          - Canonical URL of a FHIR profile (http://... or https://...)
          - Directory containing FHIR packages (.tgz/.zip files)
          - Single FHIR package (.tgz/.zip file)
          - Single StructureDefinition (.json file)
          - Directory containing StructureDefinition files
  output  Output directory or archive name (optional)

Commands:
  install                Download, process, and npm install package as dependency

Options:
  -h, --help               Show this help message
  -v, --version            Show version number
  --log <dest>             Log destination: console (default) or file
  --log-level <level>      Log verbosity: error, warn, info (default), or debug
  --cache-dir <path>       Custom cache directory (default: .cache, env: FHIR_CACHE_ROOT)
  --no-cache               Delete .cache folder after generation
  --no-classes             Only generate interfaces and types (skip class generation)
  --no-client              Skip FHIR client generation (client generated by default)
  --schema <format>        Generate schema files alongside outputs (supported: zod)
  --fhir-version <ver>     FHIR version to target: r4 or r4b (auto-detected from package if omitted)
  --package <pkg@version>  Download FHIR package from registry and process it
  --registry <url>         FHIR package registry URL (default: https://packages.simplifier.net)
  --tx-server <url>        Terminology server URL for ValueSet expansion (e.g., https://tx.fhir.org/r4)
                           When set, expands ValueSets without explicit codes using $expand operation

Examples:
  babelfhir-ts                                             # Process ./input to ./output
  babelfhir-ts http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient  # Generate from profile URL
  babelfhir-ts package.tgz                                 # Process package to current directory
  babelfhir-ts package.tgz modified-package.tgz            # Embed interfaces in package
  babelfhir-ts profiles/ generated/                        # Process directory to directory
  babelfhir-ts --package hl7.fhir.us.core@8.0.0            # Download and process from default registry
  babelfhir-ts --package hl7.fhir.us.core@8.0.0 output/    # Download and output to directory
  babelfhir-ts --package pkg@version --log console --log-level debug  # With verbose logging
  babelfhir-ts install de.gematik.isik-basismodul@3.1.0                   # Download, process, and npm install
  babelfhir-ts install ./package.tgz                                      # Install from local package file
  babelfhir-ts install hl7.fhir.us.core@8.0.0 --registry <url>            # Install from custom registry
  babelfhir-ts install --package hl7.fhir.us.core@8.0.0 --registry <url>  # Alternative syntax

Documentation

Full documentation is available at max-health-inc.github.io/BabelFHIR-TS/docs/

• Getting Started — installation, quick start, first generation
• CLI Reference — full list of commands and options
• Generated Code Guide — understanding the output, module resolution, FHIR type imports
• FHIR Client — type-safe server interactions
• Validation — what validators check, CI pipelines, known Firely SDK issues
• Limitations — R4 only, edge cases, random() caveats
• Contributing — dev setup, scripts, project structure

License

ISC © Maximilian Nussbaumer

Changelog

Release notes are published automatically on GitHub Releases: View all releases

Contributing

Contributions are welcome! See the Contributing guide for dev setup, scripts, and how to submit changes.

Security

For security issues, please see SECURITY.md for our security policy and how to report vulnerabilities.

Links

• npm package — babelfhir-ts
• npm package — @babelfhir-ts/client-r4
• GitHub repository
• Validation report
• Issue tracker
• Changelog