Schematron Validation

Relevant source files

• .claude/docs/error-formatting.md
• .claude/docs/validation-pipeline.md

The schematron package implements a rules-based XML validation engine that complements grammar-based validators like XSD and RELAX NG. It targets complex, context-sensitive rules by leveraging XPath for expressing conditions and message generation. The package follows a compile-then-validate pattern, parsing the Schematron XML into an internal Schema structure before applying the rules to an XML document. Key features include three-phase parsing (title, namespaces, patterns), the rule-assert-report model, message interpolation with embedded XPath, scoped variable bindings via <let>, and XPath-based assertion evaluation.

---

Compilation Pipeline

Schematron compilation involves transforming the declarative XML form of a Schematron schema into a runtime representation with compiled XPath expressions. This three-phase parse strategy organizes schema information progressively, ensuring static namespaces and XPath expressions are available for validation.

Three-Phase Parsing

The compilation proceeds in three distinct phases:

1. Phase 1 – Title Extraction
   The parser first extracts the optional <title> element's text content from the root <schema>. This title describes the schema and is stored as a string property on the Schema struct.

2. Phase 2 – Namespace Registration
   The package processes all <ns> child elements that declare namespace prefix-to-URI bindings. These mappings populate the namespaces map on Schema, establishing a static, global namespace context used by all XPath expressions during validation.

3. Phase 3 – Patterns and Rules
   Finally, it collects all <pattern> elements, each containing multiple <rule>s. Each rule declares a context XPath expression to select nodes on which assertions and reports apply.

   Within each rule:

   • Zero or more <let> declarations bind variables to XPath expressions with lexical scoping.
   • One or more <assert> elements specify tests that fail validation if their XPath test evaluates to false.
   • One or more <report> elements specify tests that fail if their XPath test evaluates to true.

For all applicable XPath expressions — in context, test, and select attributes — the package uses the xpath3 engine to compile them into *xpath.Expression for efficient runtime evaluation.

This phased approach ensures namespace mappings are established prior to compiling XPath expressions, maintaining correctness and reducing repeated work during validation.

Message Interpolation

Validation messages inside <assert> and <report> elements are not treated as raw strings but parsed into a sequence of typed messagePart values:

• Text literals: Simple string components appearing verbatim in the final message.
• <name path="..."/>: Produces the QName of the current node or a node selected by XPath relative to the context node.
• <value-of select="..."/>: Evaluates an XPath expression and inserts its string value dynamically.

These components are concatenated during validation to produce clear, context-sensitive error or report messages.

---

Validation Engine

The schematron package performs validation by iterating all compiled patterns and applying their rules against the target XML document.

Execution Flow

1. Create XPath Context:
   Each validation run starts by creating an XPath evaluation context xpath3.NewContext() seeded with the schema's static namespace bindings.

2. Pattern and Rule Matching:
   For every rule, the contextExpr XPath expression is evaluated against the input document to obtain the subset of nodes (context nodes) for which this rule applies.

3. Let Variable Binding:
   For each node selected by the context expression:

   • All <let> expressions are evaluated sequentially.
   • Their results are stored in a per-node variable map attached to the XPath context.
   • Later variables can reference earlier ones, allowing complex, reusable expressions to be factored out.

4. Test Evaluation:
   Each <assert> or <report> test is evaluated as follows:

   • <assert test="condition"/>: If the expression evaluates to false (Effective Boolean Value), the assertion has failed and a validation error is recorded.
   • <report test="condition"/>: If the expression evaluates to true, this is considered a failure condition as well.

5. Message Formatting and Error Reporting:
   On failure, the message template parts are interpolated, substituting dynamic names and evaluated expressions. A ValidationError is constructed with detailed location info and the generated message. This error is delivered to the configured ErrorHandler.

---

Data Model and Entities

The internal data model closely represents the Schematron XML, with explicit support for XPath expressions compiled to the xpath3 package.

XML Element	Go Type / Field	Description
<schema>	schematron.Schema	Root container holding namespaces and patterns
<ns prefix="x" uri="...">	Schema.namespaces map[string]string	Namespace prefix to URI map (static XPath namespace context)
<pattern>	schematron.pattern	Group containing multiple rules
<rule context="...">	schematron.rule	Defines rule context XPath, lets, asserts, reports
<let>	schematron.letBinding	Scoped variable binding with compiled XPath expr
<assert test="...">	schematron.test	Assertion with test XPath expression and message parts
<report test="...">	schematron.test	Report test, triggers error if condition true

