pyxsd

pyxsd compiles XML Schema (XSD) into Python classes, then validates and binds XML documents into typed object trees. It combines structured validation reports, XPath and ElementTree queries, user-defined transforms, and XML serialization, with optional Pydantic and Arrow/Parquet integrations. Use it when you need schema-driven validation and XML processing, not just an XML parser: compile a schema once, then inspect, transform, or export many documents.

Install

Requires Python 3.11 or newer:

pip install pyxsd

For the MCP server, pip install 'pyxsd[mcp]' provides the pyxsd-mcp command, or configure your client to launch the server with uvx. Install pyxsd[mcp-all] instead when the server should also project records through Arrow; transformation execution remains disabled by default.

{
  "mcpServers": {
    "pyxsd": {
      "command": "uvx",
      "args": ["--from", "pyxsd[mcp]", "pyxsd-mcp"]
    }
  }
}

For the bundled agent skills:

npx skills add knorby/pyxsd

See MCP setup for storage and trust options and agent skills for other clients. MCP transformation execution is disabled by default.

Quickstart

This example runs without any files or downloads:

from io import StringIO

from pyxsd import Schema

schema = Schema.compile(
    StringIO("""
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="quantity" type="xs:positiveInteger"/>
</xs:schema>
""")
)
schema.require_valid()
document = schema.parse(StringIO("<quantity>42</quantity>"))
document.require_valid()
print(document.to_dict()["$"])  # 42

Compilation generates Python classes at runtime; no separate code-generation step is needed. Parsing records recoverable validation errors rather than raising them automatically. require_valid() raises ValidationError when the report contains errors.

The quickstart supplies a complete file-based example with queries, edits, and fresh validation. The same install also provides a CLI:

pyxsd -i inventory.xml -s inventory.xsd --namespaces strict --strict

Use that command with your own files or the quickstart's fixtures. --strict makes validation errors fail the command; a bare run does not write XML.

Work with your data

• Validate and diagnose XML: inspect issue codes, phases, and exact source occurrences.
• Query and edit documents: use XPath or ElementTree paths, export dictionaries/JSON, and revalidate edits.
• Convert JSON data: import and export Parker, BadgerFish, JsonML, native pyxsd, and schema-driven pyxsd-json formats, and generate JSON Schema from XSD.
• Write transforms: apply Python functions or reusable transform classes to the bound tree.
• Process multiple documents: reuse a compiled schema sequentially and choose whether to stop or report failures.
• Connect Pydantic and Arrow: generate access models or schema-derived tables and Parquet with optional extras.
• Use MCP tools: explore schemas and inspect XML diagnostics through a local stdio server. Transform execution is disabled by default; trusted-local previews require explicit opt-in.

For runnable applications, browse the examples: GPX statistics, document and diagram rendering, healthcare conversion and diagnosis, and analytical workflows. Each family documents its inputs and setup.

Scope and limits

pyxsd supports XSD 1.1 with an optional XSD 1.0 mode. Namespace-aware binding is the default (ParseModes.NAMESPACED and CLI --namespaces strict). Pass ParseModes.STRICT, ParseModes.LAX, or --namespaces legacy explicitly when a document needs the historical local-name matching. See binding modes, supported features and gaps, and W3C test-suite results before choosing it for a particular schema.

Parsing materializes the XML tree. Validation does not repair invalid input, and the Python object tree is not a lossless source representation. Read the data model for access and export limits. For untrusted input, configure parser protections and resource limits as described in XML security.

Documentation and contributing

Full documentation · Python API · CLI reference · Contributing · Changelog

The documentation site follows develop and may describe unreleased behavior. For release-specific sources, select the matching tag in this repository.

pyxsd began at Oak Ridge National Laboratory in 2006 and was revived for Python 3 in 2026. See the project history.

License

BSD 3-Clause. LICENSE includes the original ORNL provenance note.