This post is part of a series on Health Samurai sessions from HL7 FHIR DevDays 2025. In this article, āFHIR Schema First Year Results: Ecosystem Evolution and DevāUX,ā Evgenii Mukha, Software Engineer at Health Samurai, shares lessons from running a new FHIR validation engine in production for a year.
What you'll learn:
- Why existing FHIR validators disagree on the same data and what that means for interoperability.
- What FHIR Schema is and how it differs from raw StructureDefinitions.
- How the snapshotāless validation algorithm enables multiāprofile checks and runtime tweaks.
- What the team learned from realāworld use and where FHIR Schema is heading next.
The problem: inconsistent validation
The talk opens with a simple but revealing edge case: a Patient resource containing a primitive extension with null values that should violate an el-1 FHIRPath constraint. Different public servers handle it in completely different ways, from silently trimming the value to accepting it or reporting unrelated errors. This illustrates that validation, which should be a cornerstone of interoperability, behaves unpredictably across implementations.
The core issue is not just bugs but an underspecified validation spec, with key details about slicing, terminology, and edge cases scattered across conversations in Zulip and tickets in JIRA rather than in a clear, implementerāoriented document. Engine authors lack precise guidance comparable to what exists for FHIRPath, making full compatibility hard to achieve.
The FHIR Schema approach
FHIR Schema is introduced as a way to give implementers a shared, languageāagnostic representation of validation constraints and a precise validation algorithm. It is derived from StructureDefinitions rather than replacing them, and consists of three main parts: a transpiler that converts StructureDefinitions into schema files, a JSON/YAML schema format that represents constraints as a tree, and a validation algorithm with an accompanying test suite.
The goal is for validation engines in different stacks to reuse the same schema representation instead of inventing their own internal models. This should make behavior more predictable and reduce divergence between servers.
Tree-shaped schema and snapshotāless validation
Where StructureDefinitions list elements as a flat table, FHIR Schema organizes them into an explicit tree that mirrors real FHIR data. Elements define possible keys, arrays are firstāclass, terminology bindings and polymorphic elements are modeled directly, and required or excluded fields are represented without guessing from cardinality. Slicing is expressed as matchers that decide whether an element belongs to a slice, based on criteria like bindings, patterns, or profile validity.
The validation algorithm builds a set of relevant schemas (base resource, profiles, and ancestors), checks topālevel invariants, then walks the resource tree, applying nodeālevel checks and slicing rules. Because it works without preābuilt snapshots, it supports runtime changes to constraints, simultaneous validation against multiple profiles, and profile discovery by testing which schemas fit existing data.
Production insights and roadmap
After a year of production use in Aidbox, several lessons emerged: transpilation needs to be stateless and reproducible; slicing groups must be uniquely scoped when multiple profiles are applied; and a clearer errorāreporting model is required so tools and test suites can compare results reliably. These points show that standardizing format and algorithm is only part of the jobāerror semantics also matter.
Looking ahead, the team plans to open their test suite, publish reference implementations in JavaScript and Clojure, and release a versioned specification in a more āFHIRālikeā form alongside a working group focused on validator implementers. The aim is to move from one engine plus internal tests to a broader ecosystem of compatible engines and shared test cases.
Why this matters for FHIR teams
For organizations building or integrating FHIR servers and validators, FHIR Schema offers a clearer path to consistent validation. Engine authors get an implementable format and algorithm instead of reverseāengineering behavior from a single reference implementation. Teams gain better chances of consistent pass/fail results across servers and unlock advanced scenarios such as multiāprofile validation and runtime tuning of constraints. This makes FHIRābased systems easier to debug and more predictable in realāworld interoperability scenarios.
Resources
Watch Evgenii's full presentation from FHIR DevDays 2025 and the complete Health Samurai playlist: Watch the full video Full playlist on YouTube
Connect with Evgenii on LinkedInor via the FHIR Schema Zulip stream.
Explore these FHIR Schema resources: Specification Draft Playground Transpiled Package Dump Ref. Implementation (CLJ) Ref. Implementation (JS)
