Skip to content

XSD-to-Code Generator & CLI Toolchain (polyxml)#

PolyXML includes a high-performance, polyglot XSD-to-code generator and CLI toolchain (polyxml) that parses W3C XSD 1.0 and 1.1 schemas, builds a language-agnostic Intermediate Representation (PolyXML-IR), resolves complex type cycles via Tarjan's Strongly Connected Components (SCC) algorithm, and emits idiomatic, production-ready data contracts and codecs across 7 modern programming languages.


🚀 Key Features#

  • Pure-Rust XSD 1.0 & 1.1 Parser: Zero dependencies on legacy libraries like libxml2 or Apache Xerces.
  • PolyXML Intermediate Representation (IR): Normalized schema representation preserving namespaces, facets, substitution groups, documentation, and cardinality.
  • Tarjan SCC Cycle-Cutting: Automatically identifies self-referential and mutually recursive types, calculating the minimal set of cycle-cut points to prevent infinite size allocations (Box<T>, pointers, std::unique_ptr, z.lazy).
  • Simultaneous Multi-Target Compilation: Emit models for Python, Rust, C++, Java, TypeScript, Go, and C# in a single compiler invocation.
  • Ordered Mixed Content: Preserve text and child elements from xs:complexType mixed="true" in one typed item sequence.
  • W3C Conformance Tested: Validated against the official W3C XML Schema Test Suite (XSTS) via the polyxml-w3c-tests harness.

Mixed content#

For a mixed complex type, PolyXML generates an items collection containing text and child-element variants in document order. For example, <description>open <b>bold</b> close</description> becomes three items: text "open ", element b with value "bold", and text " close". Attributes remain regular fields on the parent model. Rust, Python, Go, Java direct codecs, and C# can read and write this ordered sequence. C++ and TypeScript expose it as typed variants for application code.


📦 Installation#

Compile and install the polyxml CLI directly from source using Cargo:

# From the PolyXML workspace root
cargo install --path crates/polyxml-cli

Verify installation:

polyxml --help

🛠️ CLI Commands#

1. polyxml generate#

Generate code directly from one or more .xsd schema files:

# Generate Python dataclasses
polyxml generate --lang python --out ./generated/python schema.xsd

# Generate Pydantic v2 models with runtime facet validation
polyxml generate --lang python --backend pydantic --out ./generated/python schema.xsd

# Generate high-performance Ahead-of-Time (AOT) PyO3 native extension crate
polyxml generate --lang python --backend aot --package my_models --out ./generated/native_models schema.xsd

# Generate zero-copy Rust models with inherent streaming codecs
polyxml generate --lang rust --feature zero-copy --codecs --out ./generated/rust schema.xsd

# Generate selected root messages and their reachable types from a large schema
polyxml generate \
  --lang rust \
  --root-element Entity \
  --root-element PositionReport \
  --out ./generated/uci \
  uci.xsd

# Generate all 7 languages simultaneously
polyxml generate \
  --lang python \
  --lang rust \
  --lang cpp \
  --lang java \
  --lang typescript \
  --lang go \
  --lang csharp \
  --out ./generated \
  schema.xsd

Flags and Options#

