fhir-dsl

The TypeScript FHIR toolchain. A typed query builder (Kysely-inspired), a code generator that emits resources / profiles / ValueSets / search-param types from any FHIR version or IG, a FHIRPath builder + invariant evaluator, optional Standard Schema V1 validators (zod or zero-dep native), SMART on FHIR v2 auth, a terminology engine with real is-a / descendent-of / regex filters, and an MCP server that exposes any FHIR endpoint to an LLM agent.

Compile-time type safety for resources, search parameters, profiles, slices, includes, _has, chained params, and FHIRPath expressions — no more string guessing, no runtime dependencies in the core DSL beyond @fhir-dsl/types.

Documentation | Quick Start | CLI Usage | Roadmap

Why fhir-dsl?

Working with FHIR in TypeScript typically means juggling untyped JSON, memorizing search-parameter names, hand-rolling validators, hand-rolling auth, and hand-rolling whatever bridge gets your data to an agent. Bugs surface at runtime; integrations ossify around whichever pieces you happened to build first.

fhir-dsl is a single coherent toolchain. Generate types from any FHIR version or IG. Query through a fluent builder that's checked at compile time. Validate with optional Standard Schema V1 validators that have FHIRPath invariants wired in. Authenticate with SMART v2 (PKCE-S256, backend-services JWT, patient-launch refresh-token rotation). Walk terminology with a real subsumption engine. Bridge to an LLM with the bundled MCP server. Each piece works alone; together they replace ~6 hand-rolled libraries that would otherwise drift.

Features

• Type-safe query builder — Autocomplete and compile-time checks for resource types, search parameters, operators, includes, reverse includes, chained parameters, composite parameters, and _has filtering. See DSL Syntax.
• FHIRPath expression builder — Type-safe FHIRPath expressions with autocomplete, compilation to FHIRPath strings, and runtime evaluation. Covers the core of the FHIRPath N1 spec (70+ functions across navigation, filtering, subsetting, combining, conversions, strings, math, arithmetic, existence, boolean logic, type operators, tree navigation, aggregates, environment variables, and FHIR-specific functions like extension() and resolve()). See Spec Coverage below.
• Profile-aware queries — Query against US Core or any custom Implementation Guide with automatic type narrowing to profile-specific interfaces.
• Code generation from spec — Generate TypeScript types from any FHIR version (R4, R4B, R5, R6) and any published IG. See CLI Usage.
• Runtime validation (optional) — Opt in with --validator native|zod to emit Standard Schema V1 validators for every resource, datatype, binding, and profile. Chain .validate() on any read/search for client-side schema checks; server-side FHIR $validate is a separate operation invoked via client.operation("$validate", ...). See Validation.
• Immutable builders — Every query method returns a new builder instance, safe to reuse, fork, and compose.
• Zero runtime dependencies — Core DSL depends only on @fhir-dsl/types.
• Dual ESM/CJS — Works in any Node.js environment out of the box.

Who Is This For?

• Backend developers building FHIR-connected services in TypeScript
• Health tech teams who want compile-time guarantees over FHIR APIs
• EHR integrators working with US Core, IPS, or custom profiles
• Anyone tired of debugging FHIR query strings at runtime

Packages

For detailed installation instructions, see the Installation Guide.

Quick Start

1. Install

npm install @fhir-dsl/core @fhir-dsl/runtime

2. Generate types for your project

npx @fhir-dsl/cli generate \
  --version r4 \
  --ig [email protected] \
  --out ./src/fhir

This generates TypeScript interfaces for all FHIR R4 resources plus US Core profile types. See CLI Usage for all options (--resources, --src, --cache, etc.).

3. Query with full type safety

import { createClient } from "./fhir/r4";

const fhir = createClient({
  baseUrl: "https://hapi.fhir.org/baseR4",
});

