Skip to content
mgbilbyPublic

About

Rust-fast tei-xml validation

Resources

Contributing

Security policy

Stars

3 stars

Watchers

0 watching

Forks

Repository files navigation

teixml

crates.io Documentation License: MIT Rust 1.88+ DOI

Validate TEI XML documents against RELAX NG schemas and the Schematron rules they embed, in pure Rust — a library (teixml) and a command-line tool (tei-rs), with no Java or libxml2 needed.

  • Gives the same verdicts as Jing, the reference RELAX NG validator, on every bundled test document (241 documents from 50 TEI projects and the TEI Consortium's test suite), with the first error on the same line.
  • Checks IDs as Jing does (RELAX NG DTD Compatibility): every xml:id or other ID-typed attribute unique, every IDREF resolving.
  • 4–24× faster than Jing end-to-end on every sample (7× at the median), and 17–36× faster than Jing with SchXslt when checking Schematron too; see BENCHMARKS.md.
  • Reads both the XML (.rng) and compact (.rnc) syntax, including include/externalRef, which are resolved as local files only: validation never touches the network.
  • Checks the ISO Schematron rules TEI ODD-generated schemas embed, in either syntax, with its own XPath 2.0 evaluator, and reports the same messages as the reference pipeline (SchXslt on Saxon-HE) on every bundled test document. All 1,358 tests in the 25 bundled schemas that embed rules are supported; tests using XPath it lacks are listed and skipped, never guessed.
  • Validates each document against the schema it declares in <?xml-model?>, from a local schema store.

Status: early development. Schematron tests that use XPath teixml doesn't implement (back-references in regular expressions, most XPath 3 functions, schema types, …) are reported as unsupported and skipped.

Usage

Add this to your Cargo.toml:

[dependencies]
teixml = "0.1"

Then:

use teixml::Schema;
use teixml::relaxng::SchemaSyntax;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let schema = Schema::from_text(
        r#"default namespace = "http://www.tei-c.org/ns/1.0"
           start = element TEI { element text { element p { text }+ } }"#,
        "inline.rnc",
        SchemaSyntax::Compact,
    )?;

    let valid = r#"<TEI xmlns="http://www.tei-c.org/ns/1.0"><text><p>Hello</p></text></TEI>"#;
    assert!(schema.validate_str(valid)?.is_empty());

    let invalid = r#"<TEI xmlns="http://www.tei-c.org/ns/1.0"><text><div/></text></TEI>"#;
    for diagnostic in schema.validate_str(invalid)? {
        println!("{diagnostic}");
    }
    Ok(())
}
1:48: unexpected element `div` (in /TEI/text)
1:61: missing required content (in /TEI/text)

Schema::from_file and Schema::validate_file do the same for files on disk. Each Diagnostic says where it comes from (DiagnosticKind::RelaxNg or DiagnosticKind::Schematron, with the rule's message, role, test and location) and how serious it is (severity()); a document is valid when none is an error. Schema::set_schematron(false) turns Schematron checking off, and Schema::schematron() lists the tests that are unsupported. See the documentation for the full API, including the schema store (teixml::store) and the RELAX NG engine (teixml::relaxng).

Command-line tool

cargo install teixml                    # validation only
cargo install teixml --features sync    # also download and update schemas

Either installs the tei-rs command:

tei-rs validate --schema tei_all.rng edition.xml
edition.xml:15:13: error: unexpected element `placeName` (in /TEI/teiHeader/fileDesc/publicationStmt)
edition.xml:93:9: error: Schematron assert failed: The @spanTo attribute of delSpan is required. (in /TEI/text/body/p/delSpan)
edition.xml:353:56: warning: Schematron assert failed: The @new attribute should always be supplied; use the special value "normal" to indicate that the feature concerned ceases to be remarkable at this point. [role: warning] (in /TEI/text/body/div/u/shift)

RELAX NG errors come first, then the messages of the schema's Schematron rules (failed asserts and successful reports). A Schematron message is an error, warning or info according to its rule's role (warning, warn and TEI's nonfatal are warnings; info is info; anything else, or no role, is an error). Schematron tests that use XPath tei-rs doesn't support are listed once per schema on stderr and skipped. --no-schematron checks RELAX NG only.

The exit status is 0 when every document is valid (warnings and info don't count), 1 when any is invalid, and 2 when a schema or document can't be read or parsed. When several documents share a schema, it is compiled once per run.

Without --schema, each document is validated against the schema it declares in <?xml-model href="…"?>, taken from a local schema store:

tei-rs schemas add https://epidoc.stoa.org/schema/latest/tei-epidoc.rng   # download once
tei-rs validate inscriptions/*.xml                                         # then offline
tei-rs schemas check     # are the stored schemas still the latest published versions?
tei-rs schemas sync      # update the ones that aren't

check compares every stored schema, and every file it includes, with what its URL serves now; sync downloads whatever changed. schemas list shows the store and schemas which doc.xml prints the schema a document resolves to; --alias and --mirror on add record other hrefs for the same schema and fallback download locations. The store defaults to $TEI_RS_SCHEMAS, else a tei-rs folder in your user cache directory; --schemas DIR picks another. Run tei-rs --help for the full reference.

Some schemas' Schematron rules read other XML documents with doc() or document(), such as a project's taxonomy published at a URL. Those are read from the schema store too: when a schema names one the store lacks, tei-rs validate says so once, with the command that adds it, and the rules that read it report an error until then.

tei-rs schemas add https://raw.githubusercontent.com/srophe/syriaca-data/refs/heads/gaddel_development/data/taxonomy/taxonomy.rdf

Rules only read files under the schema's directory, the validated document's directory and the schema store (symbolic links and .. resolved first); for anything else, doc-available() is false and doc() an error. In the library, Schema::set_store gives a schema the store to read from.

Cargo features

  • schematron (on by default): checking the ISO Schematron rules embedded in schemas — the teixml::schematron module, Schema::set_schematron and the CLI's Schematron messages. It adds no dependencies. Rules are compiled on first use, so RELAX NG-only validation (--no-schematron) costs nothing extra. default-features = false builds a RELAX NG-only validator.
  • sync (off by default): downloading and updating schemas in a schema store — the teixml::sync module and tei-rs schemas add/check/sync. Downloads use HTTPS only (redirects included), honour HTTPS_PROXY and use the operating system's certificates. Without it, the crate contains no network code; validation, schemas list and schemas which work in every build.
[dependencies]
teixml = { version = "0.1", features = ["sync"] }

Rust version support

The minimum supported Rust version is 1.88. It may be raised in a minor release; such changes are noted in the release notes.

Contributing

Bug reports and pull requests are welcome. See CONTRIBUTING.md for how the repository is laid out and how to run the tests, the comparisons with Jing and the benchmarks.

Security

Documents are treated as untrusted input; schemas as trusted. See SECURITY.md for what that means and how to report a vulnerability.

License

Licensed under the MIT license.

The RELAX NG engine in src/relaxng/ is derived from CASOON's MIT-licensed relax-ng and keeps its copyright notice in src/relaxng/LICENSE; see src/relaxng/PROVENANCE.md. Test data and schemas in this repository keep their own licences, listed in tests/tei/SOURCES.md and schemas/README.md.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in teixml by you shall be licensed as MIT, without any additional terms or conditions.

About

Rust-fast tei-xml validation

Resources

Contributing

Security policy

Stars

3 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages