Alias

Tip

Alias() and AliasPath() provide mechanisms to map JSON keys or nested paths to dataclass fields, enhancing serialization and deserialization in the dataclass-wizard library. These utilities build upon Python’s dataclasses.field(), enabling custom mappings for more flexible and powerful data handling.

An alias is an alternative name for a field, used when de/serializing data. This feature is introduced in v0.35.0.

You can specify an alias in the following ways:

• Using Alias() and passing alias(es) to all, load, or dump

• Using Meta setting field_to_alias

For examples of how to use all, load, and dump, see Field Aliases.

Field Aliases

Field aliases allow mapping one or more JSON key names to a dataclass field for de/serialization. This feature provides flexibility when working with JSON structures that may not directly match your Python dataclass definitions.

Defining Aliases

There are three primary ways to define an alias:

• Single alias for all operations

  • Alias('foo')

• Separate aliases for de/serialization

  • Alias(load='foo') for de-serialization

  • Alias(dump='foo') for serialization

The load and dump parameters enable fine-grained control over how fields are handled during deserialization and serialization, respectively. If both are provided, the field can behave differently depending on the operation.

Examples of Field Aliases

Using a Single Alias

You can use a single alias for both serialization and deserialization by passing the alias name directly to Alias():

from dataclass_wizard import Alias, DataclassWizard


class User(DataclassWizard):
    name: str = Alias('username')


user = User.from_dict({'username': 'johndoe'})
print(user)
# > User(name='johndoe')
print(user.to_dict())
# > {'username': 'johndoe'}

Using Separate Aliases for Serialization and Deserialization

To define distinct aliases for load and dump operations:

from dataclass_wizard import Alias, DataclassWizard


class User(DataclassWizard):
    name: str = Alias(load='username', dump='user_name')


user = User.from_dict({'username': 'johndoe'})
print(user)
# > User(name='johndoe')
print(user.to_dict())
# > {'user_name': 'johndoe'}

Skipping Fields During Serialization

To exclude a field during serialization, use the skip parameter:

from dataclass_wizard import Alias, DataclassWizard


class User(DataclassWizard):
    name: str = Alias('username', skip=True)


user = User.from_dict({'username': 'johndoe'})
print(user.to_dict())  # > {}

Advanced Usage

Aliases can be combined with typing.Annotated to support complex scenarios. You can also use the field_to_alias meta-setting for bulk aliasing:

from typing import Annotated
from dataclass_wizard import Alias, DataclassWizard


class Test(DataclassWizard):
    class _(DataclassWizard.Meta):
        load_case = 'CAMEL'
        field_to_alias_dump = {
            'my_int': 'MyInt',
        }

    my_str: str = Alias(load=('a_str', 'other_str'))
    my_bool_test: Annotated[bool, Alias(dump='myDumpedBool')]
    my_int: int
    other_int: int = Alias(dump='DumpedInt')


t = Test.from_dict({'other_str': 'test', 'myBoolTest': 'T', 'myInt': '123', 'otherInt': 321.0})
print(t.to_dict())
# > {'my_str': 'test', 'myDumpedBool': True, 'MyInt': 123, 'DumpedInt': 321}

Alias Paths

Maps one or more nested JSON paths to a dataclass field. See documentation on AliasPath() for more details.

Examples

Mapping multiple nested paths to a field:

from dataclasses import dataclass
from dataclass_wizard import fromdict, AliasPath


@dataclass
class Example:
    my_str: str = AliasPath('a.b.c.1', 'x.y["-1"].z', default="default_value")


print(fromdict(Example, {'x': {'y': {'-1': {'z': 'some_value'}}}}))
# > Example(my_str='some_value')

Using typing.Annotated with nested paths:

from typing import Annotated
from dataclass_wizard import AliasPath, DataclassWizard


class Example(DataclassWizard):
    my_str: Annotated[str, AliasPath('my."7".nested.path.-321')]


ex = Example.from_dict({'my': {'7': {'nested': {'path': {-321: 'Test'}}}}})
print(ex)  # > Example(my_str='Test')