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.
• 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 opt-in (ParseModes.NAMESPACED or --namespaces strict); the default matches
local names for compatibility. 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.