Mapping Aliases and Attributes

To map input data from keys that do not match your internal field names, or to ingest data from Python objects instead of dictionaries, use field aliases and the from_attributes configuration.

Using Field Aliases for Validation

To map an input key to a different internal field name, define a validation_alias in a ModelField or TypedDictField. This allows you to handle incoming data with keys like field_a_alias while storing them internally as field_a.

from pydantic_core import SchemaValidator, core_schema

v = SchemaValidator(
    core_schema.model_fields_schema(
        fields={
            'field_a': core_schema.model_field(
                schema=core_schema.int_schema(),
                validation_alias='field_a_alias'
            )
        }
    )
)

# Validates from the alias
assert v.validate_python({'field_a_alias': 1}) == ({'field_a': 1}, None, {'field_a'})

Complex Alias Paths and Choices

The validation_alias supports more than just simple strings. You can provide a list of strings and integers to define a path into nested data, or a list of lists to provide multiple alternative lookup locations (choices).

v = SchemaValidator(
    core_schema.model_fields_schema(
        fields={
            'field_a': core_schema.model_field(
                # Look for input['foo']['bar']['bat'] OR input['foo'][3]
                validation_alias=[['foo', 'bar', 'bat'], ['foo', 3]], 
                schema=core_schema.int_schema()
            )
        }
    )
)

# Matches the first path
assert v.validate_python({'foo': {'bar': {'bat': 1}}}) == ({'field_a': 1}, None, {'field_a'})
# Matches the second path (index 3 of the list at 'foo')
assert v.validate_python({'foo': [0, 1, 2, 3]}) == ({'field_a': 3}, None, {'field_a'})

Mapping from Python Objects (ORM Style)

To validate data from arbitrary Python objects or ORM models using getattr instead of dictionary lookups, enable from_attributes in the CoreConfig or directly in the ModelFieldsSchema.

from pydantic_core import SchemaValidator, core_schema

class User:
    def __init__(self, id: int, name: str):
        self.id = id
        self.name = name

v = SchemaValidator(
    core_schema.model_fields_schema(
        fields={
            'id': core_schema.model_field(schema=core_schema.int_schema()),
            'name': core_schema.model_field(schema=core_schema.str_schema()),
        },
        from_attributes=True
    )
)

user_obj = User(id=1, name='John Doe')
# Validates directly from the object instance
assert v.validate_python(user_obj) == ({'id': 1, 'name': 'John Doe'}, None, {'id', 'name'})

Configuring Lookup Behavior

You can control whether fields are accessible by their internal names, their aliases, or both using CoreConfig settings.

Enabling Lookup by Name

By default, if an alias is defined, the field name itself is not used for validation. Set validate_by_name=True in CoreConfig to allow both the alias and the field name to be used.

from pydantic_core import SchemaValidator, core_schema, CoreConfig

v = SchemaValidator(
    core_schema.model_fields_schema(
        fields={'a': core_schema.model_field(schema=core_schema.int_schema(), validation_alias='a_alias')},
    ),
    config=CoreConfig(validate_by_name=True),
)

# Works with alias
assert v.validate_python({'a_alias': 1}) == ({'a': 1}, None, {'a'})
# Also works with field name because validate_by_name is True
assert v.validate_python({'a': 1}) == ({'a': 1}, None, {'a'})

Error Locations

The loc_by_alias setting in CoreConfig (which defaults to True) determines whether validation errors report the alias or the internal field name in the error loc.

v = SchemaValidator(
    core_schema.model_fields_schema(
        fields={'a': core_schema.model_field(schema=core_schema.int_schema(), validation_alias='a_alias')},
    ),
    config=CoreConfig(loc_by_alias=True),
)

try:
    v.validate_python({'a_alias': 'not an int'})
except Exception as e:
    # Error location uses the alias 'a_alias'
    assert e.errors()[0]['loc'] == ('a_alias',)

Troubleshooting

Missing Attributes

When from_attributes=True is enabled and you validate a Python object, pydantic-core attempts to access attributes using getattr(). If an attribute is missing from the object, it raises a missing error, identical to how it would behave if a key were missing from a dictionary.

Alias Precedence

If validate_by_name is False (the default), providing the internal field name in the input data when a validation_alias is defined will result in a "Field required" error, as the validator only looks for the alias.

Serialization Aliases

Note that validation_alias only affects data ingestion. To change the key name used when serializing data back out, you must define a serialization_alias in the ModelField or TypedDictField. By default, serialization uses the internal field name unless serialize_by_alias=True is set in the CoreConfig.