uss-xsd-engine

Browser-first XSD engine for schema diagnostics, tree extraction, sample XML generation, and XML validation.

If you appreciate this library and you want to support my work:

⭐ Please don't forget to star my GitHub repository if you like this project: uss-xsd-engine

📦 Latest release: See full details in GitHub Releases

Consult the Api Documentation for detailed usage and features:

📄 API Documentation: See full details in API DOCUMENTATION

🚀 Overview

uss-xsd-engine is a standalone JavaScript engine designed to process XML Schema (XSD) directly in the browser.

It is built to power tools like USS XSD Studio while remaining lightweight and reusable as:

• a browser/CDN script
• an npm package
• an embedded validation/generation engine

✨ Features

✅ Schema Processing

• Parse XSD into a structured internal model
• Namespace-aware schema resolution
• Support for global elements, types, groups, and attribute groups

✅ Schema Diagnostics

• Unknown types and references detection
• Missing base types
• Restriction validation (subset + occurrence narrowing)
• Facet validation (including pattern support for date/time)
• Default/fixed conflict detection
• Include/import diagnostics

✅ Schema Tree Extraction

• Semantic tree representation of XSD
• Expandable references and structure traversal
• Exposes annotation payloads (documentation, appinfo, processing instructions) on relevant tree nodes
• Useful for UI rendering and schema exploration

✅ Sample XML Generation

• Minimal (mandatory-only) mode
• Full traversal (limited expansion)
• Namespace-aware output (xmlns, prefixes)
• Supports:
  • sequences
  • choices (first-branch strategy)
  • extensions
  • restrictions (first-pass)
• Honors:
  • fixed values
  • default values
• Depth-limited generation with cycle-safe recursion
• Controlled choice and repeated element expansion

✅ XML Validation

• Validate XML against XSD structure
• Namespace-aware validation
• Content model validation:
  • sequence
  • choice
  • all
• Mixed content enforcement
• Attribute validation
• Facet validation (pattern, length, numeric, etc.)
• Compound simple-type support for xs:list and xs:union
• Wildcard support for xs:any and xs:anyAttribute
• processContents support (strict, lax, skip)
• Namespace constraint handling including ##any, ##other, ##targetNamespace, exclusions via notNamespace and notQName
• Ambiguity warnings for competing xs:choice branches
• Restriction enforcement (runtime)
• Derivation-control enforcement for abstract elements, substitution groups, and final-type derivations
• Comprehensive Phase 5.6 compliance coverage for namespace edge cases, QName resolution, schema composition, substitution-group chains, and attribute wildcard interactions
• Fixed value enforcement
• Identity constraints runtime validation (xs:key, xs:keyref, xs:unique)

✅ Streaming Validation (v1.0.0)

• Incremental async API: validateXmlStream(...)
• Chunk-based Node.js interface: createStreamValidator(...)
• Checkpoint/resume for resumable validation workflows
• Parallel multi-stream validation: validateXmlStreams(...)
• Streaming diagnostics export helper: createStreamingDiagnosticsExporter(...)
• Memory-bounded parser option via maxBufferBytes

✅ Include / Import (Groundwork)

• Recognizes xs:include and xs:import
• Supports caller-provided external schemas
• Merges external schema definitions into runtime model
• Emits warnings when referenced schemas are not provided

📦 Installation

npm

npm install uss-xsd-engine

import {
  getSchemaDiagnostics,
  extractSchemaTree,
  generateSampleXml,
  validateXml,
  validateXmlStream,
  createStreamValidator,
  validateXmlStreams,
  createStreamingDiagnosticsExporter
} from "uss-xsd-engine";

const result = validateXml(schema, xml);
console.log(result.issues);

CDN/Browser

<script src="https://unpkg.com/uss-xsd-engine@latest/dist/uss-xsd-engine.standalone.js"></script>

or

<script src="https://cdn.jsdelivr.net/npm/uss-xsd-engine@latest/dist/uss-xsd-engine.esm.min.js"></script>

<script>
  const result = UssXsdEngine.getSchemaDiagnostics({ xsdText });
</script>

Public API

All endpoints follow a consistent result format:

{
  ok: boolean,
  data: any,
  issues: Issue[],
  summary: {
    errorCount: number,
    warningCount: number,
    infoCount: number
  }
}

getSchemaDiagnostics({ xsdText, options? }) Analyze schema and return:

