{"id":1792,"library":"xmlschema","title":"XML Schema Validator and Decoder","description":"xmlschema is a Python library for validating XML documents against XML Schema Definition (XSD) files and for decoding XML data into Python dictionaries. It supports XPath 1.0/2.0+ for schema processing and data extraction. The library is actively maintained with regular major and minor releases, typically several per year.","status":"active","version":"4.3.1","language":"python","source_language":"en","source_url":"https://github.com/sissaschool/xmlschema","tags":["XML","Schema Validation","XSD","Data Binding","XPath"],"install":[{"cmd":"pip install xmlschema","lang":"bash","label":"Default installation"},{"cmd":"pip install \"xmlschema[lxml]\"","lang":"bash","label":"With lxml for improved performance"}],"dependencies":[{"reason":"Core dependency for XPath 1.0/2.0+ support required for schema processing.","package":"elementpath","optional":false},{"reason":"Optional dependency for faster XML parsing, especially when using the `iterparse` feature.","package":"lxml","optional":true}],"imports":[{"symbol":"XMLSchema","correct":"from xmlschema import XMLSchema"},{"symbol":"XMLResource","correct":"from xmlschema import XMLResource"},{"symbol":"ValidationError","correct":"from xmlschema import ValidationError"}],"quickstart":{"code":"import xmlschema\n\n# Define a simple XML Schema (XSD) and an XML document\nxsd_content = '''\n<xs:schema xmlns:xs=\"http://www.w3.org/2001/XMLSchema\">\n  <xs:element name=\"data\">\n    <xs:complexType>\n      <xs:sequence>\n        <xs:element name=\"item\" type=\"xs:string\" maxOccurs=\"unbounded\"/>\n      </xs:sequence>\n    </xs:complexType>\n  </xs:element>\n</xs:schema>\n'''\n\nxml_content = '''\n<data>\n  <item>First</item>\n  <item>Second</item>\n</data>\n'''\n\n# 1. Load the XML Schema\ntry:\n    schema = xmlschema.XMLSchema(xsd_content)\n    print(\"Schema loaded successfully.\")\nexcept xmlschema.XMLSchemaException as e:\n    print(f\"Schema error: {e}\")\n    exit(1)\n\n# 2. Validate an XML document against the schema\ntry:\n    schema.validate(xml_content)\n    print(\"XML document is valid.\")\nexcept xmlschema.ValidationError as e:\n    print(f\"XML validation error: {e}\")\n\n# 3. Decode the XML document into a Python dictionary\ntry:\n    data_dict = schema.to_dict(xml_content)\n    print(\"\\nDecoded XML to dictionary:\")\n    print(data_dict)\nexcept xmlschema.ValidationError as e:\n    print(f\"Decoding error: {e}\")\n\n# Example of invalid XML\ninvalid_xml_content = '''\n<data>\n  <extra_item>This should not be here</extra_item>\n  <item>Valid Item</item>\n</data>\n'''\ntry:\n    schema.validate(invalid_xml_content)\n    print(\"Invalid XML document is valid (ERROR!).\")\nexcept xmlschema.ValidationError as e:\n    print(f\"Invalid XML correctly failed validation: {e.reason.splitlines()[0]}...\")","lang":"python","description":"This quickstart demonstrates how to load an XML Schema, validate an XML document against it, and decode the validated XML into a Python dictionary. It also shows an example of how invalid XML is handled during validation."},"warnings":[{"fix":"Upgrade your Python environment to 3.10 or newer. If stuck on Python 3.9, use `xmlschema<4.3.0`. If stuck on Python 3.8, use `xmlschema<4.0.0`.","message":"Python 3.8 support was dropped in `xmlschema` v4.0.0, and Python 3.9 support was dropped in `xmlschema` v4.3.0. Users on older Python versions must use `xmlschema` v3.x or upgrade their Python interpreter.","severity":"breaking","affected_versions":">=4.0.0, >=4.3.0"},{"fix":"Consult the `xmlschema` v4.x documentation for updated usage patterns, especially for custom decoding/encoding or schema loading processes. High-level methods like `validate()` and `to_dict()` are largely compatible.","message":"Version 4.0.0 introduced significant internal API changes, replacing generators with normal functions for decoding/encoding and standardizing on `DecodeContext` and `EncodeContext` instead of keyword arguments. Code directly interacting with these lower-level APIs or internal methods will break.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"If encountering `XMLSchemaResourceError`, consider increasing the limits via `xmlschema.set_settings()` for `MAX_SCHEMA_SOURCES`, `MAX_XML_ELEMENTS`, or `MAX_XML_DEPTH` if your application legitimately requires larger resources. For example: `xmlschema.set_settings(max_xml_elements=5_000_000)`.","message":"Version 4.2.0 introduced package limits for schema sources (`MAX_SCHEMA_SOURCES`) and XML elements (`MAX_XML_ELEMENTS`), and reduced `MAX_XML_DEPTH`. These limits are designed to prevent resource exhaustion but can lead to `XMLSchemaResourceError` exceptions for very large or deeply nested schemas/documents if not configured.","severity":"gotcha","affected_versions":">=4.2.0"},{"fix":"Install `xmlschema` with the `lxml` extra: `pip install \"xmlschema[lxml]\"`. Then, some methods like `XMLResource.iterparse` can accept an `lxml=True` argument for `lxml`-specific behavior.","message":"While `xmlschema` can use `lxml` for improved parsing performance, it is an optional dependency. If `lxml` is not installed, the library falls back to Python's built-in `xml.etree.ElementTree`. Users expecting `lxml`'s speed or specific features (like `iterparse`'s `lxml` argument) must explicitly install it.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'/2.0':33 '1.0':32 'activ':43 'bind':60 'data':25,38,59 'decod':5,23 'definit':18 'dictionari':28 'document':14 'extract':39 'file':20 'librari':10,41 'maintain':44 'major':47 'minor':49 'per':53 'process':36 'python':9,27 'regular':46 'releas':50 'schema':2,17,35,56 'sever':52 'support':30 'typic':51 'valid':3,12,57 'xml':1,13,16,24,55 'xmlschema':6 'xpath':31,61 'xsd':19,58 'year':54","created_at":"2026-04-09T04:03:19.364307+00:00","updated_at":"2026-04-17T00:56:34.606862+00:00","problems":[{"fix":"Run `pip install xmlschema` in your terminal to install the library.","cause":"The `xmlschema` library is not installed in the Python environment where the code is being executed.","error":"ModuleNotFoundError: No module named 'xmlschema'"},{"fix":"Review the XML document and adjust its content or structure to match the constraints (e.g., data types, required elements, enumerations) specified in the XSD. Use `schema.validate(xml_file)` for detailed error messages.","cause":"The XML document being processed does not conform to the rules defined in the associated XML Schema Definition (XSD), leading to a validation failure during decoding.","error":"xmlschema.validators.exceptions.XMLSchemaValidationError: failed to decode value"},{"fix":"Verify that the path or URL to your XSD file is correct and that the file exists in the specified location. Ensure your application has read access to the file and its directory.","cause":"The XSD file path or URL provided to `xmlschema.XMLSchema()` is incorrect, the file does not exist at the specified location, or the program lacks the necessary permissions to access it.","error":"FileNotFoundError: No such file or directory: 'path/to/your/schema.xsd'"},{"fix":"Inspect the XSD file for XML well-formedness and schema validity. Correct any syntax errors, missing required attributes in schema definitions, or structural inconsistencies within the XSD itself.","cause":"The XML Schema Definition (XSD) file itself is syntactically malformed, not well-formed XML, or contains structural errors that prevent `xmlschema` from parsing it correctly (e.g., missing required attributes like 'targetNamespace').","error":"xmlschema.exceptions.XMLSchemaParseError: invalid XML schema"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"4.3.2","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/sissaschool/xmlschema","docs":null,"changelog":null,"pypi":"https://pypi.org/project/xmlschema/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization","data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-27","next_check":"2026-07-28","install_tag":null}}