Option Flag Description Default
Target Language -l, --lang Target language (python, rust, cpp, java, typescript, go, csharp). Can be specified multiple times. python
Output Directory -o, --out Target directory for generated source files. generated
Config Manifest -c, --config Path to workspace manifest (defaults to ./polyxml.toml if present). None
Root Elements --root-element ELEMENT Repeatable global element selection; use {namespace-URI}local-name if the local name is ambiguous. All roots and types
Model Style --style Target-specific type representation; see the table below. Existing target default
Enhancements --feature NAME Repeatable; also accepts comma-separated names. None added
Target Backend -b, --backend Target backend (dataclass/pydantic/aot for Python; standard/jackson/jackson3 for Java; standard/glaze for C++; interfaces/zod/valibot/typebox for TypeScript; standard/easyjson/sonic for Go; standard/source-gen for C#). Target default
Compilation Mode -m, --mode Target packaging mode (header or modules for C++). Target default
Zero-Copy (Rust) --zero-copy [BOOL] Borrow Cow<'a, str> in Rust models; pass false for owned String fields. true
Streaming Codecs --codecs [BOOL] Emit inherent zero-copy streaming XML serializers and deserializers. true
Split Units --split-units [BOOL] Partition large schemas into topologically-sorted compilation units (chunk_XX.rs for Rust, <stem>_chunk_XX.cpp for C++ in header mode) to reduce compiler memory and recursion depth. false
Split Crates --split-crates [BOOL] In [modules] manifest builds, emit a multi-crate Cargo workspace (Rust) or DAG-chunked sub-packages + utils (Go); for C++, enables split_units. false
Chunk Size --chunk-size SIZE Target maximum types per compilation unit chunk (used with --split-units / --split-crates). 250
Package / Namespace -p, --package Namespace or package name for Java, Go, C#, C++, or Python AOT. Target default
Custom Header --custom-header Custom comment, license, or linter directive text to prepend to generated files. None
Dry Run --dry-run Validate options and parse schemas without writing to disk. false
Format --format Automatically format generated code using host toolchains (ruff, cargo fmt, clang-format, gofmt, npx prettier, google-java-format, csharpier/dotnet format). false

Root selection parses the full schema, then emits the requested element(s), their referenced types, substitution group members, and possible derived types. Multiple root elements can be specified by repeating --root-element on the CLI. It reduces generated output and downstream compile work; it does not reduce schema parsing work or add xsi:type support to codecs that currently reject it. For a manifest build, set root_elements = ["Entity", "PositionReport"] under [workspace] for ordinary builds or under [modules.defense_uci] for a module build. A missing or ambiguous root is an error even with --dry-run.


Backend, style, and feature compatibility#

Options apply to every language selected in one invocation. Use polyxml.toml when targets need different options. Invalid values, unsupported combinations, and conflicting options fail before schema parsing or output creation, including with --dry-run.

Target Backends (first is default) Styles Features
Python dataclass, pydantic, aot dataclass (dataclass backend only) slots, kw-only (dataclass backend only)
Rust standard — zero-copy, phf, split-units, split-crates; rkyv is accepted but currently incompatible with rkyv 0.8
TypeScript interfaces, zod, valibot, typebox — —
Java standard, jackson, jackson3 record (default), pojo (alias class) builder, direct-codec, validation
C# standard, source-gen record-class (default, alias record), record-struct, class (mutable, alias pojo) —
C++ standard, glaze — split-units, split-crates
Go standard, easyjson, sonic (Sonic tag limitation) — split-crates

Java jackson3 targets Spring Boot 4; jackson and its existing spring / spring-boot aliases select Jackson 2. See Spring Boot setup for dependencies, Java 25 verification, and record XML text configuration.

Java's --feature validation (or features = ["validation"] in a manifest) adds Jakarta Bean Validation annotations to generated records and mutable classes. Add jakarta.validation:jakarta.validation-api:3.1.0 to the consuming Java project. Without the feature, generated models need no Jakarta API.

Schemas using xs:gDay, xs:gMonth, xs:gYear, xs:gYearMonth, or xs:gMonthDay generate named partial date types with lexical pattern checks. The string value is retained, including any timezone suffix. Generated validators reject invalid ranges such as ---32, --13, --02-30, and offsets beyond 14:00; the schema-backed Rust parser checks the same values when reading XML.

Defaults are unchanged: Rust zero-copy and Python slots/keyword-only fields are already enabled. Future styles such as Python plain class and C# mutable struct are rejected until their generators support them.

polyxml generate schema.xsd --lang rust --feature phf
polyxml generate schema.xsd --lang java --style pojo --feature builder --feature direct-codec
polyxml generate schema.xsd --lang csharp --backend source-gen --style record-struct

The same options work in both [[generate]] and [codegen.<target>]:

[codegen.java]
output = "generated/java"
backend = "jackson3" # Jackson 3 / Spring Boot 4; use "jackson" for Jackson 2
style = "pojo"
features = ["builder", "direct-codec"]

The CLI rejects unsupported target options and manifest fields. For owned Rust strings, use --zero-copy=false (or zero_copy = false in the manifest); combining it with --feature zero-copy is an error.

polyxml generate without schema paths delegates to the manifest. Put target options in that manifest; command-line generation overrides are rejected rather than silently ignored.

2. polyxml build#

Declaratively compile complex, multi-schema enterprise projects using a workspace manifest (polyxml.toml):

polyxml build --config polyxml.toml

Workspace Manifest Example (polyxml.toml)#

[workspace]
name = "enterprise-iso20022"
schemas = ["schemas/iso20022/*.xsd"]
output_base_dir = "./generated"
go_module = "example.com/enterprise/iso20022"
custom_header = "// Copyright (c) 2026 Enterprise Corp. All rights reserved."

[[generate]]
target = "python"
output = "src/generated/python"
backend = "pydantic"
codecs = true

[[generate]]
target = "rust"
output = "src/generated/rust"
features = ["phf"]
codecs = true
# Optional: partition massive schemas into compilation units or split crates
# split_units = true
# split_crates = true
# chunk_size = 250

[[generate]]
target = "java"
output = "src/generated/java"
package = "com.enterprise.banking.iso20022"
backend = "jackson3" # Jackson 3 / Spring Boot 4; use "jackson" for Jackson 2
# style = "pojo"        # record (default) | pojo (JavaBeans, alias class)
# features = ["builder", "direct-codec"]

[[generate]]
target = "typescript"
output = "src/generated/ts"
backend = "valibot"

[[generate]]
target = "cpp"
output = "src/generated/cpp"
mode = "modules"
backend = "glaze"

[[generate]]
target = "go"
output = "src/generated/go"
package = "payments"
backend = "sonic"

[[generate]]
target = "csharp"
output = "src/generated/csharp"
namespace = "Enterprise.Banking.Iso20022"
backend = "source-gen"
style = "record-struct"

Multi-Module Workspaces & Large-Schema Splitting ([modules.<name>])#

For large multi-schema standards (e.g. NeTEx, FpML, HL7 CDA, UBL), declare [modules.<name>] sections with depends_on so PolyXML deduplicates shared types and emits cross-module imports in topological order:

[workspace]
name = "transit-corpus"
output_base_dir = "generated"
go_module = "example.com/transit"

[modules.geospatial_gml]
schemas = ["schemas/gml/gml.xsd"]
depends_on = []

[modules.transit_netex]
schemas = ["schemas/netex/NeTEx_publication.xsd"]
depends_on = ["geospatial_gml"]
# root_elements = ["PublicationDelivery"]

[[generate]]
target = "rust"
output = "rust"
split_units = true
split_crates = true
chunk_size = 250

[[generate]]
target = "go"
output = "go"
split_crates = true
chunk_size = 250

[[generate]]
target = "cpp"
output = "cpp"
split_units = true
chunk_size = 300
  • Rust (split_units = true, split_crates = true): Emits a Cargo workspace per build with one crate per module and one sub-crate per topological chunk.
  • Go (split_crates = true): Emits go.mod (go_module), a shared utils package, DAG-chunked sub-packages (chunk_XX), and root package type aliases/constructors.
  • C++ (split_units = true): Emits pure-declaration .hpp headers alongside chunked <stem>_chunk_XX.cpp translation units, and lowers > 16-branch xs:choice / xs:union types to template-free tagged structs to avoid std::variant compile-time memory blowups.

3. polyxml validate#

Statically check W3C XML schemas for structural validity, element types, and cycle topology without emitting code:

polyxml validate schemas/*.xsd

Validates: - XML syntax and W3C XSD element structure. - Type reference integrity and namespace imports. - Strongly Connected Components and recursion depth.


4. polyxml transcode#

Bidirectionally convert complete XML and JSON documents, with optional schema guidance. The command accepts stdin and stdout pipes, but reads the full input and buffers the full output before writing it:

[!TIP] For in-depth tutorials, schema-directed vs schema-free rules, and Unix piping examples, see the dedicated Transcoding & Streaming Guide.

# 1. Transcode XML to JSON with W3C XSD schema typing
polyxml transcode --schema order.xsd --pretty order.xml --out order.json

# 2. Connect stdin / stdout pipes
cat order.xml | polyxml transcode --schema order.xsd > order.json

# 3. Transcode JSON back to XML with specified root element
cat order.json | polyxml transcode --schema order.xsd --root order --pretty > order.xml

# 4. Dynamic schema-less transcoding with attribute (@attr) and text (#text) preservation
polyxml transcode legacy.xml --out modern.json

Flags and Options#

Option Flag Description Default
Input [INPUT] Input file path, or - / omitted for standard input. stdin
Output -o, --out Output file path, or - / omitted for standard output. stdout
From Format --from Input format (xml or json). Auto-detected if omitted. Auto-detect
To Format --to Output format (xml or json). Auto-detected if omitted. Auto-detect
Schema -s, --schema Optional W3C XSD schema file for typed schema-directed transcoding. None
Root Element -r, --root Root XML element tag name (used when transcoding JSON to XML). None
Pretty --pretty Format output with indentation and newlines. false

🎯 Target Language Matrix#

Target Language Version Paradigm Key Highlights
Python Python 3.12+ @dataclass, Pydantic v2 & PyO3 AOT PEP 695 type aliases, PEP 604 unions, Ahead-of-Time (AOT) PyO3 C-extensions (--backend aot), zero-copy streaming codecs, native .to_json() / .from_json() methods
Rust Rust 2021 / 2024 Zero-Copy & Owned Structs Lifetime inference <'a>, automatic Box<T> cycle breaks, inherent streaming XML codecs, inherent .to_json_string() codecs
C++ C++20 / C++23 Header-Only Value Types std::variant choices, std::unique_ptr cycle breaks, C++20 concepts, CMake/Meson export
Java Java 22+ Modern Records & Sealed Interfaces Exhaustive switch pattern matching, compact constructor facet validation
TypeScript TypeScript 5+ Interfaces & Discriminated Unions Runtime Zod schemas, circular references handled via z.lazy(), as const enums
WebAssembly Wasm Core (@polyxml/wasm) Zero-Dependency Browser & Edge Runtime High-throughput streaming parseStream, schema-directed XSD validation, zero native Node addons
Go Go 1.22+ Structs with encoding/xml & encoding/json Dual xml:"..." and json:"..." struct tags, json:"-" on XMLName, canonical initialisms (ID, URL), choice exclusivity
C# C# 12 / .NET 8+ Records with Primary Constructors Parameterless constructors, dual XmlSerializer and System.Text.Json attributes ([JsonPropertyName], [JsonConverter]), IValidatableObject

📊 W3C XML Schema Conformance#

PolyXML's schema compiler and runtime codecs are continuously tested against the official W3C XML Schema 1.0 / 1.1 Test Suite (XSTS) using our dedicated test harness repository, polyxml-w3c-tests.

  • Schema Compilation Pass Rate: 99.8% (635 / 636 groups)
  • Instance Validation & Round-Trip Pass Rate: 96.4% (489 / 507 instances)

For full conformance benchmark metrics across Sun Microsystems, Microsoft, and NIST test sets, visit the polyxml-w3c-tests repository.


🌐 Real-World Enterprise Repositories#

Explore full-scale enterprise examples demonstrating polyxml.toml manifests and multi-target compilation in real-world production settings:

Shell completion#

Generate and install a completion script for your shell:

# Bash: add this to ~/.bashrc
source <(polyxml completions bash)

# Zsh: save _polyxml into a directory already on $fpath, then run compinit
polyxml completions zsh > /your/completion/directory/_polyxml

# Fish
mkdir -p ~/.config/fish/completions
polyxml completions fish > ~/.config/fish/completions/polyxml.fish

Backend, style, and feature suggestions use the CLI's validation rules and the selected --lang (including aliases). With multiple languages, completion only suggests values accepted by every selected target. Without --lang, it uses the Python default. Bash also completes comma-separated features; repeat --feature for portable completion across shells.

CLI startup benchmark#

Run ./benchmarks/cli/benchmark.sh with hyperfine installed. It builds the release CLI and measures help rendering plus argument validation and parsing of an empty schema. See the benchmark methodology for measurement limits and output location.