• issues (errors/warnings)
• roots
• supported/unsupported features
• schema statistics

extractSchemaTree({ xsdText, options? }) Returns a structured tree respresentation of the schema

generateSampleXml({ xsdText, options? })

Generates example XML from XSD.

• Options:
• mode: "minimal" (default) or "full"
• targetPrefix: namespace prefix (default "tns")
• includeOptionalAttributes: boolean
• maxDepth: number — limit recursive complex type expansion (default: 3)
• maxChoiceBranches: number — limit how many choice branches are expanded (default: 1)
• expandRepeatingElements: number — limit repeated element expansion for maxOccurs > 1 (default: 2)
• externalDocuments: map of schemaLocation → XSD text

validateXml({ xsdText, xmlText, options? })

Validates XML against schema.

Options:

• rootElementName
• externalDocuments

validateXmlStream({ xsdText, xmlStream, options?, checkpoint? })

Validates XML incrementally from a stream source.

Returns AsyncIterator<Result> where each yielded result contains:

• incremental issues
• current element path
• progress (bytes, elements)

createStreamValidator({ xsdText, options?, checkpoint? })

Chunk-oriented streaming validator interface for Node.js streams.

Methods:

• validateChunk(chunk)
• finalize()
• checkpoint()
• resume(checkpoint)

validateXmlStreams({ xsdText, xmlStreams, options?, checkpoints?, concurrency? })

Validates multiple XML streams in parallel and returns an array of final results.

createStreamingDiagnosticsExporter({ format?, includeData?, includeSummary? })

Collects/exports streaming diagnostics in ndjson, json, or array format.

📚 External Schema Support

You can provide external schemas manually:

const externalDocuments = {
  "common.xsd": "...",
  "common-import.xsd": "..."
};

validateXml({
  xsdText,
  xmlText,
  options: {
    externalDocuments
  }
});

🤔 Why uss-xsd-engine?

Most XML/XSD libraries were designed for server-side environments, require heavy dependencies, or lack meaningful diagnostics.

uss-xsd-engine is built differently — with a focus on modern, browser-first use cases and developer experience.

🌐 Browser-First by Design

• Runs fully in the browser
• No native dependencies or network fetching required
• Perfect for tools like USS, editors, and client-side validation

🧭 Precise Error Diagnostics

• Line/column support for both:

  • XML parsing errors
  • Schema validation errors

• Click-to-navigate support (e.g. Monaco Editor integration)

• Fine-grained mapping:

  • elements
  • attributes
  • values

➡️ Debug XML like you debug code

🌐 Namespace-Aware Everything

• Proper handling of targetNamespace
• Prefix-aware sample XML generation
• Multi-schema support with correct namespace boundaries

➡️ No more ambiguity in complex schema environments

🔁 Real Multi-Schema Support

• Recursive xs:include and xs:import resolution
• Handles deep schema graphs (A → B → C)
• Circular-safe resolution

➡️ Works with real-world schemas (not just simple examples)

🧩 Practical XML Generation

• Generates usable sample XML

• Respects:

  • structure
  • required elements
  • namespaces

• Designed for real testing, not just demos

⚡ Lightweight & Modular

• No heavy runtime dependencies
• Designed for CDN + npm usage
• Easy to embed into any tool or workflow

🧠 Built for Tooling

• Tree extraction for UI rendering
• Structured diagnostics pipeline
• Clean API surface for integration

➡️ Not just a library — a foundation for schema tooling

🚀 When to Use This Engine

Use uss-xsd-engine if you need:

• In-browser XML validation against XSD
• Schema-driven XML generation
• Developer-friendly diagnostics
• Multi-schema (include/import) support
• A lightweight alternative to server-side XML tools

💡 This engine is actively evolving — built to power real tools, not just validate specs.

⚠️ Supported vs Not Fully Supported

✅ Supported (v1.0.0 / Phase 5.6)

• XSD parsing into an internal schema model
• Namespace-aware resolution (elements, types, attributes, groups)
• Extensions (xs:extension)
• Restrictions (subset enforcement, occurrence narrowing, attribute constraints)
• Facet validation:
  • length, numeric, pattern, enumeration, digits
• Default / fixed semantics (schema + XML validation)
• Include/import:
  • manual provision via externalDocuments
  • recursive resolution
  • strict namespace enforcement
