Validation

[smunini]

Introduction

This document shares my thoughts on how to approach FHIR resource validation for the Helios FHIR Server. Like the persistence layer discussion, the auth discussion, and the bulk export discussion, this is an architectural strategy document rather than a comprehensive specification. It explains the motivating direction, the key building blocks, the validation model we intend to adopt, and the Rust trait and code-generation designs that will shape the validation subsystem.

Who should read this? Anyone with an interest in FHIR conformance, profile-driven validation, terminology binding, or the mechanics of FHIR validation generally. Feedback is very much welcome — this is open source, developed in the open, and your perspective matters.

A note on scope. Validation in FHIR is a large surface — the FHIR Validation spec enumerates eight distinct aspects, from structure to business rules. This document commits to a concrete plan for the computable, profile-expressible aspects: structure, cardinality, value domains, terminology bindings, FHIRPath invariants, profiles, slicing, and references. Two things are explicitly deferred and get their own treatment later: Questionnaire/QuestionnaireResponse validation (its own animal), and application business rules (duplicate detection, referential existence against the live store) — the latter belongs to the persistence and REST layers, not the validation engine.

The central architectural bet of this document is this: we will not walk StructureDefinition snapshots at runtime. We will compile them — ahead of time, into Rust — using an intermediate representation borrowed from the FHIR Schema project, and we will lean on the code-generation machinery this project already owns (helios-fhir-gen and helios-fhir-macro) to do it.

---

The Lay of the Land: What "Validation" Means in FHIR

The FHIR specification is unusually candid that validation is incomplete — it can only address "computable aspects of conformance," and even a green light from a validator is "a statement about how likely the resource is to be acceptable," not a guarantee. With that caveat framed, the spec enumerates the aspects a validator checks. It is worth reproducing them, because each one maps to a distinct piece of machinery we have to build:

Aspect	What it checks	Where the rule lives
Structure	Only defined elements are present; each is in the right place.	Base StructureDefinition
Cardinality	Each element occurs within its min..max bounds.	ElementDefinition min / max
Value domains	Primitive values match their type's rules (a date is a date, a code matches its regex).	Type system
Coding / CodeableConcept bindings	Coded values conform to the bound ValueSet at the binding's strength.	ElementDefinition binding + terminology
Invariants	Co-occurrence and conditional rules hold (FHIRPath expressions).	ElementDefinition constraint
Profiles	Every rule in any asserted profile is satisfied — tightened cardinality, fixed values, slicing.	Profile StructureDefinition
Questionnaires	A QuestionnaireResponse matches its Questionnaire.	(deferred)
Business rules	Application logic: references resolve, no duplicates, etc.	(persistence / REST layer)

The spec also ranks the methods of validation by capability. XML/JSON schema and Schematron are the least capable — they handle structure and some cardinality but "slicing is partially supported," and they are, in the spec's own words, "not connected to a terminology server," which makes binding validation impossible. At the top sits the validator: a program that reads the full profile graph, resolves terminology against a real terminology server, and evaluates FHIRPath invariants.

The kick-off surface for validation is the $validate operation:

POST [base]/Observation/$validate
POST [base]/Observation/$validate?profile=http://hl7.org/fhir/StructureDefinition/heartrate

It accepts a resource (and, optionally, a mode and one or more profile canonicals) and returns an OperationOutcome enumerating every issue found, each with a severity (fatal / error / warning / information), a machine-readable code, an expression (the FHIRPath location of the problem), and human-readable diagnostics. That OperationOutcome is the contract. Everything this document proposes is in service of producing a correct, complete, and fast one.

Binding strengths, because they change everything

One subtlety that deserves front-loading: terminology bindings have a strength, and the strength determines whether a failed binding is an error, a warning, or nothing at all.

Strength	Meaning	Failure severity
required	The code SHALL come from the ValueSet.	error
extensible	The code SHALL come from the ValueSet if the set covers the concept; otherwise a code from elsewhere is permitted.	error or warning, context-dependent
preferred	The code SHOULD come from the ValueSet.	warning / information
example	The ValueSet is illustrative only.	none (informational at most)

This table is why binding validation cannot be a boolean. The engine has to know the strength, has to be able to expand the ValueSet (or ask a terminology server to $validate-code), and has to downgrade its own severity accordingly. It is the single most operationally demanding aspect of validation, and it is the one schema-only validators simply cannot do.

---

Why Not Just Walk StructureDefinitions?

The obvious implementation of a FHIR validator reads StructureDefinition resources directly. Load the snapshot, walk the element[] array, and for each element check the instance against min, max, type, binding, constraint, and slicing. Every reference implementation started here. Almost none of them stayed here, and the FHIR Schema project's motivation section explains why with unusual bluntness: "there are only few implementations of FHIR validation — why? because it's hard, no unit-tests, esoteric knowledge."

The StructureDefinition format is a poor runtime data structure for validation, for reasons that compound:

• It is flat, but the data is nested. A snapshot is a flat list of elements keyed by dotted paths (Patient.contact.name.given). The resource is a tree. Every validator that walks a snapshot first has to reconstruct the tree from the path strings — the exact "convert SD to a nested data structure" step that the FHIR Schema project observes "most of implementers do," duplicating the same fiddly transformation in every language.
• Snapshots are a leaky abstraction. Generating a correct snapshot from a differential (merging a profile's constraints onto its base's elements) is itself one of the hardest parts of FHIR tooling — slicing, re-slicing, and type-narrowing all interact. The FHIR Schema project's position, which I find persuasive, is that "snapshots is implementation detail leaking into standard, only-differential validation sounds better."
• Choice types, arrays, and the primitive-extension split are implicit. Whether value[x] is present as valueQuantity or valueString, whether an element is an array or a scalar, whether a primitive carries an id/extension sidecar — none of this is a first-class field in a snapshot. It has to be inferred from type[] and max. Every inference is a place to get it subtly wrong.

