xmlschema

The xmlschema library uses converter classes to handle the decoding (XML to intermediate data) and encoding (intermediate data to XML) of XML data. Because XML contains metadata like attributes and namespaces, converters apply specific naming conventions to represent these in formats like JSON.

Predefined Converters

Depending on your target data format or preferred convention, you can use one of the following derived classes:

• xmlschema.ParkerConverter: Implements the Parker convention.
• xmlschema.BadgerFishConverter: Implements the BadgerFish convention.
• xmlschema.AbderaConverter: Implements the Apache Abdera project convention.
• xmlschema.JsonMLConverter: Implements the JsonML (JSON Mark-up Language) convention.
• xmlschema.UnorderedConverter: Similar to the default converter but performs unordered decoding and encoding.
• xmlschema.ColumnarConverter: Remaps attributes as child elements in a columnar shape.
• xmlschema.DataElementConverter: Converts XML to a tree of xmlschema.DataElement instances (Element-like objects with decoded values and schema bindings).

Base Class Options

All converters inherit from xmlschema.XMLSchemaConverter. While specific converters may fix certain values, the base class supports options to vary the conversion process, such as force_list and force_dict (though these may be ignored by some predefined converters).

Starting from v4.2, schema instances are configured using xmlschema.settings.SchemaSettings instances. These settings control how schema and XML resources are handled securely.

When creating a new schema, the instance inherits settings from the global defaults, which can be overridden by providing arguments to xmlschema.XMLResource (passed as optional keyword arguments during schema creation).

To ensure multiple schema instances share the same configuration, use the XMLSchemaBase.from_settings method.

To manage configuration globally for an entire application, you can modify the library-wide defaults using update_defaults or revert them using reset_defaults.

import xmlschema
from xmlschema.settings import SchemaSettings

# Update global defaults for all subsequent schema creations
SchemaSettings.update_defaults(some_setting=True)

# Restore to library defaults
SchemaSettings.reset_defaults()

# Create a schema using specific settings
schema = xmlschema.XMLSchema(schema_path, some_setting=True)

# Create a new schema instance based on an existing one's settings
new_schema = schema.from_settings(another_schema_path)

The validation argument controls how the processor handles schemas and XML data. The default mode is strict.

• strict: Validates schemas against the meta-schema. Stops execution immediately upon finding any error in the schema or XML data.
• lax: Validates schemas against the meta-schema. Collects errors and continues; missing parts are replaced with wildcards, and undecodable XML data is replaced with None.
• skip: Does not validate schemas against the meta-schema and does not collect errors. Undecodable XML data is replaced with its original text.

Note: For iter_decode() and iter_encode(), errors are propagated even in skip mode, though top-level decode() and encode() methods discard them.

import xmlschema

schema = xmlschema.XMLSchema('schema.xsd', validation='strict')
# You can override the mode during decoding
data = schema.decode(xml_data, validation='lax')

Every element or attribute has a .type attribute.

Simple Types

Used for attributes and elements containing only text.

• Use .is_simple() to check if a type is simple.
• Simple types do not have an .attributes property.
• They may have .validators (e.g., for facets like positiveInteger) and properties like .white_space.

Complex Types

Used for elements with attributes or child elements.

• Use .has_complex_content() to check if it is a complex type.
• Access attributes via the .attributes property (which returns an XsdAttributeGroup).
• Access the content model via the .content property (usually an XsdGroup).
• Use .iter_elements() on the .content property to traverse nested elements within a model group.

# Inspecting a complex type
person = schema.elements['person']
print(person.type.has_complex_content())
print(person.type.content)  # Returns XsdGroup

# Traversing nested elements in a complex type
for e in person.type.content.iter_elements():
    print(e)

# Inspecting a simple type
step_attr = schema.attributes['step']
print(step_attr.type.is_simple())
print(step_attr.type.validators)