// Search with typed parameters — every part is type-checked
const result = await fhir
  .search("Patient")
  .where("family", "eq", "Smith")
  .where("birthdate", "ge", "1990-01-01")
  .include("general-practitioner")
  .sort("birthdate", "desc")
  .count(10)
  .execute();

// result.data is Patient[], result.included is typed too
for (const patient of result.data) {
  console.log(patient.name?.[0]?.family); // fully typed
}

Advanced queries — chained params, reverse includes, _has

// Search through references: find observations where patient name is "Smith"
const obs = await fhir
  .search("Observation")
  .whereChained("subject", "Patient", "family", "eq", "Smith")
  .execute();

// Reverse include: get patients with their observations
const patientsWithObs = await fhir
  .search("Patient")
  .revinclude("Observation", "subject")
  .execute();
// patientsWithObs.included has the Observation resources

// _has: find patients who have a specific observation
const filtered = await fhir
  .search("Patient")
  .has("Observation", "subject", "code", "eq", "http://loinc.org|85354-9")
  .execute();

// Composite params: search on multiple values simultaneously
const bpReadings = await fhir
  .search("Observation")
  .whereComposite("code-value-quantity", {
    code: "http://loinc.org|8480-6",
    "value-quantity": "60",
  })
  .execute();
// Compiles to: Observation?code-value-quantity=http://loinc.org|8480-6$60

Read a single resource

const patient = await fhir.read("Patient", "123").execute();
// patient: Patient

Profile-aware queries with type narrowing

const vitals = await fhir
  .search("Observation", "http://hl7.org/fhir/us/core/StructureDefinition/us-core-vital-signs")
  .where("patient", "eq", "Patient/123")
  .where("status", "eq", "final")
  .execute();

// result.data is USCoreVitalSignsProfile[] — profile-required fields are non-optional

FHIRPath Expressions

import { fhirpath } from "@fhir-dsl/fhirpath";
import type { Patient } from "./fhir/r4";

// Type-safe path navigation with autocomplete
const expr = fhirpath<Patient>("Patient").name.family;
expr.compile();              // "Patient.name.family"
expr.evaluate(somePatient);  // ["Smith", "Doe"]

// Expression predicates with $this
fhirpath<Patient>("Patient")
  .name.where($this => $this.use.eq("official")).given
  .compile();  // "Patient.name.where($this.use = 'official').given"

// Collection operations
fhirpath<Patient>("Patient").name.first().family.compile();
fhirpath<Patient>("Patient").name.count().compile();
fhirpath<Patient>("Patient").name.exists().compile();

// String, math, and conversion functions
fhirpath<Patient>("Patient").name.family.upper().compile();
fhirpath<Patient>("Patient").name.family.startsWith("Sm").compile();

Transactions

const bundle = await fhir
  .transaction()
  .create({ resourceType: "Patient", name: [{ family: "Doe" }] })
  .create({ resourceType: "Observation", status: "final", code: { text: "BP" } })
  .delete("Observation", "obs-456")
  .execute();

Batch operations

const bundle = await fhir
  .batch()
  .create({ resourceType: "Patient", name: [{ family: "Doe" }] })
  .delete("Observation", "obs-456")
  .execute();

See the full DSL Syntax Reference for all query methods, operators, and patterns.

Spec Coverage