The $validate spec's own note that schema-based methods only "partially support" slicing is a symptom of the same disease: the source format does not represent the thing you need to check in a shape that makes checking it natural.

So the question is not "should we transform StructureDefinitions into something better?" — everyone does. The question is "into what, and when?" This document's answer: into FHIR Schema, at code-generation time, emitted as Rust.

---

The Model: FHIR Schema

FHIR Schema is a re-representation of StructureDefinition, "heavily inspired by the design of JSON Schema," whose entire purpose is to be the developer-friendly intermediate form that everyone was hand-rolling anyway — but standardized, unit-tested, and language-neutral. It has reference implementations, a growing conformance test suite modeled on the JSON Schema test corpus, and — critically for us — a documented, mechanical conversion from StructureDefinition. We adopt it as our internal validation IR.

The shape is exactly what you would design if you sat down to make validation easy. A schema is an object with a small header and a nested elements tree that mirrors the resource. Here is the top-level surface, from the FHIR Schema reference:

url: http://hl7.org/fhir/StructureDefinition/Patient   # canonical identity
type: Patient                                           # resource/type being described
name: Patient
base: http://hl7.org/fhir/StructureDefinition/DomainResource
kind: resource                                          # resource | complex-type | primitive-type
derivation: specialization                              # specialization (a type) | constraint (a profile)
required: [ ... ]                                       # subelements that SHALL be present
excluded: [ ... ]                                       # subelements that SHALL be absent
elements: { ... }                                       # the nested element tree
constraints: { ... }                                    # FHIRPath invariants at this level

base is the inheritance pointer — a schema "will inherit all elements and constraints" from its base, so a US Core Patient profile carries a base of the core Patient schema, which carries a base of DomainResource, and validation walks that chain. derivation distinguishes a brand-new type (specialization) from a profile that constrains an existing one (constraint) — the same distinction the $validate operation makes when you pass a profile parameter.

Everything interesting is in elements. Each element is an object whose properties are, individually, trivial to check. Consider this (lightly trimmed) excerpt of the real R4 Patient schema — note how each concept that a StructureDefinition leaves implicit is here an explicit key:

