Pydantic XML Extension

2.19.0 · active · verified Sat Apr 11

Pydantic-xml is a Pydantic extension that provides XML binding for model fields, enabling seamless XML serialization and deserialization. It is deeply integrated with Pydantic, supporting most of its features. The library is actively maintained, with frequent releases addressing bug fixes and new features, often several times a month.

Warnings

breaking Migration to Pydantic V2 (from Pydantic V1) requires significant changes. `pydantic-xml` 2.x supports Pydantic V2+. While `pydantic-xml` itself aims for compatibility, direct Pydantic V1 (`pydantic.v1.BaseModel`) and Pydantic V2 (`pydantic.BaseModel`) models cannot be mixed directly within the same hierarchy.
Fix: Upgrade Pydantic to V2, migrate your Pydantic models, and ensure all models used with `pydantic-xml` are Pydantic V2 compatible. Avoid mixing `pydantic.v1.BaseModel` and `pydantic.BaseModel` in model hierarchies. Use `bump-pydantic` tool for initial migration of Pydantic models.
breaking Since v2.16.0, an exception is now raised if a namespace alias used in a model or field is not found within the model's namespace map (`__xml_nsmap__`). This changed behavior from silently ignoring missing aliases.
Fix: Ensure all namespace aliases used in `ns` or `nsmap` parameters are correctly defined in the model's `__xml_nsmap__` class attribute.
breaking The way custom root types are declared changed significantly around `pydantic-xml` 2.0.0. Custom root models must now inherit from `RootXmlModel` instead of `BaseXmlModel` with `__root__` attribute.
Fix: Change base class from `BaseXmlModel` to `RootXmlModel` for models representing the root of an XML document and defining a `root` field for the content.
gotcha By default, `pydantic-xml` maps Python field names directly to XML element/attribute names. If the XML tag or attribute name differs (e.g., due to different casing or hyphens), `ParsingError` will be raised unless `tag` or `name` arguments are explicitly provided to `element()`, `attr()`, or `BaseXmlModel`.
Fix: Always explicitly specify `tag='your-xml-tag'` for elements or `name='your-xml-attribute'` for attributes, and `tag='YourRootTag'` for `BaseXmlModel` if the XML names don't exactly match Python field/class names or casing.
gotcha The syntax for defining custom field serializers and validators has evolved with Pydantic V2. While older `@xml_field_serializer` and `@xml_field_validator` decorators are still functional, the `Annotated` pattern with `pydantic.field_serializer` and `pydantic.field_validator` (or `pydantic.BeforeValidator`, `pydantic.AfterValidator`, etc.) is the recommended Pydantic V2 approach for better integration and type safety.
Fix: Prefer using `typing.Annotated` with Pydantic's functional validators/serializers (`field_serializer`, `field_validator`, `AfterValidator`, etc.) for defining custom serialization/validation logic.
breaking The encoding format for `bool` and `None` types changed. `bool` values now serialize as lowercase `'true'` or `'false'` instead of title-case `'True'` or `'False'`. `None` values now serialize as an empty string `''` instead of `'None'`.
Fix: Update any downstream consumers of XML generated by `pydantic-xml` to expect the new `bool` and `None` encoding formats. If the old format is strictly required, implement custom serializers for these types.

Install

pip install pydantic-xml Basic Installation
pip install pydantic-xml[lxml] With lxml backend (recommended for performance)

Imports

BaseXmlModel
```
from pydantic_xml import BaseXmlModel
```
RootXmlModel
```
from pydantic_xml import RootXmlModel
```
Required for custom root types and models that directly represent the XML root element.
attr
```
from pydantic_xml import attr
```
Top-level import is preferred for convenience and stability.
element
```
from pydantic_xml import element
```
Top-level import is preferred for convenience and stability.
wrapped
```
from pydantic_xml import wrapped
```
Top-level import is preferred for convenience and stability. Used for deep element hierarchies without intermediate models.

Quickstart

This example demonstrates how to define XML serializable/deserializable models using `BaseXmlModel`, bind fields to XML attributes (`attr`), elements (`element`), and handle lists of sub-models. It covers both deserialization from an XML string and serialization back to XML.

from typing import List, Optional
from pydantic import HttpUrl
from pydantic_xml import BaseXmlModel, attr, element

class Product(BaseXmlModel):
    status: str = attr() # e.g., 'running', 'development'
    launched: Optional[int] = attr(default=None)
    title: str # Extracted from the element text

class Company(BaseXmlModel, tag='Company'):
    trade_name: str = attr(name='trade-name')
    website: HttpUrl = element()
    products: List[Product] = element(tag='product', default_factory=list)

xml_doc = """
<Company trade-name="SpaceX">
    <website>https://www.spacex.com</website>
    <product status="running" launched="2013">Several launch vehicles</product>
    <product status="running" launched="2019">Starlink</product>
    <product status="development">Starship</product>
</Company>
"""

# Deserialize XML to a Pydantic model
company = Company.from_xml(xml_doc)
print(f"Company: {company.trade_name}, Website: {company.website}")
for product in company.products:
    print(f"  Product: {product.title}, Status: {product.status}, Launched: {product.launched}")

# Serialize Pydantic model back to XML
new_xml_doc = company.to_xml(pretty_print=True)
print("\nSerialized XML:")
print(new_xml_doc.decode())

view raw JSON →