node-schematron

Common errors

• ENOENT: no such file or directory, stat '/path/to/include/files/file.xml'

  cause A Schematron schema uses `<include href="file.xml" />` but the `resourceDir` option was not provided or points to an incorrect location, preventing the included file from being found.
  fix Ensure the `resourceDir` option in `Schema.fromString()` or `Schema.fromFileSync()` points to the correct directory containing the included Schematron files. For CLI, verify `schematronLocation` and any paths referenced within the schema.

• Error: XPath error: "Cannot convert XdmValue to single value: multiple values encountered"

  cause An XPath expression in an `assert` or `report` test, or a `value-of` select, evaluates to a sequence of multiple items where a single item is expected (e.g., trying to compare `//element` with a string, when `//element` matches multiple elements).
  fix Refine the XPath expression to ensure it selects a single node or atomic value, or explicitly handle sequences using XPath functions like `string-join()`, `count()`, `head()`, `tail()`, or predicates like `[1]` to select a specific item from the sequence.

• Error: (XPath error) Cannot parse XQuery/XPath expression: Unexpected token "|" at position X

  cause A syntax error in an XPath expression within a Schematron rule, often due to a typo or incorrect XPath syntax for the XPath 3.1 query language.
  fix Carefully review the XPath expression for syntax errors. Validate the XPath against an XPath 3.1 validator. Pay attention to common pitfalls like incorrect axis specifiers, mismatched parentheses, or improper use of operators.

Warnings

• gotcha The underlying XPath 3.1 implementation, `fontoxpath`, is noted as not yet feature-complete. Users relying on advanced or less common XPath 3.1 functions might encounter unsupported features or unexpected behavior.
  Fix: Consult the `fontoxpath` documentation or `node-schematron` unit tests for specific supported XPath features. Consider implementing custom XPath functions using `registerCustomXPathFunction` for unsupported scenarios.
• gotcha Schematron's rule matching behavior can be counter-intuitive: within a single pattern, a node will only match the *first* rule whose context matches it. Subsequent rules in the same pattern for that node will not be evaluated, even if their contexts also match.
  Fix: Structure your Schematron patterns carefully, ordering rules from most specific to least specific. Use multiple patterns or refactor rules if multiple independent checks are required for the same node.
• gotcha The library explicitly states that XSLT functions (`<xsl:function>`) are not supported. While there was a feature branch, it remains unimplemented.
  Fix: Avoid using `<xsl:function>` elements in your Schematron schemas. If custom logic is required, define JavaScript-based custom XPath functions using `registerCustomXPathFunction`.
• gotcha Some ISO/IEC 19757-3 2016 (Schematron) attributes are not supported, including `@abstract`, `@diagnostics`, `@icon`, `@see`, `@fpi`, `@flag`, `@role`, and `@subject` in certain contexts.
  Fix: Be aware of these unsupported attributes when authoring Schematron schemas, as they will be ignored by `node-schematron`. Adjust schemas to use supported constructs or external reporting mechanisms if these features are critical.
• gotcha When using `resourceDir` for schema includes, ensure the path is correct and accessible. Incorrect paths will lead to `file not found` errors, and the CLI tool may default to `*.xml` if `globPattern` is not used correctly or `schematronLocation` is relative and ambiguous.
  Fix: For programmatic use, always provide an absolute or correctly resolved path to `resourceDir`. For CLI use, double-check `schematronLocation` and `globPattern` arguments, using absolute paths for clarity where possible. Use `--files` for explicit file lists if globbing is problematic.

Install

• npm install node-schematron npm
• yarn add node-schematron yarn
• pnpm add node-schematron pnpm

Imports

• Schema
  wrong:

  const { Schema } = require('node-schematron');

  correct:

  import { Schema } from 'node-schematron';

  ESM is preferred in modern Node.js and browser projects, but CommonJS `require` is also supported for older Node.js environments as shown in the README example. TypeScript types are included.
• registerCustomXPathFunction
  wrong:

  const { registerCustomXPathFunction } = require('node-schematron');

  correct:

  import { registerCustomXPathFunction } from 'node-schematron';

  Used to extend XPath capabilities with custom JavaScript functions. This utility is an alias for the same function in `fontoxpath`.
• validateString
  wrong:

  Schema.validateString('<xml/>', options);

  correct:

  schema.validateString('<xml/>', options);

  This is a method on an *instance* of `Schema`, not a static method on the `Schema` class itself. Always instantiate `Schema` first.

Quickstart

This quickstart demonstrates how to initialize a Schematron `Schema` from a string and validate an XML string, logging the results.

import { Schema } from 'node-schematron';

const schematronSchema = `
<schema xmlns="http://purl.oclc.org/dsdl/schematron">
	<pattern>
		<rule context="thunder">
			<let name="lightning" select="@foo"/>
			<report test="$lightning = 'bar'">
				Skeet boop <value-of select="$lightning" />
			</report>
			<assert test="@type = 'storm'">
				Thunder must have a 'type' attribute with value 'storm'.
			</report>
		</rule>
		<rule context="xml">
			<assert test="count(thunder) > 0">
				XML document must contain at least one thunder element.
			</assert>
		</rule>
	</pattern>
</schema>`;

const schema = Schema.fromString(schematronSchema);

const xmlToValidate = `
<xml foo="err">
	<thunder foo="bar" type="storm" />
</xml>`;

const results = schema.validateString(xmlToValidate, { debug: true });

console.log(JSON.stringify(results, null, 2));
/* Expected Output for the report (assertion passes):
[
  {
    "isReport": true,
    "context": "<thunder foo="bar" type="storm"/>",
    "message": "\n\t\t\t\tSkeet boop bar\n\t\t\t"
  }
]
*/