elements:
  gender:
    type: code
    scalar: true
    binding:
      valueSet: http://hl7.org/fhir/ValueSet/administrative-gender
      strength: required
      codesystems:
      - http://hl7.org/fhir/administrative-gender
  name:
    type: HumanName
    array: true
  managingOrganization:
    type: Reference
    scalar: true
    refers:
    - http://hl7.org/fhir/StructureDefinition/Organization
  multipleBirth:
    choices:
    - multipleBirthBoolean
    - multipleBirthInteger
    scalar: true
  multipleBirthBoolean:
    type: boolean
    choiceOf: multipleBirth
  multipleBirthInteger:
    type: integer
    choiceOf: multipleBirth
  contact:
    type: BackboneElement
    array: true
    constraints:
      pat-1:
        human: SHALL at least contain a contact's details or a reference to an organization
        severity: error
        expression: name.exists() or telecom.exists() or address.exists() or organization.exists()
    elements:
      name:      { type: HumanName, scalar: true }
      telecom:   { type: ContactPoint, array: true }
      organization:
        type: Reference
        scalar: true
        refers: [ http://hl7.org/fhir/StructureDefinition/Organization ]

Read that against the aspects table from earlier and the mapping is one-to-one:

• Shape — array: true vs scalar: true are mutually exclusive first-class flags. "Only arrays accepted" / "arrays rejected." No more inferring cardinality-of-one from max: "1". (Empty arrays are always rejected, matching FHIR.)
• Cardinality — min / max integers, permitted only when the shape is array. Absent means unconstrained.
• Value domain — type names a FHIR type. Primitive types validate the value; complex types pull in that type's schema and recurse.
• Choice types — the choices list enumerates the polymorphic members and choiceOf back-links each concrete member to its base. The rule "exactly one of multipleBirthBoolean / multipleBirthInteger, never both" falls straight out.
• Bindings — binding carries valueSet and strength, exactly the two facts the strength table above says we need.
• References — refers lists the allowed target profile canonicals for a Reference.
• Invariants — constraints is a map of constraint-id → { expression, human, severity }, each a FHIRPath expression evaluated with %context bound to the node the constraint is attached to (top-level constraints see the whole resource; the contact constraint above sees each contact element).
• Nesting — elements recurses for backbone elements, and elementReference handles genuinely recursive structures like Questionnaire.item without infinite expansion.

Slicing gets its own object, and it is far more legible than the StructureDefinition discriminator machinery:

elements:
  address:
    slicing:
      rules: closed          # open | closed | openAtEnd
      ordered: true
      slices:
        home:
          match: { type: pattern, value: { use: home } }
        work:
          match: { type: pattern, value: { use: work } }

rules: closed means every array item must match some slice; open imposes no extra restriction; openAtEnd requires unmatched items to come last. Each slice carries its own nested constraints. This is the aspect that schema/Schematron validators famously botch, and here it is a plain object with a match predicate.

The validation algorithm over this IR is refreshingly small. Paraphrasing the FHIR Schema algorithm notes: start with a context (the set of applicable schemas — base plus every asserted profile) and the data node; for each schema, run each keyword's validator; most keywords are pure functions over a single value (type, pattern, fixed, min/max, binding); only elements and slicing need cooperative validation across a whole collection. Walk the data tree once, and at each node union the schemas that apply, collect issues, recurse. "Only slices and elements need cooperative validation" — everything else is embarrassingly parallel and, more to the point for us, embarrassingly compilable.

---

A Previous Attempt: What PR #73 Taught Us

We do not start from a blank page. In PR #73, @sandhums contributed an in-progress "FHIR validation stack" that is genuinely instructive — both in what it got right and in why, as-is, it will not merge. I want to be explicit and appreciative here: that PR is a serious piece of work and it materially informs this design. It will not be merged because it carries a contributor's company-specific code (the generator crate is named atrius-fhir-valueset-gen, after their fork), not because the approach was wrong. Several of its instincts are exactly right and we will keep them.

What PR #73 built, at a glance:

Crate it added	Role
fhir-validation-types	Shared validation vocabulary (issues, outcomes) used by generated code.
fhir-validation-gen	Build-time tool: reads StructureDefinition bundles, builds an index, emits generated Rust.
fhir-validation	Runtime library: structure, invariants, profiles/slicing/cardinality, bindings.
atrius-fhir-valueset-gen	Generates ValueSet/CodeSystem membership helpers from bundled valuesets.json.

What it got right, and we adopt:

1. Generation, not interpretation. Its fhir-validation-gen reads the same StructureDefinition bundles that helios-fhir-gen already consumes (profiles-types.json, profiles-resources.json) and emits Rust ahead of time. The invocation was literally cargo run -p fhir-validation-gen --release -- r5 <inputs...> <out-dir>. This is the right axis, and it is the axis this document doubles down on.
2. Local-first terminology with a remote fallback. Finite CodeSystems and small ValueSets were compiled into typed membership checks from the bundled valuesets.json; large or intensional value sets fell back to an async $validate-code call. This is exactly the right layering, and HFS is better positioned than the fork was — we have helios-hts in-tree as the fallback, so the "remote" call can be an in-process one.
3. Per-version dispatch. Generated glue lived under r4 / r4b / r5 / r6 with a dispatch layer, mirroring the version-feature pattern the rest of the workspace uses.
4. OperationOutcome-shaped reporting. Issues mapped to OperationOutcome, the correct and only sane public contract.

What kept it from merging, and what we change:

1. Vendor-named, vendor-shaped code. atrius-fhir-valueset-gen is a fork artifact.
2. It generated from StructureDefinition directly, into bespoke per-type Rust. PR FHIR validation stack + FHIRPath primitive id / extension support #73 emitted 18–24 part_*.rs files per version of hand-shaped validation models. That works, but it re-invents an intermediate representation that FHIR Schema already standardizes and unit-tests. We interpose the FHIR Schema IR so our generator's input is a documented, conformance-tested artifact rather than an ad-hoc in-memory index — which means our generator is simpler and its output is checkable against an external test suite.
3. A parallel primitive-metadata model. PR FHIR validation stack + FHIRPath primitive id / extension support #73 introduced PrimitiveMeta to carry primitive id/extension through FHIRPath. That need is real — invariants like ele-1 (hasValue() or (children().count() > id.count())) depend on it — but HFS's FHIRPath engine already models this: EvaluationResult carries a PrimitiveElement { id, extension } slot today. We thread through the existing type, not a new one.
4. A fourth generation crate. Four new crates (-types, -gen, -valueset-gen, runtime) is more surface than we need. This document proposes one new runtime crate plus extensions to the two codegen crates we already own.

In short: PR #73 validated the strategy (generate, don't interpret; local-first terminology; per-version dispatch) and we thank it for that. This document re-homes that strategy on top of the FHIR Schema IR and the Helios codegen crates, with no vendor code.

---

The Architecture: Compile the Spec, Don't Interpret It

The single conviction behind this design is that a StructureDefinition is source code, and validation is its compiled output. HFS already treats the spec this way for data models — helios-fhir-gen turns StructureDefinitions into Rust structs at build time; nobody reflects over a StructureDefinition at runtime to figure out that Patient.name is a Vec<HumanName>. Validation should work identically. The profile graph is known at build time. The FHIRPath invariant strings are known at build time. The binding ValueSet URLs are known at build time. There is no reason to discover any of it while a request is in flight.

The pipeline has three stages, and each reuses machinery HFS already has:

   FHIR spec bundles                    build time                         run time
   =================                    ==========                         ========

  profiles-types.json  ─┐
  profiles-resources.json├─▶ [1] SD→FHIRSchema ─▶ [2] FHIRSchema→Rust ─▶ generated validators
  profiles-others.json  ─┘      (helios-fhir-gen)     (helios-fhir-gen +      (r4.rs/r5.rs/…)
  <profile IGs>                  emits *.fhirschema     helios-fhir-macro)          │
                                     .json IR)                                      ▼
  valuesets.json ────────────▶ [1b] ValueSet compile ─────────────────────▶ terminology tables
                                (bundled finite sets)                              │
                                                                                   ▼
                                                              helios-fhirpath (invariants) ◀── HTS ($validate-code)
                                                                                   │
                                                                                   ▼
                                                                            OperationOutcome

