Validation

pyxsd is a lax validator: it never aborts on bad data. Every problem it finds is recorded as a ValidationIssue in a single ValidationReport reachable at PyXSD.report. A run can produce a complete object tree and a full error report at the same time.

Note

“Lax validator” here means reporting is non-fatal. It is separate from the parse mode (PyXSD(mode=...), --mode), which controls what is bound into the tree when a document is invalid. The report is always strict regardless of mode — see Parse modes and binding.

from pyxsd import PyXSD

parser = PyXSD(xmlFileInput="inventory.xml", xsdFile="schema.xsd")
if parser.report.has_errors:
    for issue in parser.report.issues:
        print(issue.format())

Report API

class pyxsd.validation.ValidationReport

An ordered collection of validation issues.

Reports are owned by a PyXSD run and filled in by the binding machinery as it walks the instance document.

phase: str

The phase new issues are attributed to unless one is passed explicitly. The parser flips this between schema compilation and instance binding.

add_error(message, *, code, element=None, phase=None)

Record a fatal-severity issue.

Parameters:

• message (str)

• code (str)

• element (str | None)

• phase (str | None)

Return type:

None

add_warning(message, *, code, element=None, phase=None)

Record a recoverable-severity issue.

Parameters:

• message (str)

• code (str)

• element (str | None)

• phase (str | None)

Return type:

None

for_phase(phase)

Only the issues attributed to phase ("schema"/"instance").

Parameters:

phase (str)

Return type:

list[ValidationIssue]

property issues: list[ValidationIssue]

All recorded issues, in the order they were found.

property errors: list[ValidationIssue]

Only the error-severity issues.

property warnings: list[ValidationIssue]

Only the warning-severity issues.

property has_errors: bool

Whether any error-severity issue was recorded.

class pyxsd.validation.ValidationIssue(severity, code, message, element=None, phase='instance')

A single problem found while validating a document.

• severity: the IssueSeverity of the issue.

• code: a short, stable, machine-readable tag describing the kind of problem (for example "missing-attribute" or "order"). Codes are documented in the validation guide and are safe to match on in tooling.

• message: a human-readable, single-line description.

• element: the name of the element or type the issue was found in, when known.

• phase: the pipeline stage that produced the issue, either "schema" (reading the XSD, composing included schemas, building the generated classes) or "instance" (binding the XML document). Tooling and the conformance runner use this to check each stage independently.

Parameters:

• severity (IssueSeverity)

• code (str)

• message (str)

• element (str | None)

• phase (str)

severity: IssueSeverity

code: str

message: str

element: str | None = None

phase: str = 'instance'

format()

Render the issue as one line, as shown by the CLI.

Return type:

str

class pyxsd.validation.IssueSeverity(*values)

How serious a validation issue is.

Issue codes

Codes are stable strings. ERROR-level codes fail under --strict or report.has_errors; WARNING-level codes never affect exit status.

Code	Severity	Meaning
order	ERROR	Child order violates the sequence content model.
unexpected-element	ERROR	Element is not declared in the content model and no wildcard allows it.
wildcard-no-declaration	ERROR	processContents="strict" wildcard matched an element/attribute with no global declaration (namespaced mode).
occurrence-min	ERROR	Fewer occurrences than minOccurs allows.
occurrence-max	ERROR	More occurrences than maxOccurs allows.
missing-attribute	ERROR	A required attribute is absent.
unexpected-attribute	WARNING	Attribute not declared in the schema.
invalid-attribute	ERROR	Attribute value fails its declared type.
prohibited-attribute	WARNING	Attribute declared use="prohibited" present.
fixed-attribute	ERROR	Attribute present with a value differing from fixed.
unknown-type	ERROR	Referenced type could not be resolved.
unknown-namespace-prefix	ERROR	A prefixed name uses a namespace prefix that is not bound in scope (namespaced mode).
value	ERROR	Text content failed lexical validation for its type.
default	ERROR	Element default value is not valid for the element’s type.
fixed-element	ERROR	Element content differs from its fixed value.
nil	ERROR	xsi:nil="true" on a non-nillable element.
abstract-element	ERROR	Instance of an abstract element declaration.
abstract-type	ERROR	Direct instance of an abstract type (allowed only via xsi:type).
blocked	ERROR	Substitution-group member blocked by the head’s block.
xsi-type	ERROR	xsi:type could not be resolved, is not validly derived from the declared type, or is blocked.
unknown-root	ERROR	Document root matches no global element declaration.
multiple-roots	ERROR	More than one global element matches the document root.
identity-key	ERROR	Key field missing or duplicate key value.
identity-unique	ERROR	Duplicate value under a xs:unique constraint.
identity-keyref	ERROR	Keyref value has no matching key/unique value.
identity-unsupported	WARNING	Identity-constraint XPath uses an unsupported construct.
unknown-group	ERROR	Referenced xs:group missing.
circular-group	ERROR	Group reference cycle.
unknown-attributeGroup	ERROR	Referenced xs:attributeGroup missing.
circular-attributeGroup	ERROR	Nested attributeGroup reference cycle.
unknown-substitution-head	ERROR	Substitution group references a missing head.
unknown-elementRef	ERROR	Element ref points to a missing global element.
final	ERROR	Derivation violates the base type’s final attribute.
schema	ERROR	The schema file itself is malformed or unreadable.
schema-hint	WARNING	Malformed schemaLocation hint in the instance document.
schema-compose	ERROR	Missing or malformed included/imported schema file.
import-unresolved	ERROR	Namespace-only xs:import could not be satisfied from a schemaLocation or namespace_schemas (namespaced mode).
compose-cycle	WARNING	A repeated include/redefine was deduplicated.
compose-namespace	ERROR	Include target namespace mismatch.
internal	WARNING	Parser internal inconsistency — please report.

Strict mode

pyxsd --strict exits with status 1 when the report contains any ERROR-severity issue. Warnings never affect the exit code.