Quickstart

pyxsd maps an XML document into a Python object tree according to its XML Schema (XSD), reports validation issues, runs user-defined transforms, and writes the tree back out as XML. It has no third-party runtime dependencies — the Python standard library is enough.

Requirements

  • Python 3.11 or newer (3.11–3.14 tested)

  • No runtime dependencies

Installation

pip install pyxsd

or with uv:

uv tool install pyxsd

Command line

Given a schema and an instance document:

pyxsd --inputXml inventory.xml

pyxsd locates the schema from the instance’s xsi:schemaLocation-style hints (or you can pass -s schema.xsd), builds the object tree, validates it, and writes the parsed document to stdout. Useful flags:

# Validate strictly: exit 1 if the report contains errors
pyxsd -i inventory.xml -s schema.xsd --strict

# Write the parsed tree to a file, then apply a transform
pyxsd -i inventory.xml -s schema.xsd -k -o transformed.xml -t 'PrintData()'

# Chain transforms with '>'
pyxsd -i inventory.xml -t 'PrintData() > PrintData()'

See Command-line reference for the complete flag reference and Transforms for transform syntax.

Library use

Constructing PyXSD runs the whole pipeline eagerly — parse, validate, write, and transform all happen in __init__ — so a validation-only run looks like this:

from pyxsd import PyXSD

parser = PyXSD(
    xmlFileInput="inventory.xml",
    xsdFile="schema.xsd",
    xmlFileOutput=False,  # don't write the parsed tree to disk
)

root = parser.schemaRootInstance  # the parsed tree's root instance

if parser.report.has_errors:
    for issue in parser.report.issues:
        print(issue.format())

With transformOutputName set (or transforms given), the transformed tree is written to that file — or to stdout when the value is "stdout".

The root instance of the tree walks with pyxsd.transforms.iter_tree or the walk/visitor helpers in The Transform class; the node shape is documented in Data model.

What pyxsd validates

pyxsd is a lax validator: it builds the tree even when the document is invalid and records non-fatal issues in a Validation report rather than aborting. Features supported in 1.0 (built-in type lattice, sequence / choice / all content models, groups, wildcards, substitution groups, xsi:type dispatch, nil/default/fixed, identity constraints, schema composition) and known gaps are tabulated in Supported features.

Next steps