Pydantic v2.9

#complex number support

We've added support for stdlib complex numbers in Pydantic. For validation, we support both complex instances and strings that can be parsed into complex numbers.

from pydantic import TypeAdapter


ta = TypeAdapter(complex)

complex_number = ta.validate_python('1+2j')
assert complex_number == complex(1, 2)

assert ta.dump_json(complex_number) == b'"1+2j"'

Credit for this goes to @changhc! For implementation details, see #9654.

#Explicit ZoneInfo support

Pydantic now supports the ZoneInfo type explicitly (in Python v3.9+). Here's an example of validation and serialization with the new type:

from pydantic import TypeAdapter
from zoneinfo import ZoneInfo

ta = TypeAdapter(ZoneInfo)

tz = ta.validate_python('America/Los_Angeles')
assert tz == ZoneInfo('America/Los_Angeles')

assert ta.dump_json(tz) == b'"America/Los_Angeles"'

Thanks for the contribution, @Youssefares! See #9896 for more details regarding the new implementation.

#val_json_bytes setting

The new val_json_bytes setting enables users to specify which encoding to use when decoding bytes data from JSON. This setting, in combination with the existing ser_json_bytes, supports consistent JSON round-tripping for bytes data.

For example:

from pydantic import TypeAdapter, ConfigDict

ta = TypeAdapter(bytes, config=ConfigDict(ser_json_bytes='base64', val_json_bytes='base64'))

some_bytes = b'hello'
validated_bytes = ta.validate_python(some_bytes)

encoded_bytes = b'"aGVsbG8="'
assert ta.dump_json(validated_bytes) == encoded_bytes

# verifying round trip
# before we added support for val_json_bytes, the default encoding was 'utf-8' for validation, so this would fail
assert ta.validate_json(encoded_bytes) == validated_bytes

Thanks for the addition, @josh-newman! You can see the full implementation details here.

#Support for JSON schema with custom validators

Previously, when using custom validators like BeforeValidator or field_validator, it wasn't possible to customize the mode='validation' JSON schema associated with the field / type in question.

Now, you can use the json_schema_input_type specification to customize the JSON schema for fields with custom validators. For example:

from typing import Any, Union

from pydantic_core import PydanticKnownError
from typing_extensions import Annotated

from pydantic import PlainValidator, TypeAdapter


def validate_maybe_int(v: Any) -> int:
    if isinstance(v, int):
        return v
    elif isinstance(v, str):
        try:
            return int(v)
        except ValueError:
            ...

    raise PydanticKnownError('int_parsing')


ta = TypeAdapter(Annotated[int, PlainValidator(validate_maybe_int, json_schema_input_type=Union[int, str])])
print(ta.json_schema(mode='validation'))
# > {'anyOf': [{'type': 'integer'}, {'type': 'string'}]}

!!! note You can't use this new feature with mode='after' validators, as customizing mode='validation' JSON schema doesn't make sense in this context.

For implementation details, see #10094. You can find documentation for json_schema_input_type in the API docs for all custom validators that support said specification.

#Tagged Union serialization

Pydantic is well known for its tagged union validation capabilities. In pydantic/pydantic-core#1397, we've added support for a tagged union serializer, which should make more intuitive serialization decisions when using tagged unions. We've also made some tangential fixes such as improving serialization choices for float | int, or Decimal | float unions.

#Moving annotation compatibility errors to validation phase

In general, during schema generation, Pydantic is generous in applying validator / constraint logic to types. This can backfire in some cases, when at runtime it becomes evident that a given validator / constraint isn't compatible with some input data. In this release, we've designed some more intuitive error messages for these cases, and moved them to the validation (runtime) phase, rather than failing in some valid cases at schema build time. For implementation details, see #9999

#Breaking change: Merge dict type json_schema_extra values, instead of overwriting

This change shouldn't affect anything except specialized usage of `json_schema_extra. That being said, if you'd like to replicate the old behavior, see these docs.

#Support sibling keys to $ref keys, thus removing allOf JSON schema workarounds

Any affected JSON syntax is now valid, and more simple! See #10029 for details.

#Deprecate passing a dict to the Examples class

This is relatively self-explanatory. See #10181 for more details. This change encourages syntactically valid JSON schemas.