---

System Architecture and Data Flow

Natural Language to Code Entity Mapping

This diagram illustrates how the Schematron XML constructs map directly to key Go structs and types, including XPath 3.1 compiled expressions.

Sources: schematron/schematron.go50-110

---

Validation Execution Pipeline

This flow shows the full pipeline from Schematron XML parsing, compilation of rules and tests to runtime validation of an XML document, including let bindings and message interpolation.

Sources: schematron/validate.go20-90

---

Key Functions and Types

• schematron.Parse(ctx context.Context, doc *helium.Document) (*Schema, error)
  Parses the root <schema> element, running three-phase parsing and compiling XPath expressions for rules, lets, asserts, and reports. Sources: schematron/schematron.go40-42

• compilePattern(patNode Node) (*pattern, error)
  Parses a <pattern> element node extracting its rules. Sources: schematron/schematron.go112

• compileRule(ruleNode Node) (*rule, error)
  Compiles a single <rule> element, including compiling the context XPath and its nested let/test elements. Sources: schematron/schematron.go130

• compileTest(testNode Node) (*test, error)
  Parses <assert> or <report>, compiles test XPath expressions and parses message parts. Sources: schematron/schematron.go160

• Validate(ctx context.Context, schema *Schema, doc *helium.Document) error
  The main validation function which runs all patterns and rules on the document, evaluates tests with let bindings, aggregates and reports errors. Sources: schematron/validate.go20

• (mp messagePart) Interpolate(ctx context.Context, node Node, lets map[string]any) string
  Interpolates message components, substituting XPath name or value-of evaluations in the current context. Sources: schematron/schematron.go200

---

Let Variable Scoping

<let> elements inside a <rule> declare XPath expressions bound to a variable name, which are:

• Evaluated in order, per node selected by the rule's context.
• Stored in a map accessible to XPath expression evaluations of subsequent <let>, <assert>, and <report> tests.
• Scoped per rule evaluation, preventing cross-contamination between rules or contexts.
• Used to factor complex expressions into reusable named variables for clearer test conditions.

This scoping mechanism extends XPath's evaluation context with custom-defined external variables handled by the package's XPath environment.

---

XPath-Based Assertion Evaluation

Schematron validation hinges on XPath expressions:

• The context XPath expression of a rule selects the set of nodes for which the rule applies.
• Each <assert> and <report> contains a test XPath expression evaluated under the current node.
• <value-of> elements in messages use select XPath expressions to extract values dynamically.

The package employs the xpath3 engine, supporting XPath 3.1 fully, compiling all expressions at parse-time for maximum runtime efficiency.

During validation:

• The evaluation context is preloaded with the static namespaces from the schema.
• Let variables are bound as external variables accessible by name.
• The current node is set as the evaluation context item.
• XPath expressions produce values or boolean results used to decide validation passes/fails.

---

Error Reporting and Message Interpolation

Upon test failures, the package generates ValidationError instances that:

• Include detailed location info (file, line number, element name).
• Carry the message with interpolated dynamic parts for clarity.
• Record the XPath location in the document where the failure occurred.
• Are delivered via the configured ErrorHandler interface.

The interpolation process involves concatenating:

• Plain text parts.
• Resolved <name> QNames from the current or selected node.
• <value-of> XPath expression results converted to strings.

The schematronError() function in schematron/errors.go formats these errors as {file}:{line}: element {elem}: schematron error : {path} line {line}: {msg}\n, noting that the line number appears twice. schematron/errors.go10 Validation returns a sentinel error (ErrValidationFailed) on any failed assertion or report, allowing callers to detect overall outcome easily.

Sources: schematron/errors.go10

---

Summary

The schematron package in helium provides a robust rule-based XML validation facility built on XPath 3.1. It rigorously separates parsing and compilation from execution, supports rich, XPath-aware message interpolation, and manages variable scoping cleanly. Its design allows expressive, complex validation rules with efficient runtime execution, suitable for demanding XML validation scenarios.

---

Sources:
schematron/schematron.go30-110
schematron/validate.go20-90
.claude/docs/validation-pipeline.md120-160
.claude/docs/error-formatting.md70-80