json

14 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

JSON parsing with model_validate_json method

Pydantic provides builtin JSON parsing via the model_validate_json method. This method supports strict specifications and is documented at pydantic.main.BaseModel.model_validate_json.

Pydantic v2.5.0+ uses jiter JSON parser

Starting in v2.5.0, Pydantic uses jiter, a fast and iterable JSON parser, instead of serde. The jiter parser is almost entirely compatible with serde and provides modest performance improvements. A notable enhancement is that jiter supports deserialization of inf and NaN values.

Partial JSON parsing with pydantic_core.from_json

Pydantic v2.7.0 and above support partial JSON parsing via pydantic_core.from_json with the allow_partial parameter. When allow_partial=False (the default), incomplete JSON raises a ValueError. When allow_partial=True, the parser returns the successfully deserialized portion of the JSON, skipping incomplete nested structures. This is useful for validating incomplete LLM outputs.

Partial JSON parsing requires all model fields to have defaults

For partial JSON parsing to work reliably, all fields on the model should have default values. This prevents validation errors when fields are missing due to incomplete JSON data.

String caching in JSON parsing - cache_strings setting

Starting in v2.7.0, Pydantic's JSON parser offers configurable string caching via the cache_strings setting, available in model config and pydantic_core.from_json. Valid values are: True or 'all' (default, cache all strings), 'keys' (cache only dictionary keys, applies only with pydantic_core.from_json or Json type), False or 'none' (no caching). String caching improves performance but increases memory usage slightly.

String cache implementation details

The string cache in Pydantic's JSON parser uses a fully associative cache with a size of 16,384 entries. Only strings where len(string) < 64 are cached. There is overhead to cache lookups, so disabling caching with cache_strings=False may improve performance if data contains very few repeated strings.

JSON parsing example with strict mode and type coercion

Example showing JSON parsing with strict mode enabled: ```python 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)) #> when=datetime.date(1987, 1, 28) where=(51, -1) try: Event.model_validate({'when': '1987-01-28', 'where': [51, -1]}) except ValidationError as e: print(e) ``` The example demonstrates that model_validate_json coerces JSON strings to dates and arrays to tuples even in strict mode, while model_validate with the same Python values raises validation errors.

Partial JSON parsing example with from_json

Example of partial JSON parsing: ```python from pydantic_core import from_json partial_json_data = '["aa", "bb", "c' try: result = from_json(partial_json_data, allow_partial=False) except ValueError as e: print(e) #> EOF while parsing a string at line 1 column 15 result = from_json(partial_json_data, allow_partial=True) print(result) #> ['aa', 'bb'] ``` When allow_partial=False (default), incomplete JSON raises ValueError. When allow_partial=True, successfully parsed data is returned.

Combining partial JSON parsing with model validation

To validate partial JSON as a Pydantic model, use pydantic_core.from_json with allow_partial=True in combination with model_validate: ```python from pydantic_core import from_json from pydantic import BaseModel class Dog(BaseModel): breed: str name: str friends: list partial_dog_json = '{"breed": "lab", "name": "fluffy", "friends": ["buddy", "spot", "rufus"], "age' dog = Dog.model_validate(from_json(partial_dog_json, allow_partial=True)) print(repr(dog)) #> Dog(breed='lab', name='fluffy', friends=['buddy', 'spot', 'rufus']) ```

API documentation references for JSON parsing

JSON parsing documentation references: pydantic.main.BaseModel.model_validate_json, pydantic.type_adapter.TypeAdapter.validate_json, pydantic_core.from_json.

API documentation references for JSON serialization

JSON serialization documentation references: 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.

Partial JSON parsing with default values and WrapValidator

Example using partial JSON parsing with default values and custom validators: ```python from typing import Annotated, Any import pydantic_core from pydantic import BaseModel, ValidationError, WrapValidator def default_on_error(v, handler) -> Any: try: return handler(v) except ValidationError as exc: if all(e['type'] == 'missing' for e in exc.errors()): raise pydantic_core.PydanticUseDefault() else: raise class NestedModel(BaseModel): x: int y: str class MyModel(BaseModel): foo: str | None = None bar: Annotated[tuple[str, int] | None, WrapValidator(default_on_error)] = None nested: Annotated[NestedModel | None, WrapValidator(default_on_error)] = None m = MyModel.model_validate( pydantic_core.from_json('{"foo": "x", "bar": ["world",', allow_partial=True) ) print(repr(m)) #> MyModel(foo='x', bar=None, nested=None) ``` This pattern converts missing field errors from partial JSON parsing into default values using WrapValidator and PydanticUseDefault.

model_dump_json() serializes models directly to JSON strings

The model_dump_json() method serializes Pydantic models directly to JSON-encoded strings. Pydantic converts Python values to valid JSON data and supports a wide variety of types including date and time types, UUID objects, and sets beyond what the standard library json module supports.

PydanticSerializationError raised for unsupported types in JSON mode

If an unsupported type cannot be serialized to JSON during model_dump_json(), a PydanticSerializationError exception is raised. This often only becomes apparent when the object is actually serialized, commonly when building a response.

Give your agent this brain