Stage 1 — StructureDefinition → FHIR Schema. A converter (living in helios-fhir-gen, following the FHIR Schema project's documented fhir2schema transformation) reads the same bundles helios-fhir-gen already parses and emits FHIR Schema JSON documents. This stage is where the leaky snapshot problem is solved once: differentials are merged, choice types are made explicit, arrays are labeled, slicing is normalized. The output is a set of .fhirschema.json files — a checkable, standard artifact we can run the FHIR Schema conformance suite against before we ever generate a line of Rust.

Stage 2 — FHIR Schema → Rust. A generator (also in helios-fhir-gen) reads those schema documents and emits, per FHIR version, a compiled validator: static tables of element rules, a compiled list of invariant expressions per type, binding descriptors, and slice matchers. This is exactly the shape PR #73 proved out with its part_*.rs split — we keep that packaging (many small files + a dispatch module keep incremental compilation sane) but feed it from the FHIR Schema IR.

Stage 3 — runtime. A new helios-validation crate walks a resource against the compiled tables, delegating the two hard sub-problems to existing subsystems: FHIRPath invariants to helios-fhirpath (whose IntoEvaluationResult impls are already generated for every FHIR type by the FhirPath derive), and terminology to a local-first table with helios-hts as the $validate-code fallback.

The reason this is worth the codegen investment is the same reason the data-model codegen was worth it: the compiler becomes your conformance partner. A binding that references a ValueSet we failed to bundle is a build error, not a 3 a.m. pager. An invariant expression that no longer parses is caught by the FHIRPath parser at generation time. A choice type with a member we do not have a Rust variant for does not compile. The class of "the validator silently skipped a rule" bug — endemic to interpreted validators — largely evaporates.

---

Where Code Generation Comes In

This is the heart of the proposal, and it is where HFS has an unfair advantage: the two crates that would do this work, helios-fhir-gen and helios-fhir-macro, already exist, already parse full StructureDefinitions, and already emit per-type Rust for every FHIR version. We are not building a code generator. We are teaching one we own two new tricks.

What the generator already knows (and currently throws away)

helios-fhir-gen deserializes the complete ElementDefinition — not a subset. Its bootstrap model (crates/fhir-gen/src/initial_fhir_model.rs) carries every field a validator needs:

pub struct ElementDefinition {
    pub path: String,
    pub slice_name: Option<String>,
    pub slicing: Option<ElementDefinitionSlicing>,
    pub min: Option<u32>,                 // cardinality lower bound
    pub max: Option<String>,              // cardinality upper bound ("*" or N)
    pub r#type: Option<Vec<ElementDefinitionType>>,
    pub fixed: Option<ElementDefinitionDefaultValue>,
    pub pattern: Option<ElementDefinitionDefaultValue>,
    pub constraint: Option<Vec<ElementDefinitionConstraint>>,  // FHIRPath invariants
    pub binding: Option<ElementDefinitionBinding>,             // valueSet + strength
    pub is_modifier: Option<bool>,
    pub is_summary: Option<bool>,
    pub must_support: Option<bool>,
    // ... and the rest
}

pub struct ElementDefinitionConstraint {
    pub key: String,          // e.g. "pat-1"
    pub severity: String,     // "error" | "warning"
    pub human: String,
    pub expression: Option<String>,   // the FHIRPath
}

pub struct ElementDefinitionBinding {
    pub strength: String,             // "required" | "extensible" | "preferred" | "example"
    pub value_set: Option<String>,    // canonical URL
}

Here is the striking part. Today, the generator uses every one of these fields — but only to write doc comments. Walk the generated crates/fhir/src/r5.rs and you will find, on the Patient.contact field, the full text of invariant pat-1, its cardinality, and its binding strength — rendered as human-readable Markdown in a /// block. The generator computes element.min/max, formats element.constraint into a ## Constraints section, formats element.binding into a ## Binding section, and then throws the structured values away, keeping only the prose.

That prose is a validation table that has not been asked to compile. The entire codegen ask of this document is: emit those same values a second time, as machine-readable metadata instead of only as documentation.

The two macros HFS already ships

helios-fhir-macro exports three derives, and their design is the template for what we add. Every FHIR type already derives them:

• #[derive(FhirSerde)] — the FHIR-correct JSON codec, including the primitive id/extension sidecar (_field) pattern and the split primitive-array pattern.
• #[derive(FhirPath)] — generates impl IntoEvaluationResult, the bridge that lets the FHIRPath engine evaluate expressions against any resource. This is the key that unlocks invariant validation for free: every type is already FHIRPath-addressable.
• #[derive(TypeInfo)] — namespace + type name for .ofType() resolution.

Crucially, these macros already demonstrate the exact pattern a validation macro needs: static metadata emitted from a comma-list attribute. Look at how resource-level metadata already works today:

#[fhir_resource(
    choice_elements = "value,effective,onset",
    summary_fields  = "id,meta,status,code,subject,effective,value"
)]
pub struct Observation { /* ... */ }

The FhirPath derive parses those comma-joined strings (via helpers like extract_resource_summary_fields) and emits:

impl FhirResourceMetadata for Observation {
    fn choice_elements() -> &'static [&'static str] { &["value", "effective", "onset"] }
    fn summary_fields()  -> &'static [&'static str] { &["id", "meta", "status", /* ... */] }
}

That is precisely the shape validation metadata wants. We are not inventing a mechanism; we are instantiating one that already carries summary_fields and will now also carry cardinality, bindings, and invariants.

The proposal: #[derive(FhirValidate)]

The plan is a two-part change, both parts small because the hard machinery exists:

1. Extend helios-fhir-gen to emit, alongside each generated field and type, structured validation attributes — the same min, max, constraint, binding values it already formats into docs. This is a localized change: the values are already in hand at the exact line where the doc string is built.
2. Add #[derive(FhirValidate)] to helios-fhir-macro, which parses those attributes with the same helper style as extract_resource_* and emits an impl FhirValidate plus a static element-definition table.

The generated surface would look like this — an ordinary FHIR struct, now carrying its own conformance rules as attributes:

#[derive(FhirSerde, FhirPath, TypeInfo, FhirValidate)]
#[fhir_validate(
    profile   = "http://hl7.org/fhir/StructureDefinition/Patient",
    invariants = "pat-1"     // keys; expressions live in the const table below
)]
pub struct Patient {
    #[fhir_element(min = 0, max = "*")]
    pub name: Option<Vec<HumanName>>,

    #[fhir_element(min = 0, max = "1",
        binding(strength = "required",
                value_set = "http://hl7.org/fhir/ValueSet/administrative-gender"))]
    pub gender: Option<CodeType>,

    #[fhir_element(min = 0, max = "1")]
    #[fhir_choice(base = "multipleBirth",
                  choices = "multipleBirthBoolean,multipleBirthInteger")]
    pub multiple_birth: Option<PatientMultipleBirth>,

    #[fhir_element(min = 0, max = "*")]
    #[fhir_reference(targets = "Organization,Practitioner,PractitionerRole")]
    pub general_practitioner: Option<Vec<Reference>>,
    // ...
}