• Chameleon includes (namespace adoption for no-targetNamespace schemas)
• Namespace-aware sample XML generation:
  • minimal + representative modes
  • pattern-aware generation (e.g., UETR, BIC)
• XML validation:
  • structural validation (sequence, choice, all, groups)
  • identity constraints (xs:key, xs:keyref, xs:unique)
  • simpleContent + complexContent enforcement
  • mixed content handling
  • restriction validation (pass 2)
• Root and nested simpleContent validation alignment
• XML parse diagnostics with line/column support
• Semantic XML diagnostics with line/column support
• Attribute, value, and text source mapping
• Namespace-aware schema tree extraction
• Imported schema isolation with namespace-safe lookup
• QName resolution:
  • prefixed + default namespace handling
  • no cross-namespace leakage
• Phase 5.6 compliance hardening:
  • substitution-group chain validation
  • namespace-safe QName resolution across schema contexts
  • include/import/redefine composition handling
  • wildcard-driven attribute acceptance and rejection semantics
• Streaming validation APIs:
  • validateXmlStream(...)
  • createStreamValidator(...)
  • validateXmlStreams(...)
  • createStreamingDiagnosticsExporter(...)
• Resumable validation with checkpoint/restore
• Memory-bound parser guard with maxBufferBytes
• Streaming benchmark tooling:
  • fixture generation (fixtures:streaming, fixtures:streaming:target100)
  • benchmark runner with threshold checks (benchmark:streaming)

❌ Not Supported Yet

• Automatic network fetching of schemas
  • (engine is intentionally browser-first and caller-driven)
• Full W3C spec completeness
  • (focus is practical + real-world coverage)
• Complete XSD 1.0/1.1 coverage targets planned for Phase 5 (for example full list/union support and advanced 1.1 assertions)
• All Phase 4 benchmark targets are not guaranteed on every runtime/environment out of the box

⚡ Streaming API Quickstart

Async iterator API:

import fs from "node:fs";
import { validateXmlStream } from "uss-xsd-engine";

for await (const result of validateXmlStream({
  xsdText,
  xmlStream: fs.createReadStream("./large.xml"),
  options: { rootElementName: "root" }
})) {
  if (!result.ok) {
    console.log(result.issues);
  }
}

Chunk-based interface:

import fs from "node:fs";
import { createStreamValidator } from "uss-xsd-engine";

const validator = createStreamValidator({ xsdText, options: { maxBufferBytes: 1024 * 1024 } });
const stream = fs.createReadStream("./large.xml");

stream.on("data", (chunk) => {
  const result = validator.validateChunk(chunk);
  if (result.issues.length) console.log(result.issues);
});

stream.on("end", () => {
  console.log(validator.finalize());
});

Parallel validation and diagnostics export:

import fs from "node:fs";
import {
  validateXmlStreams,
  createStreamingDiagnosticsExporter,
} from "uss-xsd-engine";

const exporter = createStreamingDiagnosticsExporter({ format: "ndjson" });

const results = await validateXmlStreams({
  xsdText,
  xmlStreams: [
    fs.createReadStream("./a.xml"),
    fs.createReadStream("./b.xml"),
  ],
  concurrency: 2,
});

results.forEach((result, idx) => exporter.write(result, { streamIndex: idx }));
console.log(exporter.flush());

🚀 Streaming Benchmark Quickstart

Phase 4.3 includes benchmark tooling for streaming validation throughput and memory checks.

Generate fixtures:

npm run fixtures:streaming

Generate target-size fixtures (100MB profile):

npm run fixtures:streaming:target100

Run benchmark:

npm run benchmark:streaming -- --xml benchmarks/fixtures/large-valid-small.xml --concurrency 2

Run benchmark with pass/fail thresholds (non-zero exit code when checks fail):

npm run benchmark:streaming -- \
  --xml benchmarks/fixtures/large-valid-target.xml \
  --min-throughput-mbps 10 \
  --max-peak-rss-mb 50

Use preset target command:

npm run benchmark:streaming:target

🧪 Playground

The repository includes playground.html for:

• testing schemas
• validating XML
• generating sample XML
• debugging diagnostics

The playground uses the built bundle to simulate real-world usage.

📌 Versioning

This project follows incremental feature delivery:

0.1.x → foundational engine (current phase) 0.2.x → expanded spec coverage 1.0.0 → stable production-ready engine

🤝 Contributing

This project is currently evolving rapidly. Contributions and feedback are welcome.

📄 License

MIT