BabelFHIR-TS

Generate production-ready TypeScript from FHIR® StructureDefinitions — typed interfaces, runtime validators, and FHIR clients.

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 / client-r4b / client-r5 with profile-specific methods (e.g., .usCorePatient(), .pASClaim()) on top of base 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 (30 packages)

Category	Implementation Guide	Package	FHIR
US	US Core	hl7.fhir.us.core@8.0.0	R4
US	QI-Core	hl7.fhir.us.qicore@6.0.0	R4
US	mCODE	hl7.fhir.us.mcode@4.0.0	R4
US	SDOH Clinical Care	hl7.fhir.us.sdoh-clinicalcare@2.2.0	R4
US	NDH (National Directory)	hl7.fhir.us.ndh@1.0.0	R4
US	CARIN BB	hl7.fhir.us.carin-bb@2.1.0	R4
US	CQF Measures	hl7.fhir.us.cqfmeasures@4.0.0	R4
US	Physical Activity	hl7.fhir.us.physical-activity@1.0.0	R4
DaVinci	PAS	hl7.fhir.us.davinci-pas@2.0.1	R4
DaVinci	CDex	hl7.fhir.us.davinci-cdex@2.1.0	R4
DaVinci	PDex	hl7.fhir.us.davinci-pdex@2.1.0	R4
DaVinci	DTR	hl7.fhir.us.davinci-dtr@2.1.0	R4
DaVinci	Alerts	hl7.fhir.us.davinci-alerts@1.0.0	R4
DaVinci	DEQM	hl7.fhir.us.davinci-deqm@4.0.0	R4
DaVinci	Drug Formulary	hl7.fhir.us.davinci-drug-formulary@2.1.0	R4
Universal	IPS	hl7.fhir.uv.ips@2.0.0	R4
Universal	SMART App Launch	hl7.fhir.uv.smart-app-launch@2.2.0	R4
Universal	SDC (Structured Data Capture)	hl7.fhir.uv.sdc@3.0.0	R4
Universal	Genomics Reporting	hl7.fhir.uv.genomics-reporting@3.0.0	R4
Universal	CPG (Clinical Practice Guidelines)	hl7.fhir.uv.cpg@2.0.0	R4
DE	ISiK Basis	de.gematik.isik-basismodul@4.0.3	R4
DE	KBV eRezept	kbv.ita.erp@1.1.1	R4
DE	DE Basisprofil	de.basisprofil.r4@1.5.0	R4
DE	ISiK Medikation	de.gematik.isik-medikation@4.0.1	R4
CH	CH Core (Switzerland)	ch.fhir.ig.ch-core@5.0.0	R4
AU	AU Core (Australia)	hl7.fhir.au.core@1.0.0	R4
IHE	PIXm	ihe.iti.pixm@3.0.4	R4
IHE	MHD	ihe.iti.mhd@4.2.2	R4
R5	AE Research (R5)	hl7.fhir.uv.ae-research-ig@1.0.1	R5
R5	eMedicinal Product (R5)	hl7.fhir.uv.emedicinal-product-info@1.0.0	R5

Validation with Firely .NET SDK

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

Validation with HL7 Java Validator

The second pipeline validates using the official HL7 FHIR Validator, the reference implementation for FHIR conformance checking:

Terminology validation requires a tx server. The pipeline uses --tx-server https://tx.fhir.org/{r4|r5} (matching the package's FHIR version) 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]
  babelfhir-ts update [<pkg@version>] [--recursive] [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
  update                 Regenerate all installed packages (or a specific one) with current babelfhir-ts

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: ~/.fhir/packages for FHIR packages, .cache for working files)
  --no-cache               Delete .cache working folder after generation (does not affect shared ~/.fhir/packages)
  --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)
  --dicomweb               Generate DICOMweb helpers typed to ImagingStudy profiles in the IG
  --recursive              (update only) Recursively search subdirectories for lib/ folders
  --force                  (update only) Force regeneration even if version and flags haven't changed
  --outDir <dir>           Output directory (alias for second positional argument)
  --fhir-version <ver>     FHIR version to target: r4, r4b, or r5 (auto-detected from package if omitted)
  --package <pkg[@version]>  Download FHIR package from registry and process it (latest if no version)
  --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
  --display-language <lang> BCP-47 language(s) for display terms (e.g., de or de,fr,en).
                           Single value replaces concept displays. Comma-separated values
                           also generate a multi-language display map with getDisplay() helper.

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                           # Download latest, process, and install
  babelfhir-ts install de.gematik.isik-basismodul@3.1.0                   # Download specific version
  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
  babelfhir-ts update                                                      # Regenerate all packages in ./lib
  babelfhir-ts update hl7.fhir.us.core@8.0.0                               # Regenerate a specific package
  babelfhir-ts update --recursive                                          # Regenerate packages in all subdirectories

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 — 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 / client-r4b / client-r5
• npm package — @babelfhir-ts/zod
• GitHub repository
• Validation report
• Issue tracker
• Changelog / Releases