And the derive would emit a static, zero-runtime-cost description of the type plus its validate entry point:

impl FhirValidate for Patient {
    fn element_defs() -> &'static [ElementDef] {
        // emitted verbatim from the FHIR Schema IR — no allocation, no parsing at runtime
        &[
            ElementDef {
                name: "name", shape: Shape::Array, min: 0, max: Card::Many,
                ty: TypeRef::Complex("HumanName"), binding: None, refers: &[],
            },
            ElementDef {
                name: "gender", shape: Shape::Scalar, min: 0, max: Card::One,
                ty: TypeRef::Primitive("code"),
                binding: Some(Binding {
                    strength: Strength::Required,
                    value_set: "http://hl7.org/fhir/ValueSet/administrative-gender",
                }),
                refers: &[],
            },
            // ...
        ]
    }

    fn invariants() -> &'static [Invariant] {
        &[Invariant {
            key: "pat-1",
            severity: Severity::Error,
            // pre-parsed at generation time; stored as a compiled FHIRPath AST handle
            expression: "name.exists() or telecom.exists() or address.exists() or organization.exists()",
            human: "SHALL at least contain a contact's details or a reference to an organization",
        }]
    }
}

Everything the runtime validator needs is now a &'static table baked into the binary. No StructureDefinition is parsed at runtime. No profile graph is walked. The cardinality check for gender is a comparison against a const. The binding check knows its ValueSet URL and its strength without a lookup. The invariant is a pre-parsed FHIRPath handle away from evaluation.

This mirrors the FHIR Schema elements tree one-to-one — which is the point. Stage 2 of the pipeline is a near-mechanical transliteration of a .fhirschema.json document into these attributes, and because the intermediate form is standardized and unit-tested, the transliteration is checkable.

---

Designing the Rust Traits

With the model and the codegen strategy established, here are the runtime abstractions. I present them the way #104 did — the vocabulary first, then the contracts — and I flag which pieces are new versus reused.

The vocabulary of a validation result

The output is an OperationOutcome, but internally we accumulate typed issues so that the engine, the tests, and the REST layer all speak the same language. Nothing here is FHIR-version-specific; these are the stable currency of the subsystem.

/// The severity of a single validation issue. Maps directly to
/// OperationOutcome.issue.severity and governs whether a resource is rejected.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Severity {
    Fatal,
    Error,
    Warning,
    Information,
}

/// A single validation finding, addressed to a location in the instance.
#[derive(Debug, Clone)]
pub struct ValidationIssue {
    pub severity: Severity,
    /// Machine-readable issue type (OperationOutcome.issue.code):
    /// `structure`, `required`, `value`, `code-invalid`, `invariant`, ...
    pub code: IssueType,
    /// FHIRPath location of the problem, e.g. `Patient.contact[0]`.
    pub expression: String,
    /// Human-readable explanation (OperationOutcome.issue.diagnostics).
    pub diagnostics: String,
    /// The constraint key or binding that produced this, when applicable.
    pub source: Option<String>,
}

/// The accumulated outcome of validating one resource.
#[derive(Debug, Clone, Default)]
pub struct ValidationOutcome {
    pub issues: Vec<ValidationIssue>,
}

impl ValidationOutcome {
    /// A resource is accepted iff it produced no Fatal or Error issues.
    /// Warnings and Information never block; they are advisory.
    pub fn is_success(&self) -> bool {
        !self.issues.iter().any(|i| matches!(i.severity, Severity::Fatal | Severity::Error))
    }

    /// Render to a version-appropriate FHIR OperationOutcome.
    pub fn to_operation_outcome(&self, version: FhirVersion) -> SofOperationOutcome { /* ... */ }
}

The compiled type description

This is the static shape the FhirValidate derive emits — the runtime face of the FHIR Schema elements tree. It is deliberately all &'static: the whole point of compiling is that describing a Patient's rules costs zero allocations.

/// Whether an element is an array or a scalar — the FHIR Schema `array`/`scalar`
/// flags, which are mutually exclusive.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Shape { Scalar, Array }

/// Cardinality upper bound.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Card { Zero, One, Many, Exactly(u32) }

/// A terminology binding: which ValueSet, and how strictly.
#[derive(Debug, Clone, Copy)]
pub struct Binding {
    pub strength: Strength,      // Required | Extensible | Preferred | Example
    pub value_set: &'static str, // canonical URL
}

/// One element's compiled rule set. Emitted as a `&'static` array per type.
#[derive(Debug, Clone, Copy)]
pub struct ElementDef {
    pub name: &'static str,
    pub shape: Shape,
    pub min: u32,
    pub max: Card,
    pub ty: TypeRef,
    pub binding: Option<Binding>,
    pub refers: &'static [&'static str],  // allowed Reference targets
    pub slicing: Option<&'static Slicing>,
}

/// A pre-parsed FHIRPath invariant.
#[derive(Debug, Clone, Copy)]
pub struct Invariant {
    pub key: &'static str,
    pub severity: Severity,
    pub expression: &'static str,
    pub human: &'static str,
}

/// Implemented by every generated FHIR type via `#[derive(FhirValidate)]`.
/// The tables are static; there is no per-instance state.
pub trait FhirValidate {
    fn profile_url() -> &'static str;
    fn element_defs() -> &'static [ElementDef];
    fn invariants() -> &'static [Invariant];
}

The validator trait

The engine itself is a trait, because — exactly as in #104 and #45 — the concrete implementation is a deployment choice. The default resolves terminology locally and falls back to HTS; a stricter deployment might reject on any preferred miss; a lenient one might treat unknown profiles as warnings. The handler does not care which is wired in.

