Skip to content

Classes

xsdata is using python's dataclasses as representation models for document entities. Plugins can extend support for output formats.

Basic Example

@dataclass
class Book:
    title: str
    author: str
    year: int

book = Book(title="The Catcher in the Rye", author="J.D. Salinger", year=1951)
print(serializer.render(book))
<?xml version="1.0" encoding="UTF-8"?>
<Book>
  <title>The Catcher in the Rye</title>
  <author>J.D. Salinger</author>
  <year>1951</year>
</Book>

Metadata

Additional class metadata are required in order to access some of the more advance features.

name

The local name of the XML/JSON element.

>>> @dataclass
... class Root:
...     class Meta:
...         name = "xsdata"
...
>>> print(serializer.render(Root()))
<xsdata/>

Type: str

Default: The class name

namespace

The namespace name of the XML element

>>> @dataclass
... class Root:
...     class Meta:
...         namespace = "xsdata"
...
>>> print(serializer.render(Root()))
<ns0:Root xmlns:ns0="xsdata"/>

Type: str | None

Default: None

nillable

Specify if the attribute xsi:nil="true" is needed when the class is serialized and it doesn't have any meaningful content.

>>> @dataclass
... class Child:
...     class Meta:
...         nillable = True
...
>>> @dataclass
... class Root:
...     child: Child
...
>>> root = Root(child=Child())
>>> print(serializer.render(root))
<Root>
  <child xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
</Root>

Type: bool

Default: False

target_namespace

The namespace name, the XML element was defined under. Used during auto-type discovery when the element form is unqualified.

Type: str | None

Default: None

global_type

Specify if the class represents an element that can appear in the document root. When false the class can be used only another class dependency, and it's excluded from auto-type discovery.

Type: bool

Default: True

element_name_generator

A callable to convert element names when no explicit names are defined.

>>> @dataclass
... class RootType:
...     class Meta:
...         element_name_generator = camel_case
...
>>> print(serializer.render(RootType()))
<rootType/>

Type: Callable[[str], str]

Default: lambda x: x

attribute_name_generator

A callable to convert attribute names when no explicit names are defined.

>>> @dataclass
... class Root:
...     who_are_you: str = field(default="xsdata", metadata={"type": "Attribute"})
...     class Meta:
...         attribute_name_generator = camel_case
...
>>> print(serializer.render(Root()))
<Root whoAreYou="xsdata"/>

Type: Callable[[str], str]

Default: lambda x: x