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)

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

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