/// The core validation engine. Version-agnostic at the trait level;
/// concrete impls are generated per FHIR version.
#[async_trait]
pub trait Validator: Send + Sync {
    /// Validate a resource against its base definition plus any profiles
    /// asserted in `meta.profile` and any passed explicitly.
    async fn validate(
        &self,
        resource: &ValidatableResource,
        profiles: &[ProfileCanonical],
        options: &ValidationOptions,
    ) -> ValidationOutcome;
}

/// Knobs an operator or a `$validate` caller can turn.
#[derive(Debug, Clone)]
pub struct ValidationOptions {
    /// How to treat a `meta.profile` we do not have compiled in:
    /// error (strict), warning (lenient), or ignore.
    pub unknown_profile: UnknownProfilePolicy,
    /// Whether to consult the remote terminology fallback, or stay local-only.
    pub terminology: TerminologyMode,
    /// The `mode` from the $validate operation: create | update | delete | profile.
    pub mode: ValidationMode,
}

The two delegated sub-problems

The design's leverage comes from delegating the two hardest aspects to subsystems HFS already owns. Both are traits so that tests can stub them and deployments can swap them.

Invariants → FHIRPath. Because every FHIR type already derives FhirPath and thus IntoEvaluationResult, evaluating a constraint is: convert the node to an EvaluationResult, evaluate the pre-parsed expression against it, expect a boolean. The engine binds %resource and %rootResource per the FHIR Schema constraint semantics.

/// Evaluates compiled FHIRPath invariants. The default impl wraps
/// `helios-fhirpath`; the resource is already `IntoEvaluationResult`.
pub trait InvariantEvaluator: Send + Sync {
    fn evaluate(
        &self,
        invariant: &Invariant,
        context: &EvaluationResult,   // %context — the node the constraint is attached to
        resource: &EvaluationResult,  // %resource / %rootResource
    ) -> Result<bool, InvariantError>;
}

Bindings → local-first terminology, HTS fallback. This is the trait that lets us honor binding strength correctly and keep the single-binary deployment terminology-capable without a network hop.

/// Resolves whether a coded value is in a bound ValueSet. The default impl
/// checks generated local membership tables first (finite CodeSystems and
/// small ValueSets compiled from the bundled valuesets.json), and only on a
/// miss consults `helios-hts` via an in-process `$validate-code`.
#[async_trait]
pub trait TerminologyBinder: Send + Sync {
    async fn validate_code(
        &self,
        value_set: &str,
        code: &Coding,
    ) -> BindingResult;
}

/// The outcome of a binding check, already aware that the *caller* will
/// downgrade severity based on the binding strength.
pub enum BindingResult {
    InValueSet,
    NotInValueSet,
    /// The ValueSet could not be resolved (not bundled, server unreachable).
    /// The caller decides whether this is a warning or an error per strength.
    Undecidable(UndecidableReason),
}

Two design notes that always come up in review:

Why is BindingResult three-valued instead of a bool? Because "I could not check" is a distinct and common outcome — an intensional ValueSet we did not bundle, or a terminology server that timed out — and it must not be silently conflated with "the code is invalid." The binding strength then decides the severity: an Undecidable on a required binding is a warning ("unable to confirm"), while a definite NotInValueSet on the same binding is an error. Collapsing this to a boolean is how validators end up either failing valid data or passing invalid data.

Why delegate invariants rather than compile them to Rust? Because FHIRPath is a real language with a real evaluator we already ship, and re-implementing its semantics in generated match-arms would be a second, divergent FHIRPath engine — the exact duplication PR #73's PrimitiveMeta taught us to avoid. We pre-parse the expressions at generation time (so a broken expression fails the build) but evaluate them through the one canonical engine.

---

The REST Layer: The $validate Operation

The public surface is the standard $validate operation, wired in the established HFS handler style: generic over the storage/validator, taking a TenantExtractor, returning RestResult<Response>. Note that $validate is unusual among FHIR operations in that a "failed" validation is still an HTTP 200 OK — the OperationOutcome is the successful response; the issues live inside it.

pub async fn validate_handler<V>(
    State(state): State<AppState<V>>,
    Path((resource_type, op)): Path<(String, String)>,
    tenant: TenantExtractor,
    ctx: RequestContextExtractor,
    Query(params): Query<ValidateParams>,   // ?profile=...&mode=...
    body: FhirResourceBody,
) -> RestResult<Response>
where
    V: Validator + Send + Sync,
{
    let resource = body.into_validatable(&resource_type)?;
    let mut profiles = params.profiles();
    profiles.extend(resource.meta_profiles());   // meta.profile is implicit

    let outcome = state
        .validator()
        .validate(&resource, &profiles, &params.options())
        .await;

    // $validate ALWAYS returns 200 with an OperationOutcome — even on error.
    let oo = outcome.to_operation_outcome(tenant.fhir_version());
    Ok(fhir_json_response(StatusCode::OK, &oo)?)
}

Two observations that are easy to miss:

It does not resolve references against the live store. Whether Observation.subject points at a Patient that actually exists is a business rule, not structural validation, and it belongs to the persistence layer's transaction path — not here. This handler validates the resource in isolation, which is what $validate without a mode means.

The same validator can run inline on writes. The interesting future wiring is not the standalone operation — it is an optional HFS_VALIDATE_ON_WRITE posture where create/update run the resource through the exact same Validator before it is persisted, rejecting non-conformant data at the door with a 422 Unprocessable Entity and the OperationOutcome as the body. That is a policy decision (validation is expensive; not every deployment wants it on the hot path), which is why it is a configuration flag and not a hardcoded behavior — but the engine is identical either way.

---

Slicing and Profiles: The Hard Part

Just as group export was where the bulk spec's edges showed, slicing is where validation's edges show — and it is the aspect the spec itself admits schema-based validators only "partially" handle. The FHIR Schema representation makes it tractable, but it does not make it trivial, and honesty compels me to name where the difficulty concentrates.

