DEV Community

Cover image for fhir-dsl: a type-safe FHIR toolchain for TypeScript
Abdelhadi Sabani
Abdelhadi Sabani

Posted on

fhir-dsl: a type-safe FHIR toolchain for TypeScript

#typescript #healthcare #fhir #opensource

If you've written TypeScript against a FHIR API, you know the script:

  • The "official" client returns Bundle | unknown. Every property access is a ?. chain through fog.
  • Search parameters are strings. name works on Patient, but does family work on Practitioner? Read the spec, hope you remember.
  • Profile narrowing (US Core, IPS) doesn't exist at the type level. You assume the resource conforms; runtime tells you when it doesn't.
  • FHIRPath is a string. The compiler doesn't know Patient.name.given is valid and Patient.name.givven isn't.
  • Validation is "import a JSON schema and pray it matches the version you're talking to".

The frustration isn't FHIR. FHIR is huge — ~146 resources in R4, hundreds more in R5, tens of thousands of bindings — but it's a precise spec. Every resource, every search parameter, every value set is published as machine-readable JSON. There's no fundamental reason a client has to lie to your type system.

Four months ago I started @fhir-dsl/* on the bet that if you lean hard on code generation and copy Kysely's design playbook, you can have full compile-time safety on every part of FHIR — searches, profiles, extensions, FHIRPath, validators, the lot — without runtime overhead.

This post is a tour of what shipped in v1.x and the design decisions worth stealing if you're building a typed-DSL library for any precise-spec domain (insurance, banking, GraphQL meta-clients, scientific data formats).

A 30-second taste 

import { createClient } from "./fhir/r4"; // generated by fhir-gen

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

const result = await fhir
  .search("Patient")
  .where("family", "eq", "Smith")
  .where("birthdate", "ge", "1990-01-01")
  .include("general-practitioner")
  .sort("birthdate", "desc")
  .count(20)
  .execute();

// result.data: Patient[]
// result.included: Practitioner[]
Enter fullscreen mode Exit fullscreen mode

Every string in that chain is autocompleted from the FHIR R4 schema:

  • "Patient" — narrowed to a real resource type
  • "family" — narrowed to Patient's actual search parameters; if you typed it on Practitioner you'd get a different list
  • "eq" — narrowed to the operator allowed for that parameter type (string params get eq/contains/exact; date params get eq/gt/ge/lt/le/sa/eb/ap; tokens get eq/not/in/above/below/of-type/text)
  • "general-practitioner" — narrowed to Patient's actual _include targets
  • result.included — typed as Practitioner[] because that's what general-practitioner resolves to per the schema

Mistype any of those and the build breaks. No runtime "I wonder if this search param exists" surprises.

The bet: generate everything from the spec

The single biggest design call was leaning fully into code generation. Hand-writing types against ~146 resources × profiles × bindings × extensions is a fool's errand. The spec evolves; hand-maintained types decay.

So @fhir-dsl/cli's fhir-gen reads the FHIR spec — any version (R4, R4B, R5, R6), any Implementation Guide — and emits a typed schema:

npx @fhir-dsl/cli generate \
  --version r4 \
  --ig hl7.fhir.us.core@6.1.0 \
  --validator native \
  --expand-valuesets \
  --resolve-codesystems \
  --out ./src/fhir
Enter fullscreen mode Exit fullscreen mode

Output:

  • types/ — TypeScript interfaces for every resource, with branded primitives, discriminated ChoiceOf<T, "value"> for value[x] fields, primitive _field siblings (_id, _extension, …), and the full 49-variant Extension.value[x] union
  • profiles/ — narrowed types for US Core (or any IG), with profile-required fields non-optional and slice-named optional fields exposed (extension_usCoreRace?, component_systolic?)
  • search-params/ — typed search-parameter map per resource (this is what where() reads)
  • schemas/ — Standard Schema v1 validators per resource, with FHIRPath invariants (pat-1, dom-3, etc.) compiled to refinement predicates
  • terminology/ — resolved value sets as TS unions (with (string & {}) for extensible bindings to keep autocomplete without boxing legitimate codes out)
  • client.ts — createClient<R4Schema>() factory

You commit this. It's just TypeScript — no runtime FHIR-spec dependency, no third-party deps, fully tree-shakeable.

Where it gets interesting: the type system depth

Type-checking the obvious stuff (resource names, primitive search params) is the price of entry. The real differentiator is what happens once you go beyond that.

Profile 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();

// vitals.data: USCoreVitalSignsProfile[]
// — `code`, `subject`, `effectiveDateTime`, `value[x]` are all non-optional
//   because the profile requires them
Enter fullscreen mode Exit fullscreen mode

When you pass a profile URL to .search(), the result type narrows to the profile's interface. Profile-required fields move from optional to required. Slices get their own typed accessors.

Typed extensions per IG

US Core defines extensions like us-core-race, us-core-ethnicity, us-core-birthsex. Each gets a branded Extension<URL> interface in the generated output:

import type { USCoreRaceExtension } from "./fhir/profiles/us-core";

// extension_usCoreRace?: USCoreRaceExtension
const race = patient.extension_usCoreRace?.extension?.find(
  (e) => e.url === "ombCategory",
);
// race.valueCoding has the branded Coding shape per the SD
Enter fullscreen mode Exit fullscreen mode

You don't have to hunt through extension[] looking for a URL match — slicing is materialized in the type.

Slicing on backbone elements

Blood pressure observations have two component[] entries with specific LOINC codes. The US Core BP profile slices component into component_systolic and component_diastolic. The generator emits both as optional accessors:

// bp: USCoreBloodPressureProfile
const systolic = bp.component_systolic?.valueQuantity?.value;
const diastolic = bp.component_diastolic?.valueQuantity?.value;
Enter fullscreen mode Exit fullscreen mode

Runtime helpers (extensionByUrl, findSliceByPath) are also emitted for cases where you'd rather walk the array.

Chained, reverse-chained, composite 

// Chained: search Observations through their patient reference
await fhir
  .search("Observation")
  .whereChained("subject", "Patient", "family", "eq", "Smith")
  .execute();

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

// Composite: code AND value-quantity together
await fhir
  .search("Observation")
  .whereComposite("code-value-quantity", {
    code: "http://loinc.org|8480-6",
    "value-quantity": "60",
  })
  .execute();
Enter fullscreen mode Exit fullscreen mode

Every chain hop, every _has link, every composite component is typed against the schema. whereChained("subject", "Practitioner", "family", "eq", "Smith") would fail at compile time because Observation.subject doesn't reference Practitioner.

Capability-driven client narrowing

If your FHIR server's CapabilityStatement says it doesn't support Observation.write, you can wrap the client to remove .create("Observation", …) from the type:

import { createCapabilityGuard } from "@fhir-dsl/core";

const guarded = createCapabilityGuard(fhir, capabilityStatement);
guarded.create("Observation", { … }); // ← TypeError, server doesn't advertise it
Enter fullscreen mode Exit fullscreen mode

FHIRPath, but typed

@fhir-dsl/fhirpath is a typed FHIRPath expression builder. You compose paths against generated resource types and either compile them to spec strings or evaluate them in-process:

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

const officialFamily = fhirpath<Patient>("Patient")
  .name.where(($) => $.use.eq("official"))
  .family;

officialFamily.compile();
// "Patient.name.where(use = 'official').family"

officialFamily.evaluate(somePatient);
// ["Smith"]
Enter fullscreen mode Exit fullscreen mode

Highlights:

  • UCUM-aware Quantity comparisons. 5 'mg' = 0.005 'g' returns true. Same-dimension equality and ordering use a native UCUM core (SI base + prefixes, common healthcare units, single-/ compounds, bracketed mm[Hg]). Offset, log, and multi-/ units throw UcumError instead of silently wrong answers.
  • resolve() walks Bundles. Inside Bundle.entry.resource.subject.resolve(), the evaluator walks the surrounding Bundle to find the referenced resource — and falls through to EvalOptions.resolveReference when not in scope.
  • Terminology hooks. conformsTo, memberOf, subsumes, subsumedBy compile to spec strings and dispatch to EvalOptions.terminology at evaluate time.
  • Invariants → OperationOutcome. Every ElementDefinition.constraint compiles to a predicate via compileInvariant, and validateInvariants(resource, [inv]) returns a real OperationOutcome. This is wired automatically into the generated validators.
  • Write-back via JSON Patch. setValue and createPatch invert an eq-shaped predicate path into a deep-cloned next resource or an RFC 6902 patch. Useful for form-driven updates that don't blow away other fields.

Not every corner of the FHIRPath N1 spec is covered — only the practical subset that real FHIR invariants and navigation actually use. The coverage table is honest about gaps.

Validators that actually validate

Pass --validator native (or --validator zod) to the generator and you get Standard Schema v1 validators for every resource, datatype, binding, and profile. Native is zero-dep; zod uses zod. Either way, downstream consumers see the same Standard Schema interface.

import { PatientSchema } from "./fhir/schemas";

const result = PatientSchema["~standard"].validate(unknownJson);
if (result.issues) {
  // OperationOutcome-shaped diagnostics, including FHIRPath invariant failures
}
Enter fullscreen mode Exit fullscreen mode

Or chain .validate() directly on a query:

const patient = await fhir
  .read("Patient", "123")
  .validate() // client-side schema check before returning
  .execute();
Enter fullscreen mode Exit fullscreen mode

(Server-side $validate is a separate operation — client.operation("$validate", { resource }) — for cases where you want the server's opinion.)

A real terminology engine

@fhir-dsl/terminology isn't a stub. It implements:

  • ValueSet $expand with filter operators: is-a, is-not-a, descendent-of, regex
  • $validate-code against expanded sets
  • $lookup and $translate
  • $subsumes with transitive concept-graph traversal

So when a FHIR resource binds to a SNOMED ValueSet of "all descendants of 444971000124105" (Body Mass Index), the engine actually walks the hierarchy and gives you the closed enum at generate time. No "we'll just leave it as a string" cop-out.

SMART on FHIR v2 + an LLM bridge

Two more pieces, both opt-in:

  • @fhir-dsl/smart — full SMART v2 client: PKCE-S256 patient launch, backend-services with signed JWT (RS384/ES384), refresh-token rotation, scope DSL. Implements core's AuthProvider interface so wiring it into createClient({ auth: smartClient }) is one line.
  • @fhir-dsl/mcp — Model Context Protocol server that exposes ~10 generic FHIR verbs (read, vread, search, history, create, update, patch, delete, operation, capabilities) as tool calls. Bearer / backend-services / patient-launch auth, pluggable audit sinks, write gating with allowlists and dry-run, response-byte cap to prevent token economy blowups. Stdio and HTTP transports. So you can hand Claude a real FHIR backend without giving it raw HTTP access.

The CLI surface

fhir-gen ships five commands:

Command What it does
generate Generate types (+ optional MCP server, validators, IG profiles)
capability Snapshot a server's CapabilityStatement as a typed report
validate Structural sanity-check on a FHIR JSON resource (CI-friendly)
scaffold-ig Bootstrap a project pre-wired to an Implementation Guide
diff Compare two generated outputs and exit-code on breaking changes

diff is the one I'd point at: wire it into CI, and FHIR version bumps stop being scary because you get a machine-readable list of every removed field, every optional→required change, every type narrowing.

Design decisions worth calling out

Compile/execute split. Every terminal builder exposes compile() (synchronous, returns the wire shape) and execute() (the network call). This lets snapshot tests skip the network, lets the React Query bindings derive a stable queryKey without invoking anything, and lets MCP report the structured query shape to the LLM before executing. Same trick Kysely, Drizzle, and tRPC use.

Discriminated FhirDslError. Every error in the monorepo extends FhirDslError with a kind discriminator (core.request, core.validation, smart.auth, runtime.fhir, …) and structured context. Plus a Result<T, E> + tryAsync toolkit if you want Effect-style typed handling without try/catch.

Surface-frozen at v1.x. Public API across all 11 packages is locked at the surface-v1.0.0 tag. Minor releases add to it, patch releases fix bugs in it, breaking changes wait for v2. Drift is caught by pnpm audit:export-surface on every PR.

Pay-as-you-go packages. Eleven small packages (~5KB to ~30KB each), not one monolith. The MCP package's SMART import is lazy-loaded so bearer-only deployments never pay the jose cost.

What it isn't

  • Not a FHIR server. Use HAPI, Aidbox, Medplum.
  • Not a CDR. No durable storage, no business logic.
  • Not "the FHIR Way". Patient context, multi-tenant routing, pagination strategy — all your app's call.

Try it 

npm install @fhir-dsl/core @fhir-dsl/runtime
npx @fhir-dsl/cli generate --version r4 --out ./src/fhir
Enter fullscreen mode Exit fullscreen mode

If you've shipped FHIR integrations and have battle-scar feedback, I'd genuinely love it — open an issue, or DM. The surface is frozen but the docs and DX are still being polished, and outside critique is the only way to find the gaps insiders miss.

If you're building a typed-DSL for some other precise-spec domain, the design playbook is the same: lean on code generation, split compile/execute, never lie to the type system, and don't let the spec be a "rough guide" — let it be the source of truth. The upfront work pays off forever.

Top comments (0)