fhir-dsl is audited against the FHIR architectural overview (https://build.fhir.org/overview-arch.html) and the FHIRPath N1 spec. The plan and gap analysis live in FHIR_COMPLIANCE_PLAN.md.

Drift between this table and the code is caught by pnpm audit:export-surface — every PR that changes the public surface must refresh .surface-snapshot.json.

Search Parameter Operators

Operators are constrained by parameter type — TypeScript won't let you use "contains" on a date parameter.

FHIR R5 Search Spec Coverage

Mapping of FHIR R5 search features to the builder API:

Invariants (FHIRPath → Predicates)

@fhir-dsl/fhirpath exposes a runtime invariant evaluator that compiles ElementDefinition.constraint[*].expression strings into predicates and surfaces results as OperationOutcome issues. The supported subset covers the patterns FHIR core invariants actually use:

• Identifiers and member access (name.given, extension.url)
• Function calls: exists(), empty(), count(), where(), select(), matches('regex'), hasValue(), first()/last()/tail()/single(), iif(), distinct(), startsWith/endsWith/contains/length/toString
• Boolean operators: and, or, xor, implies, not (with FHIRPath three-valued logic)
• Comparison/equivalence: =, !=, <, >, <=, >=, ~, !~, in
• Arithmetic, parentheses, indexers, $this, scalar literals

import { compileInvariant, validateInvariants } from "@fhir-dsl/fhirpath";

const inv = compileInvariant({
  key: "pat-1",
  expression: "name.exists() or telecom.exists() or address.exists()",
  severity: "error",
  human: "Patient must have a contact mechanism",
});

const result = inv.check(patient);            // { passed: true | false | "indeterminate", ... }
const oo = validateInvariants(patient, [inv]); // { resourceType: "OperationOutcome", issue: [...] }

Generator wiring is automatic when --validator is used: every emitted resource and backbone schema with ElementDefinition.constraint[*] is wrapped in s.refine(...) (native) or .superRefine(...) (zod) that calls validateInvariants after structural validation succeeds. Opt out with fhir-gen generate --validator native --no-invariants. Generated projects need @fhir-dsl/fhirpath as a runtime dependency. (Phase 6 follow-up, v0.49.0.)

MCP Server (Model Context Protocol)

@fhir-dsl/mcp exposes any FHIR endpoint as an MCP tool surface for LLM agents — one server === one upstream + one IG.

import { createServer, stdioTransport } from "@fhir-dsl/mcp";

const server = createServer({
  name: "us-core-mcp",
  version: "1.0.0",
  baseUrl: "https://hapi.fhir.org/baseR4",
  resourceTypes: ["Patient", "Observation", "Encounter"],
  auth: { kind: "bearer", token: process.env.FHIR_TOKEN! },
  // writes default to none — opt in explicitly:
  // writes: ["create", "update"],
});

await server.listen(stdioTransport());

Or expose the same server over HTTP for hosted deployments:

import { createServer, httpTransport } from "@fhir-dsl/mcp";

const transport = httpTransport({
  port: 8080,
  cors: true,
  authenticate: (req) => req.headers.authorization === `Bearer ${process.env.MCP_TOKEN}`,
});
await server.listen(transport);
console.log(`MCP listening on ${transport.url()}`);

Capabilities:

• ~10 generic verbs typed by resourceType discriminated union: read, vread, search, history, create, update, patch, delete, operation, capabilities
• Read-only by default; writes opt in via writes, with optional per-resource-type allowlist (writeResourceTypes), confirmWrites (require {confirm: true} per call), and dryRun (short-circuit to a synthetic OperationOutcome)
• Three auth strategies, all wired: bearer, backend-services (SMART v2 signed JWT — RS384 / ES384, lazy-loaded via @fhir-dsl/smart + jose), patient-launch (refresh-token flow with auto-rotation)
• Pluggable AuditSink — JsonLogAuditSink, MemoryAuditSink, NullAuditSink ship by default
• Token economy guards — defaultSearchCount (default 20), defaultReadSummary, and a maxResponseBytes cap (default 64KB) that swaps oversize bodies for a too-costly OperationOutcome (the audit retains the original)
• MCP resources — fhir://<ResourceType>/{id} URIs read via resources/read (and _history/<versionId> for vread)
• Two transports — stdioTransport() for CLI MCP clients, httpTransport() for hosted deployments (POST JSON-RPC; optional CORS, auth hook, body cap; mounts onto a caller-owned http.Server if you already have one)

Generate a server alongside the typed client

fhir-gen generate --version r4 --ig [email protected] \
  --out ./src/fhir --mcp ./mcp-server

./mcp-server/ gets a server.ts shim, mcp.config.json seeded with the IG's resource types, and a README. Launch it with FHIR_BASE_URL=… node server.ts.

Or run inline (no generated types):

fhir-gen mcp https://hapi.fhir.org/baseR4 \
  --resources Patient,Observation \
  --writes create --confirm-writes --auth-bearer-env FHIR_TOKEN

CLI Reference

The fhir-gen binary ships five commands:

fhir-gen generate     # generate TypeScript from a FHIR version (+ optional IG)
fhir-gen capability   # snapshot a server's CapabilityStatement
fhir-gen validate     # structurally check a FHIR JSON resource
fhir-gen scaffold-ig  # initialise a project with an IG pre-wired
fhir-gen diff         # report breaking changes between two generated outputs

fhir-gen generate

fhir-gen capability <baseUrl>

Fetches <baseUrl>/metadata and prints a table of supported interactions, formats, search params, and conditional-* flags. --out <file> dumps the raw JSON, --json prints it to stdout. (Phase 7.2, v0.32.0.)

fhir-gen validate <file>

Structural sanity-check on a FHIR JSON resource: parses, validates the resourceType is known, checks basic invariants (string id, Bundle.entry is an array, no NaN/Infinity in numbers). Designed for CI gates around LLM-generated payloads. --quiet suppresses warnings on success. (Phase 7.1, v0.35.0.)

fhir-gen scaffold-ig <pkg>

Initialises a starter project with the IG pre-wired. Writes package.json, tsconfig.json, fhir-dsl.config.json, and src/client.ts calling the generator's emitted createClient. --out <dir> (default cwd), --version <ver> (default r4), --name <project>, --force to overwrite. (Phase 7.3, v0.36.0.)

fhir-gen diff <oldDir> <newDir>

Compares two generated outputs and reports added/removed resources, removed fields, optional→required changes, and type narrowing. Exits 2 when breaking changes are detected — wire it into CI to gate FHIR version bumps. --json for a machine-readable report. (Phase 7.4, v0.37.0.)

For full CLI details and examples, see the CLI Usage Guide.

Supported FHIR Versions

Development

Prerequisites

• Node.js >= 20
• pnpm >= 10
• TypeScript >= 5.0 with strict: true

Setup

pnpm install
pnpm build

Scripts

pnpm build       # Build all packages
pnpm typecheck   # Type check all packages
pnpm lint        # Lint with Biome
pnpm lint:fix    # Auto-fix lint issues
pnpm test        # Run tests

Architecture

fhir-dsl/
  packages/
    types/       # FHIR type definitions (generated + hand-written)
    core/        # Query builder DSL - the main user-facing API
    runtime/     # HTTP executor, pagination, error handling
    fhirpath/    # Type-safe FHIRPath expression builder
    generator/   # Parses StructureDefinitions, emits TypeScript
    cli/         # CLI wrapping the generator
    utils/       # Shared naming/type-mapping utilities

Dependency graph:

cli -> generator -> utils
core -> types
fhirpath -> types
runtime -> core, types

Core and CLI are fully decoupled. Runtime does not depend on CLI or generator. For more details, see the Architecture Overview.

Documentation

Full documentation is available at awbx.github.io/fhir-dsl.

• Introduction — Overview and motivation
• Installation — Setup and TypeScript configuration
• Quick Start — Get up and running
• Core Concepts — Resources, DSL syntax, and how the type system works
• DSL Syntax Reference — Full API for search, read, transactions, and profiles
• Query Patterns — Common query examples
• Working with Patients — Patient-focused examples
• CLI Usage — Code generation options and output structure
• Architecture — Package design and dependency graph
• Contributing — How to contribute
• Roadmap — Planned features and future direction

Contributing

Suggestions, feature requests, and contributions are welcome. See the Contributing Guide for details, or open an issue on GitHub.

License

MIT