json_schema

23 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_schema module in Pydantic

Pydantic includes a json_schema module that provides functionality for JSON schema generation and handling. This module is part of the core Pydantic API.

JsonSchemaMode type alias

JsonSchemaMode is a type alias representing the available options for the mode parameter in model_json_schema and TypeAdapter.json_schema methods. The available modes are: 'validation' (produces JSON schema corresponding to the model's validation schema, the default) and 'serialization' (produces JSON schema corresponding to the model's serialization schema).

json_schema_extra dict vs Callable behavior

The json_schema_extra option can receive either a dict or a Callable. When a dict is passed, it is merged into the JSON schema. When a Callable is passed, it is called with the schema dict as argument to modify the schema in place. Starting in v2.9, json_schema_extra dictionaries from annotated types are merged additively rather than overridden. Mixing dict and callable json_schema_extra specifications is not supported.

WithJsonSchema annotation

WithJsonSchema is an annotation used to override the JSON Schema for a type. It is useful for types that don't produce JSON schemas by default (e.g. Callable). The annotation accepts a dict representing the complete JSON schema, and this overrides the whole generated JSON Schema for the type. WithJsonSchema is preferred over implementing __get_pydantic_json_schema__ for custom types as it is simpler and less error-prone.

SkipJsonSchema annotation

The SkipJsonSchema annotation can be used to skip an included field or part of a field's specifications from the generated JSON schema.

__get_pydantic_core_schema__ for custom types

Custom types and Annotated metadata can modify or override generated schema by implementing __get_pydantic_core_schema__. This method receives two positional arguments: 1) the type annotation (e.g. TheType[int] for TheType[T][int]), and 2) a handler/callback to call the next implementer. For custom types, you typically do not call the handler. For Annotated metadata, you can call handler(source) to get the CoreSchema from the type/inner constraints, then wrap or modify it. The method must always return a core_schema.CoreSchema.

__get_pydantic_json_schema__ implementation

Implementing __get_pydantic_json_schema__ modifies or overrides the generated JSON schema. This method only affects JSON schema generation, not the core schema used for validation and serialization. It receives the core_schema as first argument and a GetJsonSchemaHandler as second argument. The handler can be called to process the schema, and handler.resolve_ref_schema(json_schema) can be used to resolve reference schemas.

models_json_schema function for top-level schema

models_json_schema generates a top-level JSON schema that includes only a list of models and related sub-models in its $defs. It accepts a list of tuples where each tuple contains (model, mode) pairs, and a title parameter for the schema.

GenerateJsonSchema class for custom schema generation

GenerateJsonSchema is a class that implements the translation of a type's pydantic-core schema into JSON schema. It breaks the JSON schema generation process into smaller methods that can be overridden in subclasses to modify the approach to generating JSON schema. Custom subclasses can be passed as schema_generator parameter to model_json_schema, TypeAdapter.json_schema, and models_json_schema methods.

GenerateJsonSchema.sort method

GenerateJsonSchema has a sort method that recursively sorts JSON schemas by alphabetically sorting keys, while skipping sorting of values under the 'properties' key to preserve field order. This method can be overridden in custom subclasses to customize or disable sorting behavior.

field_title_generator function signature

The field_title_generator function accepts two parameters: field_name (str) and field_info (FieldInfo), and returns a string representing the generated title. It is used at field level in Field() or at model level in ConfigDict to programmatically generate field titles.

model_title_generator function signature

The model_title_generator function accepts one parameter: model (the model class as type), and returns a string representing the generated title. It is configured in ConfigDict to programmatically generate the model's title in JSON schema.

JSON schema type mapping priority order

Types, custom field types, and constraints are mapped to corresponding spec formats in the following priority order: 1) JSON Schema Core, 2) JSON Schema Validation, 3) OpenAPI Data Types, 4) The standard 'format' JSON field for Pydantic extensions for complex string sub-types.

model_json_schema and model_dump_json distinction

BaseModel.model_json_schema and TypeAdapter.json_schema return a jsonable dict representing the JSON schema of the model or type. This is different from BaseModel.model_dump_json and TypeAdapter.dump_json, which serialize instances and return JSON strings.

JSON schema for Optional fields

The JSON schema for Optional fields indicates that the value null is allowed.

Decimal type in JSON schema

The Decimal type is exposed in JSON schema and serialized as a string.

Sub-models in JSON schema $defs

Sub-models are added to the $defs JSON attribute and referenced according to JSON schema spec. However, sub-models with modifications via the Field class (such as custom title, description, or default value) are recursively included in the schema instead of referenced.

Model description in JSON schema

The description for models in JSON schema is taken from either the docstring of the class or the description argument to the Field class.

JSON schema generation by_alias default behavior

By default, JSON schema is generated using aliases as keys. It can be generated using model property names instead by calling model_json_schema() or model_dump_json() with the by_alias=False keyword argument.

ref_template parameter for customizing $refs

The ref_template parameter can be passed to model_json_schema() or model_dump_json() to customize the format of $refs in JSON schema. The definitions are always stored under the key $defs, but the specified prefix can be used for the references. Example: ref_template='#/components/schemas/{model}' for OpenAPI compatibility.

Pydantic compliance with JSON Schema specifications

Pydantic generates JSON schemas that are compliant with JSON Schema Draft 2020-12 and OpenAPI Specification v3.1.0.

PydanticOmit for excluding fields from schema

PydanticOmit from pydantic_core can be raised in GenerateJsonSchema.handle_invalid_for_json_schema to exclude fields from the JSON schema that don't have valid JSON schemas.

Field() JSON Schema customization parameters

Field() accepts parameters used exclusively for JSON schema customization: 'title', 'description', 'examples', and 'json_schema_extra'. These parameters do not affect validation or serialization behavior.

Give your agent this brain