JSON¶

Json Parsing¶

API Documentation

pydantic.main.BaseModel.model_validate_json
pydantic.type_adapter.TypeAdapter.validate_json
pydantic_core.from_json

Pydantic provides builtin JSON parsing, which helps achieve:

Significant performance improvements without the cost of using a 3rd party library
Support for custom errors
Support for strict specifications

Here's an example of Pydantic's builtin JSON parsing via the model_validate_json method, showcasing the support for strict specifications while parsing JSON data that doesn't match the model's type annotations:

Python 3.7 and abovePython 3.9 and above

from datetime import date
from typing import Tuple

from pydantic import BaseModel, ConfigDict, ValidationError


class Event(BaseModel):
    model_config = ConfigDict(strict=True)

    when: date
    where: Tuple[int, int]


json_data = '{"when": "1987-01-28", "where": [51, -1]}'
print(Event.model_validate_json(json_data))  # (1)!
#> when=datetime.date(1987, 1, 28) where=(51, -1)

try:
    Event.model_validate({'when': '1987-01-28', 'where': [51, -1]})  # (2)!
except ValidationError as e:
    print(e)
    """
    2 validation errors for Event
    when
      Input should be a valid date [type=date_type, input_value='1987-01-28', input_type=str]
    where
      Input should be a valid tuple [type=tuple_type, input_value=[51, -1], input_type=list]
    """

JSON has no date or tuple types, but Pydantic knows that so allows strings and arrays as inputs respectively when parsing JSON directly.
If you pass the same values to the model_validate method, Pydantic will raise a validation error because the strict configuration is enabled.

from datetime import date

from pydantic import BaseModel, ConfigDict, ValidationError


class Event(BaseModel):
    model_config = ConfigDict(strict=True)

    when: date
    where: tuple[int, int]


json_data = '{"when": "1987-01-28", "where": [51, -1]}'
print(Event.model_validate_json(json_data))  # (1)!
#> when=datetime.date(1987, 1, 28) where=(51, -1)

try:
    Event.model_validate({'when': '1987-01-28', 'where': [51, -1]})  # (2)!
except ValidationError as e:
    print(e)
    """
    2 validation errors for Event
    when
      Input should be a valid date [type=date_type, input_value='1987-01-28', input_type=str]
    where
      Input should be a valid tuple [type=tuple_type, input_value=[51, -1], input_type=list]
    """

JSON has no date or tuple types, but Pydantic knows that so allows strings and arrays as inputs respectively when parsing JSON directly.
If you pass the same values to the model_validate method, Pydantic will raise a validation error because the strict configuration is enabled.

In v2.5.0 and above, Pydantic uses jiter, a fast and iterable JSON parser, to parse JSON data. Using jiter compared to serde results in modest performance improvements that will get even better in the future.

The jiter JSON parser is almost entirely compatible with the serde JSON parser, with one noticeable enhancement being that jiter supports deserialization of inf and NaN values. In the future, jiter is intended to enable support validation errors to include the location in the original JSON input which contained the invalid value.

JSON Serialization¶

API Documentation

pydantic.main.BaseModel.model_dump_json
pydantic.type_adapter.TypeAdapter.dump_json
pydantic_core.to_json

For more information on JSON serialization, see the Serialization Concepts page.