html-conform 0.1.0

HTML5 conformance checking as a pure Rust dependency (vnu-comparable, no JVM runtime).
Documentation

html-conform

A pure Rust library for HTML5 specification conformance checking — comparable in precision and output to the Nu Html Checker (vnu), but without a JVM, subprocesses, or HTTP network requests. Embeddable directly into any Rust application, CLI, or web service.

🎯 Conformance Profile & Metrics

html-conform is validated continuously against the official W3C/vnu differential test suite (4,655 test fixtures vendored from validator/validator@388cb36).

  • Precision Floor: 0 False Positives (BASELINE_FALSE_POSITIVE = 0) — zero false alarms across all 4,655 test cases.
  • Accuracy: 98.8 % overall accuracy across the entire corpus (3,691 True Positives, 909 True Negatives).
  • Residual False Negatives: 55 / 4,655 — 43 need real tree-construction-error tracking during parsing (a separate html5-parser change, not expressible by inspecting the finished tree), 5 need a full 2D table grid model with colspan/rowspan overlap detection (not reasonably expressible in the Schematron/XPath 1.0 layer), and 7 are smaller individually-researched gaps (an ARIA tab/tabpanel heuristic, dl duplicate-term edge cases, ruby markup advisories, inline CSS property validation). None of these are false alarms — each is a documented, deliberate limitation, not a silent gap.

🔍 Validation Layers

html-conform combines five independent finding sources into a single, unified CheckReport:

  1. HTML5 Tree Construction (parser.html5) — Spec-compliant, error-tolerant tree parsing via html5-parser. Emits tokenizer & DOCTYPE parse findings with line, column, and byte offset locations.
  2. Grammar & Content Model (schema.html5) — Validation against the full vendored W3C RELAX NG schema (relax-ng), including SVG 1.1 and MathML 3 subtrees.
  3. Custom Datatype Micro-Syntaxes (w:*) — Full spec-compliant datatype validation for 50 custom W3C attribute microsyntaxes (w:image-candidate-strings for srcset, w:content-security-policy, w:media-query, w:datetime, w:iri-ref, BCP 47 language tags, etc.).
  4. Schematron Co-Constraints (rules/*.sch) — High-precision assertion rules via schematron-engine and xpath-eval (ARIA 1.2 constraints, structural HTML restrictions, heading hierarchy, link/script attribute combinations).
  5. Script & CSP Validation (scripts.import-map, scripts.speculation-rules, csp.meta-enforcement) — Dedicated JSON validation for <script type="importmap"> / <script type="speculationrules"> contents, and Content Security Policy (<meta http-equiv="Content-Security-Policy">) enforcement against inline scripts/styles via csp-parse.

🚀 Usage

Add html-conform to your Cargo.toml:

[dependencies]
html-conform = "0.1.0"

Basic Check

use html_conform::check;

fn main() {
    let html = r#"<!DOCTYPE html>
<html lang="en">
<head><title>Test Document</title></head>
<body><p>Hello world</p></body>
</html>"#;

    let report = check(html).expect("checker execution succeeded");

    for finding in &report.findings {
        println!(
            "[{:?}] {} at line {:?}: {}",
            finding.severity, finding.rule_id, finding.location, finding.message
        );
    }

    if report.has_errors() {
        eprintln!("Document has conformance errors!");
    }
}

Fine-Grained Options

use html_conform::{CheckOptions, check_with_options};

let options = CheckOptions {
    include_parse_errors: false, // exclude tokenizer/parser diagnostics
};

let report = check_with_options(html, options).unwrap();

🏗️ Architecture

                 HTML Source String / Document
                               │
                               ▼
                    ┌─────────────────────┐
                    │  1. html5-parser    │  WHATWG Tree Construction
                    └─────────────────────┘
                               │
            ┌──────────────────┼──────────────────┐
            ▼                  ▼                  ▼
  ┌──────────────────┐ ┌───────────────┐ ┌──────────────────┐
  │ 2. relax-ng      │ │ 3. Schematron │ │ 4. JSON / CSP    │
  │    (Schema &     │ │    (Co-Con-   │ │    (Import-Maps, │
  │    Datatypes)    │ │    straints)  │ │    Speculation,  │
  └──────────────────┘ └───────────────┘ │    CSP)          │
            │                  │         └──────────────────┘
            └──────────────────┼──────────────────┘
                               │
                               ▼
                   ┌───────────────────────┐
                   │ CheckReport           │
                   │  Vec<Finding>         │
                   └───────────────────────┘

🔄 Maintenance & Refinement Loops

html-conform enforces quality through two structured maintenance loops:

  • Loop A (Schema Sync): Mechanical updates when W3C RELAX NG schemas or vnu upstream specifications update (xtask/vendor-corpus.sh).
  • Loop B (Assertion Refinement Loop): Iterative refinement of Schematron rules and datatype checkers against the 4,655-fixture differential test suite, strictly maintaining the 0 False Positive floor.

📜 License & Attributions