The core of slicing is: an array element carries a slicing object with named slices, each a match predicate (a pattern or a discriminator), a set of nested constraints, and a rules mode. Validating it means partitioning the actual array into slice-buckets by evaluating each item against each slice's match, then checking each bucket against its slice's cardinality and constraints, then applying the rules: closed rejects any unmatched item, openAtEnd requires unmatched items to trail, open allows anything extra. The FHIR Schema algorithm notes are explicit that this is the one place — along with elements — that needs "cooperative validation" over the whole collection rather than element-by-element.

Three things make this genuinely hard, and each gets an explicit position:

Discriminators beyond pattern. FHIR discriminators come in flavors — value, pattern, type, profile, exists. The FHIR Schema match object handles pattern cleanly; type and profile discriminators require recursively deciding whether an item validates against a target schema, which means slice-matching and validation are mutually recursive. We will implement pattern, value, and exists first (they cover the overwhelming majority of real profiles, including all of US Core's common slices) and stage type/profile discriminators behind them.

Re-slicing. A profile can slice a slice. The FHIR Schema model nests this naturally (a slice's element can itself carry slicing), and our compiled ElementDef → Slicing → Slice tree nests the same way — but the runtime partition logic has to recurse, and the error messages have to name the full slice path (Patient.identifier:mrn/type) or they are useless to the user.

Profile composition. When a resource asserts multiple profiles (or a profile whose base is itself a profile), the context at each node is the union of all applicable schemas, and their constraints all apply simultaneously. The FHIR Schema algorithm's "set of schemas in context" is exactly this union, and our engine models it as a Vec<&'static [ElementDef]> gathered by walking the base chain of every asserted profile at generation time — so the union is precomputed wherever the profile set is statically known, and assembled at runtime only for dynamically-asserted meta.profile combinations.

The Bulk-Cohort-style dynamic case — a resource asserting an arbitrary profile we compiled but did not anticipate combining — is handled, but the fully general "validate against a profile the server has never seen, supplied in the request" case (the $validate operation technically permits a contained StructureDefinition) is out of scope for the first cut. It requires a runtime SD→FHIRSchema→validator path — essentially shipping Stage 1 and 2 of the pipeline as a runtime library — and it deserves its own design once the compiled path is solid.

---

Configuration: What Operators Will Touch

Variable	Default	Description
HFS_VALIDATION_ENABLED	true	Master switch for the $validate operation. When false, the endpoint returns 501 Not Implemented.
HFS_VALIDATE_ON_WRITE	false	When true, create/update validate before persisting and reject non-conformant resources with 422. Off by default — validation is not free.
HFS_VALIDATION_UNKNOWN_PROFILE	warning	Posture on a meta.profile we did not compile: error, warning, or ignore.
HFS_VALIDATION_TERMINOLOGY	local-first	local-first (bundled tables, HTS fallback), local-only (no remote calls), or remote-required (fail if HTS is unreachable).
HFS_VALIDATION_TERMINOLOGY_URL	(from HTS config)	Endpoint for the $validate-code fallback when distinct from the in-process HTS.
HFS_VALIDATION_TERMINOLOGY_TIMEOUT	2000	Milliseconds. How long to wait on a remote $validate-code before returning Undecidable.
HFS_VALIDATION_BEST_PRACTICE	warning	Severity for bpr-* best-practice invariants: error, warning, or ignore.
HFS_VALIDATION_MAX_DEPTH	50	Recursion guard for deeply nested / elementReference structures.

The default posture — validation available as an operation, off on the write path, lenient on unknown profiles, local-first terminology — is the one that makes a fresh HFS install useful without surprising anyone. A deployment tightens into HFS_VALIDATE_ON_WRITE=true and HFS_VALIDATION_UNKNOWN_PROFILE=error when it is ready to enforce, by changing configuration, not code.

---

Conformance Testing

Validation has an unusually good conformance story, because two independent test corpora exist and we intend to be green on both:

• The FHIR Schema test suite. Because Stage 1 of the pipeline emits standard FHIR Schema documents, we can run the FHIR Schema project's conformance tests — a JSON-Schema-style corpus of (schema, instance, expected-outcome) cases — against our IR before any Rust is generated. This validates the hardest and most error-prone stage (SD→FHIRSchema, including snapshot merging and slicing normalization) against an external oracle.
• The official FHIR validation examples. The spec ships thousands of example resources, many deliberately invalid, each with an expected outcome. PR FHIR validation stack + FHIRPath primitive id / extension support #73 already demonstrated wiring these in as integration tests ("heavy coverage lives in integration tests: bindings, profiles, invariants, examples"). We adopt that corpus wholesale.
• Inferno. The Inferno test kits exercise $validate behavior end-to-end for US Core and other IGs; we fold validation into the same nightly Inferno job the bulk-export discussion proposed.

The plan, mirroring #104's testing posture:

• A cargo xtask fhirschema-conformance target that runs the FHIR Schema corpus against the Stage-1 converter output.
• Integration tests in helios-validation that validate the official invalid-example corpus per version and assert the exact OperationOutcome issue set.
• An Inferno US Core validation run added to .github/workflows/inferno.yml as a nightly job, with a conformance badge in the crate README.

These are slow and authoritative — nightly CI, not per-PR.

---

What's Not in Scope (Yet)

A handful of things are deliberately deferred. None are blockers; each is a follow-up.

• Questionnaire / QuestionnaireResponse validation. Validating a response against its questionnaire (enable-when logic, answer-option constraints, item cardinality) is a distinct engine with its own spec surface. It reuses the FHIRPath dependency but little else.
• Runtime SD-supplied profiles. Validating against a StructureDefinition supplied in the request (rather than compiled ahead of time) requires shipping the Stage 1/2 pipeline as a runtime library. Worth doing; not first.
• type and profile slice discriminators. pattern / value / exists first; the recursive discriminators after.
• Reference resolution (does the target actually exist in the store?). This is a business rule owned by the persistence/transaction layer, deliberately not the validation engine. The seam is the Validator producing a structural verdict and the write path layering existence checks on top.
• Terminology $expand of large intensional ValueSets at build time. We compile finite code systems and small value sets; large intensional sets resolve at runtime via HTS. Pre-expanding them into the binary is a size/speed trade we will revisit.
• mustSupport enforcement. mustSupport is a producer/consumer contract, not an instance-validity rule in the base spec; we surface it as metadata and let IG-specific policies act on it, rather than baking a severity in.

---

Proposed Next Steps

The traits and codegen sketched above are a starting point. To move toward implementation:

1. Land the StructureDefinition → FHIR Schema converter in helios-fhir-gen and get it green against the FHIR Schema conformance suite for R4 first. This is the highest-risk stage; prove it in isolation before generating any Rust.
2. Emit the FHIR Schema IR as checked-in .fhirschema.json artifacts per version, the way the models and the compartment tables are already generated — so the IR is reviewable in PRs.
3. Extend helios-fhir-gen to emit structured #[fhir_element(...)] / #[fhir_validate(...)] attributes alongside the existing doc comments. The values are already computed; this is promotion from prose to tokens.
4. Add #[derive(FhirValidate)] to helios-fhir-macro, following the FhirResourceMetadata precedent, emitting the &'static ElementDef / Invariant tables.
5. Create the helios-validation crate with the Validator, InvariantEvaluator, and TerminologyBinder traits and the version-feature layout (R4 / R4B / R5 / R6) the rest of the workspace uses.
6. Wire the local-first terminology tables by generating membership helpers from the bundled valuesets.json (re-homing PR FHIR validation stack + FHIRPath primitive id / extension support #73's capability under Helios naming, backed by helios-hts for the fallback).
7. Implement structure + cardinality + value-domain validation — the embarrassingly-parallel keywords — end to end, with the official example corpus as the test oracle.
8. Wire invariants through helios-fhirpath, binding %resource / %rootResource / %context per the FHIR Schema constraint semantics, pre-parsing expressions at generation time.
9. Implement bindings with three-valued BindingResult and strength-aware severity, local-first with the HTS fallback.
10. Implement slicing (pattern / value / exists discriminators, open / closed / openAtEnd), then profile composition over the base chain.
11. Wire the $validate REST handler in helios-rest, returning 200 OK + OperationOutcome, honoring ?profile= and ?mode=.
12. Add the Inferno US Core validation run to the nightly workflow and publish the badge.

---

Closing Thoughts

Validation is the API that turns a FHIR server from a store that accepts data into a platform that stands behind it. Every downstream consumer — the SQL-on-FHIR views, the terminology lookups, the bulk exports feeding research and AI pipelines — inherits the quality of what validation let through. A server that cannot validate is a server that has quietly outsourced its data-quality guarantees to whoever happened to write the ingesting client, which is to say, to no one.

The architecture proposed here is built around two convictions. First, that a StructureDefinition is source code, and the right time to process it is build time — compiled into &'static Rust tables via the code-generation machinery HFS already owns, so that the compiler becomes a conformance partner and "the validator silently skipped a rule" stops being a class of bug. Second, that the two genuinely hard aspects — FHIRPath invariants and terminology bindings — should be delegated to the subsystems HFS already ships (helios-fhirpath and helios-hts) rather than re-implemented, so the validation engine stays small and the hard parts stay canonical.

The Rust type system and its macro machinery make both convictions enforceable. Because every FHIR type already derives FhirPath, every resource is already FHIRPath-addressable, and invariant evaluation is nearly free. Because helios-fhir-gen already parses every ElementDefinition field — and today spends them only on doc comments — teaching it to emit those same values as #[derive(FhirValidate)] attributes is promotion, not invention. And because FHIR Schema gives us a standardized, unit-tested intermediate representation, the riskiest stage of the whole enterprise — turning the spec's leaky snapshots into something checkable — can be verified against an external oracle before we generate a single line.

I want to close by thanking @sandhums, whose PR #73 did the unglamorous work of proving this strategy out end to end. That PR will not merge as-is — it carries a fork's vendor-specific code — but its instincts were right: generate, don't interpret; local-first terminology with a remote fallback; per-version dispatch; OperationOutcome as the contract. This document re-homes those instincts on the FHIR Schema IR and the Helios codegen crates, with no vendor code, and points them at the conformance suites that will tell us, every night, whether HFS is a validator the rest of the ecosystem can trust.

Thank you for reading. I look forward to the discussion.

• Steve

[sandhums]

Thanks @smunini , I really appreciate both the detailed write-up and the acknowledgement of my earlier work. It was encouraging to see that we independently converged on many of the same architectural principles—compile-time generation, local-first terminology validation, version-specific dispatch, FHIRPath for invariants, and OperationOutcome as the public contract.

I also think the move towards FHIR Schema as the intermediate representation is a sensible direction for HFS. It fits well with the existing code generation pipeline and should make the implementation cleaner and easier to maintain upstream.

One area where my implementation ended up evolving a little differently was around implementation guides and profile management. Once I started looking at real-world deployments (particularly national IGs that are revised independently of server releases), I found it useful to introduce a runtime profile registry and package materialization layer alongside the generated core validators. That allows servers to load curated IG packages without requiring a rebuild every time a profile package changes.

For an upstream open source HFS server, compile-time profiles are probably the right place to start. I do wonder whether, as HFS matures, you’ll eventually encounter the same requirement from users who need to support multiple customer-specific or frequently updated IGs. If that happens, some form of runtime profile/package registry may become a natural extension rather than a replacement for the generated validators.

In any case, I’m glad to see validation becoming a first-class part of HFS, and I’m happy that my earlier work could help shape the direction. I’m looking forward to seeing how the implementation evolves and would be happy to contribute ideas or experience as those more advanced profile-management scenarios come into scope.