json_schema

The json_schema module contains classes and functions to allow the way JSON Schema is generated to be customized.

In general you shouldn't need to use this module directly; instead, you can BaseModel.model_json_schema and TypeAdapter.json_schema.

CoreSchemaOrFieldType `module-attribute` ¶

CoreSchemaOrFieldType = Literal[
    core_schema.CoreSchemaType,
    core_schema.CoreSchemaFieldType,
]

A type alias for defined schema types that represents a union of core_schema.CoreSchemaType and core_schema.CoreSchemaFieldType.

JsonSchemaValue `module-attribute` ¶

JsonSchemaValue = Dict[str, Any]

A type alias for a JSON schema value. This is a dictionary of string keys to arbitrary values.

JsonSchemaMode `module-attribute` ¶

JsonSchemaMode = Literal['validation', 'serialization']

A type alias that represents the mode of a JSON schema; either 'validation' or 'serialization'.

For some types, the inputs to validation differ from the outputs of serialization. For example, computed fields will only be present when serializing, and should not be provided when validating. This flag provides a way to indicate whether you want the JSON schema required for validation inputs, or that will be matched by serialization outputs.

JsonSchemaWarningKind `module-attribute` ¶

JsonSchemaWarningKind = Literal[
    "skipped-choice", "non-serializable-default"
]

A type alias representing the kinds of warnings that can be emitted during JSON schema generation.

See GenerateJsonSchema.render_warning_message for more details.

DEFAULT_REF_TEMPLATE `module-attribute` ¶

DEFAULT_REF_TEMPLATE = '#/$defs/{model}'

The default format string used to generate reference names.

PydanticJsonSchemaWarning ¶

Bases: UserWarning

This class is used to emit warnings produced during JSON schema generation. See the GenerateJsonSchema.emit_warning and GenerateJsonSchema.render_warning_message methods for more details; these can be overridden to control warning behavior.

GenerateJsonSchema ¶

GenerateJsonSchema(
    by_alias=True, ref_template=DEFAULT_REF_TEMPLATE
)

A class for generating JSON schemas.

This class generates JSON schemas based on configured parameters. The default schema dialect is https://json-schema.org/draft/2020-12/schema. The class uses by_alias to configure how fields with multiple names are handled and ref_template to format reference names.

Attributes:

Name	Type	Description
`schema_dialect`		The JSON schema dialect used to generate the schema. See Declaring a Dialect in the JSON Schema documentation for more information about dialects.
`ignored_warning_kinds`	`set[JsonSchemaWarningKind]`	Warnings to ignore when generating the schema. `self.render_warning_message` will do nothing if its argument `kind` is in `ignored_warning_kinds`; this value can be modified on subclasses to easily control which warnings are emitted.
`by_alias`		Whether or not to use field names when generating the schema.
`ref_template`		The format string used when generating reference names.
`core_to_json_refs`	`dict[CoreModeRef, JsonRef]`	A mapping of core refs to JSON refs.
`core_to_defs_refs`	`dict[CoreModeRef, DefsRef]`	A mapping of core refs to definition refs.
`defs_to_core_refs`	`dict[DefsRef, CoreModeRef]`	A mapping of definition refs to core refs.
`json_to_defs_refs`	`dict[JsonRef, DefsRef]`	A mapping of JSON refs to definition refs.
`definitions`	`dict[DefsRef, JsonSchemaValue]`	Definitions in the schema.
`collisions`	`dict[DefsRef, JsonSchemaValue]`	Definitions with colliding names. When collisions are detected, we choose a non-colliding name during generation, but we also track the colliding tag so that it can be remapped for the first occurrence at the end of the process.
`defs_ref_fallbacks`	`dict[DefsRef, JsonSchemaValue]`	Core refs to fallback definitions refs.
`_schema_type_to_method`		A mapping of schema types to generator methods.
`_used`		Set to `True` after generating a schema to avoid re-use issues.
`mode`	`JsonSchemaMode`	The schema mode.

Parameters:

Name	Type	Description	Default
`by_alias`	`bool`	Whether or not to include field names.	`True`
`ref_template`	`str`	The format string to use when generating reference names.	`DEFAULT_REF_TEMPLATE`

Raises:

Type	Description
`JsonSchemaError`	If the instance of the class is inadvertently re-used after generating a schema.

Source code in pydantic/json_schema.py

def __init__(self, by_alias: bool = True, ref_template: str = DEFAULT_REF_TEMPLATE):
    self.by_alias = by_alias
    self.ref_template = ref_template

    self.core_to_json_refs: dict[CoreModeRef, JsonRef] = {}
    self.core_to_defs_refs: dict[CoreModeRef, DefsRef] = {}
    self.defs_to_core_refs: dict[DefsRef, CoreModeRef] = {}
    self.json_to_defs_refs: dict[JsonRef, DefsRef] = {}

    self.definitions: dict[DefsRef, JsonSchemaValue] = {}

    self.mode: JsonSchemaMode = 'validation'

    # The following includes a mapping of a fully-unique defs ref choice to a list of preferred
    # alternatives, which are generally simpler, such as only including the class name.
    # At the end of schema generation, we use these to produce a JSON schema with more human-readable
    # definitions, which would also work better in a generated OpenAPI client, etc.
    self._prioritized_defsref_choices: dict[DefsRef, list[DefsRef]] = {}
    self._collision_counter: dict[str, int] = defaultdict(int)
    self._collision_index: dict[str, int] = {}

    self._schema_type_to_method = self.build_schema_type_to_method()

    # When we encounter definitions we need to try to build them immediately
    # so that they are available schemas that reference them
    # But it's possible that that CoreSchema was never going to be used
    # (e.g. because the CoreSchema that references short circuits is JSON schema generation without needing
    #  the reference) so instead of failing altogether if we can't build a definition we
    # store the error raised and re-throw it if we end up needing that def
    self._core_defs_invalid_for_json_schema: dict[DefsRef, PydanticInvalidForJsonSchema] = {}

    # This changes to True after generating a schema, to prevent issues caused by accidental re-use
    # of a single instance of a schema generator
    self._used = False

ValidationsMapping ¶

This class just contains mappings from core_schema attribute names to the corresponding JSON schema attribute names. While I suspect it is unlikely to be necessary, you can in principle override this class in a subclass of GenerateJsonSchema (by inheriting from GenerateJsonSchema.ValidationsMapping) to change these mappings.

build_schema_type_to_method ¶

build_schema_type_to_method()

Builds a dictionary mapping fields to methods for generating JSON schemas.

Returns:

Type	Description
`dict[CoreSchemaOrFieldType, Callable[[CoreSchemaOrField], JsonSchemaValue]]`	A dictionary containing the mapping of `CoreSchemaOrFieldType` to a handler method.

Raises:

Type	Description
`TypeError`	If no method has been defined for generating a JSON schema for a given pydantic core schema type.

Source code in pydantic/json_schema.py

def build_schema_type_to_method(
    self,
) -> dict[CoreSchemaOrFieldType, Callable[[CoreSchemaOrField], JsonSchemaValue]]:
    """Builds a dictionary mapping fields to methods for generating JSON schemas.

    Returns:
        A dictionary containing the mapping of `CoreSchemaOrFieldType` to a handler method.

    Raises:
        TypeError: If no method has been defined for generating a JSON schema for a given pydantic core schema type.
    """
    mapping: dict[CoreSchemaOrFieldType, Callable[[CoreSchemaOrField], JsonSchemaValue]] = {}
    core_schema_types: list[CoreSchemaOrFieldType] = _typing_extra.all_literal_values(
        CoreSchemaOrFieldType  # type: ignore
    )
    for key in core_schema_types:
        method_name = f"{key.replace('-', '_')}_schema"
        try:
            mapping[key] = getattr(self, method_name)
        except AttributeError as e:  # pragma: no cover
            raise TypeError(
                f'No method for generating JsonSchema for core_schema.type={key!r} '
                f'(expected: {type(self).__name__}.{method_name})'
            ) from e
    return mapping

generate_definitions ¶

generate_definitions(inputs)

Generates JSON schema definitions from a list of core schemas, pairing the generated definitions with a mapping that links the input keys to the definition references.

Parameters:

Name	Type	Description	Default
`inputs`	`Sequence[tuple[JsonSchemaKeyT, JsonSchemaMode, core_schema.CoreSchema]]`	A sequence of tuples, where: The first element is a JSON schema key type. The second element is the JSON mode: either 'validation' or 'serialization'. The third element is a core schema.	required

Returns:

Type Description

tuple[dict[tuple[JsonSchemaKeyT, JsonSchemaMode], JsonSchemaValue], dict[DefsRef, JsonSchemaValue]]

A tuple where:

The first element is a dictionary whose keys are tuples of JSON schema key type and JSON mode, and whose values are the JSON schema corresponding to that pair of inputs. (These schemas may have JsonRef references to definitions that are defined in the second returned element.)
The second element is a dictionary whose keys are definition references for the JSON schemas from the first returned element, and whose values are the actual JSON schema definitions.

Raises:

Type	Description
`PydanticUserError`	Raised if the JSON schema generator has already been used to generate a JSON schema.

Source code in pydantic/json_schema.py

def generate_definitions(
    self, inputs: Sequence[tuple[JsonSchemaKeyT, JsonSchemaMode, core_schema.CoreSchema]]
) -> tuple[dict[tuple[JsonSchemaKeyT, JsonSchemaMode], JsonSchemaValue], dict[DefsRef, JsonSchemaValue]]:
    """Generates JSON schema definitions from a list of core schemas, pairing the generated definitions with a
    mapping that links the input keys to the definition references.

    Args:
        inputs: A sequence of tuples, where:

            - The first element is a JSON schema key type.
            - The second element is the JSON mode: either 'validation' or 'serialization'.
            - The third element is a core schema.

    Returns:
        A tuple where:

            - The first element is a dictionary whose keys are tuples of JSON schema key type and JSON mode, and
                whose values are the JSON schema corresponding to that pair of inputs. (These schemas may have
                JsonRef references to definitions that are defined in the second returned element.)
            - The second element is a dictionary whose keys are definition references for the JSON schemas
                from the first returned element, and whose values are the actual JSON schema definitions.

    Raises:
        PydanticUserError: Raised if the JSON schema generator has already been used to generate a JSON schema.
    """
    if self._used:
        raise PydanticUserError(
            'This JSON schema generator has already been used to generate a JSON schema. '
            f'You must create a new instance of {type(self).__name__} to generate a new JSON schema.',
            code='json-schema-already-used',
        )

    for key, mode, schema in inputs:
        self.mode = mode
        self.generate_inner(schema)

    definitions_remapping = self._build_definitions_remapping()

    json_schemas_map: dict[tuple[JsonSchemaKeyT, JsonSchemaMode], DefsRef] = {}
    for key, mode, schema in inputs:
        self.mode = mode
        json_schema = self.generate_inner(schema)
        json_schemas_map[(key, mode)] = definitions_remapping.remap_json_schema(json_schema)

    json_schema = {'$defs': self.definitions}
    json_schema = definitions_remapping.remap_json_schema(json_schema)
    self._used = True
    return json_schemas_map, _sort_json_schema(json_schema['$defs'])  # type: ignore

generate ¶

generate(schema, mode='validation')

Generates a JSON schema for a specified schema in a specified mode.

Parameters:

Name	Type	Description	Default
`schema`	`CoreSchema`	A Pydantic model.	required
`mode`	`JsonSchemaMode`	The mode in which to generate the schema. Defaults to 'validation'.	`'validation'`

Returns:

Type	Description
`JsonSchemaValue`	A JSON schema representing the specified schema.

Raises:

Type	Description
`PydanticUserError`	If the JSON schema generator has already been used to generate a JSON schema.

Source code in pydantic/json_schema.py

def generate(self, schema: CoreSchema, mode: JsonSchemaMode = 'validation') -> JsonSchemaValue:
    """Generates a JSON schema for a specified schema in a specified mode.

    Args:
        schema: A Pydantic model.
        mode: The mode in which to generate the schema. Defaults to 'validation'.

    Returns:
        A JSON schema representing the specified schema.

    Raises:
        PydanticUserError: If the JSON schema generator has already been used to generate a JSON schema.
    """
    self.mode = mode
    if self._used:
        raise PydanticUserError(
            'This JSON schema generator has already been used to generate a JSON schema. '
            f'You must create a new instance of {type(self).__name__} to generate a new JSON schema.',
            code='json-schema-already-used',
        )

    json_schema: JsonSchemaValue = self.generate_inner(schema)
    json_ref_counts = self.get_json_ref_counts(json_schema)

    # Remove the top-level $ref if present; note that the _generate method already ensures there are no sibling keys
    ref = cast(JsonRef, json_schema.get('$ref'))
    while ref is not None:  # may need to unpack multiple levels
        ref_json_schema = self.get_schema_from_definitions(ref)
        if json_ref_counts[ref] > 1 or ref_json_schema is None:
            # Keep the ref, but use an allOf to remove the top level $ref
            json_schema = {'allOf': [{'$ref': ref}]}
        else:
            # "Unpack" the ref since this is the only reference
            json_schema = ref_json_schema.copy()  # copy to prevent recursive dict reference
            json_ref_counts[ref] -= 1
        ref = cast(JsonRef, json_schema.get('$ref'))

    self._garbage_collect_definitions(json_schema)
    definitions_remapping = self._build_definitions_remapping()

    if self.definitions:
        json_schema['$defs'] = self.definitions

    json_schema = definitions_remapping.remap_json_schema(json_schema)

    # For now, we will not set the $schema key. However, if desired, this can be easily added by overriding
    # this method and adding the following line after a call to super().generate(schema):
    # json_schema['$schema'] = self.schema_dialect

    self._used = True
    return _sort_json_schema(json_schema)

generate_inner ¶

generate_inner(schema)

Generates a JSON schema for a given core schema.

Parameters:

Name	Type	Description	Default
`schema`	`CoreSchemaOrField`	The given core schema.	required

Returns:

Type	Description
`JsonSchemaValue`	The generated JSON schema.

Source code in pydantic/json_schema.py

def generate_inner(self, schema: CoreSchemaOrField) -> JsonSchemaValue:  # noqa: C901
    """Generates a JSON schema for a given core schema.

    Args:
        schema: The given core schema.

    Returns:
        The generated JSON schema.
    """
    # If a schema with the same CoreRef has been handled, just return a reference to it
    # Note that this assumes that it will _never_ be the case that the same CoreRef is used
    # on types that should have different JSON schemas
    if 'ref' in schema:
        core_ref = CoreRef(schema['ref'])  # type: ignore[typeddict-item]
        core_mode_ref = (core_ref, self.mode)
        if core_mode_ref in self.core_to_defs_refs and self.core_to_defs_refs[core_mode_ref] in self.definitions:
            return {'$ref': self.core_to_json_refs[core_mode_ref]}

    # Generate the JSON schema, accounting for the json_schema_override and core_schema_override
    metadata_handler = _core_metadata.CoreMetadataHandler(schema)

    def populate_defs(core_schema: CoreSchema, json_schema: JsonSchemaValue) -> JsonSchemaValue:
        if 'ref' in core_schema:
            core_ref = CoreRef(core_schema['ref'])  # type: ignore[typeddict-item]
            defs_ref, ref_json_schema = self.get_cache_defs_ref_schema(core_ref)
            json_ref = JsonRef(ref_json_schema['$ref'])
            self.json_to_defs_refs[json_ref] = defs_ref
            # Replace the schema if it's not a reference to itself
            # What we want to avoid is having the def be just a ref to itself
            # which is what would happen if we blindly assigned any
            if json_schema.get('$ref', None) != json_ref:
                self.definitions[defs_ref] = json_schema
                self._core_defs_invalid_for_json_schema.pop(defs_ref, None)
            json_schema = ref_json_schema
        return json_schema

    def convert_to_all_of(json_schema: JsonSchemaValue) -> JsonSchemaValue:
        if '$ref' in json_schema and len(json_schema.keys()) > 1:
            # technically you can't have any other keys next to a "$ref"
            # but it's an easy mistake to make and not hard to correct automatically here
            json_schema = json_schema.copy()
            ref = json_schema.pop('$ref')
            json_schema = {'allOf': [{'$ref': ref}], **json_schema}
        return json_schema

    def handler_func(schema_or_field: CoreSchemaOrField) -> JsonSchemaValue:
        """Generate a JSON schema based on the input schema.

        Args:
            schema_or_field: The core schema to generate a JSON schema from.

        Returns:
            The generated JSON schema.

        Raises:
            TypeError: If an unexpected schema type is encountered.
        """
        # Generate the core-schema-type-specific bits of the schema generation:
        json_schema: JsonSchemaValue | None = None
        if self.mode == 'serialization' and 'serialization' in schema_or_field:
            ser_schema = schema_or_field['serialization']  # type: ignore
            json_schema = self.ser_schema(ser_schema)
        if json_schema is None:
            if _core_utils.is_core_schema(schema_or_field) or _core_utils.is_core_schema_field(schema_or_field):
                generate_for_schema_type = self._schema_type_to_method[schema_or_field['type']]
                json_schema = generate_for_schema_type(schema_or_field)
            else:
                raise TypeError(f'Unexpected schema type: schema={schema_or_field}')
        if _core_utils.is_core_schema(schema_or_field):
            json_schema = populate_defs(schema_or_field, json_schema)
            json_schema = convert_to_all_of(json_schema)
        return json_schema

    current_handler = _schema_generation_shared.GenerateJsonSchemaHandler(self, handler_func)

    for js_modify_function in metadata_handler.metadata.get('pydantic_js_functions', ()):

        def new_handler_func(
            schema_or_field: CoreSchemaOrField,
            current_handler: GetJsonSchemaHandler = current_handler,
            js_modify_function: GetJsonSchemaFunction = js_modify_function,
        ) -> JsonSchemaValue:
            json_schema = js_modify_function(schema_or_field, current_handler)
            if _core_utils.is_core_schema(schema_or_field):
                json_schema = populate_defs(schema_or_field, json_schema)
            original_schema = current_handler.resolve_ref_schema(json_schema)
            ref = json_schema.pop('$ref', None)
            if ref and json_schema:
                original_schema.update(json_schema)
            return original_schema

        current_handler = _schema_generation_shared.GenerateJsonSchemaHandler(self, new_handler_func)

    for js_modify_function in metadata_handler.metadata.get('pydantic_js_annotation_functions', ()):

        def new_handler_func(
            schema_or_field: CoreSchemaOrField,
            current_handler: GetJsonSchemaHandler = current_handler,
            js_modify_function: GetJsonSchemaFunction = js_modify_function,
        ) -> JsonSchemaValue:
            json_schema = js_modify_function(schema_or_field, current_handler)
            if _core_utils.is_core_schema(schema_or_field):
                json_schema = populate_defs(schema_or_field, json_schema)
                json_schema = convert_to_all_of(json_schema)
            return json_schema

        current_handler = _schema_generation_shared.GenerateJsonSchemaHandler(self, new_handler_func)

    json_schema = current_handler(schema)
    if _core_utils.is_core_schema(schema):
        json_schema = populate_defs(schema, json_schema)
        json_schema = convert_to_all_of(json_schema)
    return json_schema

any_schema ¶

any_schema(schema)

Generates a JSON schema that matches any value.

Parameters:

Name	Type	Description	Default
`schema`	`core_schema.AnySchema`	The core schema.	required

Returns:

Type	Description
`JsonSchemaValue`	The generated JSON schema.

Source code in pydantic/json_schema.py

def any_schema(self, schema: core_schema.AnySchema) -> JsonSchemaValue:
    """Generates a JSON schema that matches any value.

    Args:
        schema: The core schema.

    Returns:
        The generated JSON schema.
    """
    return {}

none_schema ¶

none_schema(schema)

Generates a JSON schema that matches a None value.

Parameters:

Name	Type	Description	Default
`schema`	`core_schema.NoneSchema`	The core schema.	required

Returns:

Type	Description
`JsonSchemaValue`	The generated JSON schema.

Source code in pydantic/json_schema.py

def none_schema(self, schema: core_schema.NoneSchema) -> JsonSchemaValue:
    """Generates a JSON schema that matches a None value.

    Args:
        schema: The core schema.

    Returns:
        The generated JSON schema.
    """
    return {'type': 'null'}

bool_schema ¶

bool_schema(schema)

Generates a JSON schema that matches a bool value.

Parameters:

Name	Type	Description	Default
`schema`	`core_schema.BoolSchema`	The core schema.	required

Returns:

Type	Description
`JsonSchemaValue`	The generated JSON schema.

Source code in pydantic/json_schema.py

def bool_schema(self, schema: core_schema.BoolSchema) -> JsonSchemaValue:
    """Generates a JSON schema that matches a bool value.

    Args:
        schema: The core schema.

    Returns:
        The generated JSON schema.
    """
    return {'type': 'boolean'}

int_schema ¶

int_schema(schema)

Generates a JSON schema that matches an Int value.

Parameters:

Name	Type	Description	Default
`schema`	`core_schema.IntSchema`	The core schema.	required

Returns:

Type	Description
`JsonSchemaValue`	The generated JSON schema.

Source code in pydantic/json_schema.py

def int_schema(self, schema: core_schema.IntSchema) -> JsonSchemaValue:
    """Generates a JSON schema that matches an Int value.

    Args:
        schema: The core schema.

    Returns:
        The generated JSON schema.
    """
    json_schema: dict[str, Any] = {'type': 'integer'}
    self.update_with_validations(json_schema, schema, self.ValidationsMapping.numeric)
    json_schema = {k: v for k, v in json_schema.items() if v not in {math.inf, -math.inf}}
    return json_schema

float_schema ¶

float_schema(schema)

Generates a JSON schema that matches a float value.

Parameters:

Name	Type	Description	Default
`schema`	`core_schema.FloatSchema`	The core schema.	required

Returns:

Type	Description
`JsonSchemaValue`	The generated JSON schema.

Source code in pydantic/json_schema.py

def float_schema(self, schema: core_schema.FloatSchema) -> JsonSchemaValue:
    """Generates a JSON schema that matches a float value.

    Args:
        schema: The core schema.

    Returns:
        The generated JSON schema.
    """
    json_schema: dict[str, Any] = {'type': 'number'}
    self.update_with_validations(json_schema, schema, self.ValidationsMapping.numeric)
    json_schema = {k: v for k, v in json_schema.items() if v not in {math.inf, -math.inf}}
    return json_schema

str_schema ¶

str_schema(schema)

Generates a JSON schema that matches a string value.

Parameters:

Name	Type	Description	Default
`schema`	`core_schema.StringSchema`	The core schema.	required

Returns:

Type	Description
`JsonSchemaValue`	The generated JSON schema.

Source code in pydantic/json_schema.py

def str_schema(self, schema: core_schema.StringSchema) -> JsonSchemaValue:
    """Generates a JSON schema that matches a string value.

    Args:
        schema: The core schema.

    Returns:
        The generated JSON schema.
    """
    json_schema = {'type': 'string'}
    self.update_with_validations(json_schema, schema, self.ValidationsMapping.string)
    return json_schema

bytes_schema ¶

bytes_schema(schema)

Generates a JSON schema that matches a bytes value.

Parameters:

Name	Type	Description	Default
`schema`	`core_schema.BytesSchema`	The core schema.	required

Returns:

Type	Description
`JsonSchemaValue`	The generated JSON schema.

Source code in pydantic/json_schema.py

def bytes_schema(self, schema: core_schema.BytesSchema) -> JsonSchemaValue:
    """Generates a JSON schema that matches a bytes value.

    Args:
        schema: The core schema.

    Returns:
        The generated JSON schema.
    """
    json_schema = {'type': 'string', 'format': 'binary'}
    self.update_with_validations(json_schema, schema, self.ValidationsMapping.bytes)
    return json_schema

date_schema ¶

date_schema(schema)

Generates a JSON schema that matches a date value.

Parameters:

Name	Type	Description	Default
`schema`	`core_schema.DateSchema`	The core schema.	required

Returns:

Type	Description
`JsonSchemaValue`	The generated JSON schema.

Source code in pydantic/json_schema.py

def date_schema(self, schema: core_schema.DateSchema) -> JsonSchemaValue:
    """Generates a JSON schema that matches a date value.

    Args:
        schema: The core schema.

    Returns:
        The generated JSON schema.
    """
    json_schema = {'type': 'string', 'format': 'date'}
    self.update_with_validations(json_schema, schema, self.ValidationsMapping.date)
    return json_schema

time_schema ¶

time_schema(schema)

Generates a JSON schema that matches a time value.

Parameters:

Name	Type	Description	Default
`schema`	`core_schema.TimeSchema`	The core schema.	required

Returns:

Type	Description
`JsonSchemaValue`	The generated JSON schema.

Source code in pydantic/json_schema.py

def time_schema(self, schema: core_schema.TimeSchema) -> JsonSchemaValue:
    """Generates a JSON schema that matches a time value.

    Args:
        schema: The core schema.

    Returns:
        The generated JSON schema.
    """
    return {'type': 'string', 'format': 'time'}

datetime_schema ¶

datetime_schema(schema)

Generates a JSON schema that matches a datetime value.

Parameters:

Name	Type	Description	Default
`schema`	`core_schema.DatetimeSchema`	The core schema.	required

Returns:

Type	Description
`JsonSchemaValue`	The generated JSON schema.

Source code in pydantic/json_schema.py

def datetime_schema(self, schema: core_schema.DatetimeSchema) -> JsonSchemaValue:
    """Generates a JSON schema that matches a datetime value.

    Args:
        schema: The core schema.

    Returns:
        The generated JSON schema.
    """
    return {'type': 'string', 'format': 'date-time'}

timedelta_schema ¶

timedelta_schema(schema)

Generates a JSON schema that matches a timedelta value.

Parameters:

Name	Type	Description	Default
`schema`	`core_schema.TimedeltaSchema`	The core schema.	required

Returns:

Type	Description
`JsonSchemaValue`	The generated JSON schema.

Source code in pydantic/json_schema.py

def timedelta_schema(self, schema: core_schema.TimedeltaSchema) -> JsonSchemaValue:
    """Generates a JSON schema that matches a timedelta value.

    Args:
        schema: The core schema.

    Returns:
        The generated JSON schema.
    """
    return {'type': 'string', 'format': 'duration'}

literal_schema ¶

literal_schema(schema)

Generates a JSON schema that matches a literal value.

Parameters:

Name	Type	Description	Default
`schema`	`core_schema.LiteralSchema`	The core schema.	required

Returns:

Type	Description
`JsonSchemaValue`	The generated JSON schema.

Source code in pydantic/json_schema.py

def literal_schema(self, schema: core_schema.LiteralSchema) -> JsonSchemaValue:
    """Generates a JSON schema that matches a literal value.

    Args:
        schema: The core schema.

    Returns:
        The generated JSON schema.
    """
    expected = [v.value if isinstance(v, Enum) else v for v in schema['expected']]

    if len(expected) == 1:
        return {'const': expected[0]}

    types = {type(e) for e in expected}
    if types == {str}:
        return {'enum': expected, 'type': 'string'}
    elif types == {int}:
        return {'enum': expected, 'type': 'integer'}
    elif types == {float}:
        return {'enum': expected, 'type': 'number'}
    elif types == {bool}:
        return {'enum': expected, 'type': 'boolean'}
    elif types == {list}:
        return {'enum': expected, 'type': 'array'}
    # there is not None case because if it's mixed it hits the final `else`
    # if it's a single Literal[None] then it becomes a `const` schema above
    else:
        return {'enum': expected}

is_instance_schema ¶

is_instance_schema(schema)

Generates a JSON schema that checks if a value is an instance of a class, equivalent to Python's isinstance method.

Parameters:

Name	Type	Description	Default
`schema`	`core_schema.IsInstanceSchema`	The core schema.	required

Returns:

Type	Description
`JsonSchemaValue`	The generated JSON schema.

Source code in pydantic/json_schema.py

def is_instance_schema(self, schema: core_schema.IsInstanceSchema) -> JsonSchemaValue:
    """Generates a JSON schema that checks if a value is an instance of a class, equivalent to Python's
    `isinstance` method.

    Args:
        schema: The core schema.

    Returns:
        The generated JSON schema.
    """
    return self.handle_invalid_for_json_schema(schema, f'core_schema.IsInstanceSchema ({schema["cls"]})')

is_subclass_schema ¶

is_subclass_schema(schema)

Generates a JSON schema that checks if a value is a subclass of a class, equivalent to Python's issubclass method.

Parameters:

Name	Type	Description	Default
`schema`	`core_schema.IsSubclassSchema`	The core schema.	required

Returns:

Type	Description
`JsonSchemaValue`	The generated JSON schema.

Source code in pydantic/json_schema.py

def is_subclass_schema(self, schema: core_schema.IsSubclassSchema) -> JsonSchemaValue:
    """Generates a JSON schema that checks if a value is a subclass of a class, equivalent to Python's `issubclass`
    method.

    Args:
        schema: The core schema.

    Returns:
        The generated JSON schema.
    """
    # Note: This is for compatibility with V1; you can override if you want different behavior.
    return {}

callable_schema ¶

callable_schema(schema)

Generates a JSON schema that matches a callable value.

Parameters:

Name	Type	Description	Default
`schema`	`core_schema.CallableSchema`	The core schema.	required

Returns:

Type	Description
`JsonSchemaValue`	The generated JSON schema.

Source code in pydantic/json_schema.py

def callable_schema(self, schema: core_schema.CallableSchema) -> JsonSchemaValue:
    """Generates a JSON schema that matches a callable value.

    Args:
        schema: The core schema.

    Returns:
        The generated JSON schema.
    """
    return self.handle_invalid_for_json_schema(schema, 'core_schema.CallableSchema')

list_schema ¶

list_schema(schema)

Returns a schema that matches a list schema.

Parameters:

Name	Type	Description	Default
`schema`	`core_schema.ListSchema`	The core schema.	required

Returns:

Type	Description
`JsonSchemaValue`	The generated JSON schema.

Source code in pydantic/json_schema.py

def list_schema(self, schema: core_schema.ListSchema) -> JsonSchemaValue:
    """Returns a schema that matches a list schema.

    Args:
        schema: The core schema.

    Returns:
        The generated JSON schema.
    """
    items_schema = {} if 'items_schema' not in schema else self.generate_inner(schema['items_schema'])
    json_schema = {'type': 'array', 'items': items_schema}
    self.update_with_validations(json_schema, schema, self.ValidationsMapping.array)
    return json_schema

tuple_positional_schema ¶

tuple_positional_schema(schema)

Generates a JSON schema that matches a positional tuple schema e.g. Tuple[int, str, bool].

Parameters:

Name	Type	Description	Default
`schema`	`core_schema.TuplePositionalSchema`	The core schema.	required

Returns:

Type	Description
`JsonSchemaValue`	The generated JSON schema.

Source code in pydantic/json_schema.py

def tuple_positional_schema(self, schema: core_schema.TuplePositionalSchema) -> JsonSchemaValue:
    """Generates a JSON schema that matches a positional tuple schema e.g. `Tuple[int, str, bool]`.

    Args:
        schema: The core schema.

    Returns:
        The generated JSON schema.
    """
    json_schema: JsonSchemaValue = {'type': 'array'}
    json_schema['minItems'] = len(schema['items_schema'])
    prefixItems = [self.generate_inner(item) for item in schema['items_schema']]
    if prefixItems:
        json_schema['prefixItems'] = prefixItems
    if 'extra_schema' in schema:
        json_schema['items'] = self.generate_inner(schema['extra_schema'])
    else:
        json_schema['maxItems'] = len(schema['items_schema'])
    self.update_with_validations(json_schema, schema, self.ValidationsMapping.array)
    return json_schema

tuple_variable_schema ¶

tuple_variable_schema(schema)

Generates a JSON schema that matches a variable tuple schema e.g. Tuple[int, ...].

Parameters:

Name	Type	Description	Default
`schema`	`core_schema.TupleVariableSchema`	The core schema.	required

Returns:

Type	Description
`JsonSchemaValue`	The generated JSON schema.

Source code in pydantic/json_schema.py

def tuple_variable_schema(self, schema: core_schema.TupleVariableSchema) -> JsonSchemaValue:
    """Generates a JSON schema that matches a variable tuple schema e.g. `Tuple[int, ...]`.

    Args:
        schema: The core schema.

    Returns:
        The generated JSON schema.
    """
    items_schema = {} if 'items_schema' not in schema else self.generate_inner(schema['items_schema'])
    json_schema = {'type': 'array', 'items': items_schema}
    self.update_with_validations(json_schema, schema, self.ValidationsMapping.array)
    return json_schema

set_schema ¶

set_schema(schema)

Generates a JSON schema that matches a set schema.

Parameters:

Name	Type	Description	Default
`schema`	`core_schema.SetSchema`	The core schema.	required

Returns:

Type	Description
`JsonSchemaValue`	The generated JSON schema.

Source code in pydantic/json_schema.py

def set_schema(self, schema: core_schema.SetSchema) -> JsonSchemaValue:
    """Generates a JSON schema that matches a set schema.

    Args:
        schema: The core schema.

    Returns:
        The generated JSON schema.
    """
    return self._common_set_schema(schema)

frozenset_schema ¶

frozenset_schema(schema)

Generates a JSON schema that matches a frozenset schema.

Parameters:

Name	Type	Description	Default
`schema`	`core_schema.FrozenSetSchema`	The core schema.	required

Returns:

Type	Description
`JsonSchemaValue`	The generated JSON schema.

Source code in pydantic/json_schema.py

def frozenset_schema(self, schema: core_schema.FrozenSetSchema) -> JsonSchemaValue:
    """Generates a JSON schema that matches a frozenset schema.

    Args:
        schema: The core schema.

    Returns:
        The generated JSON schema.
    """
    return self._common_set_schema(schema)

generator_schema ¶

generator_schema(schema)

Returns a JSON schema that represents the provided GeneratorSchema.

Parameters:

Name	Type	Description	Default
`schema`	`core_schema.GeneratorSchema`	The schema.	required

Returns:

Type	Description
`JsonSchemaValue`	The generated JSON schema.

Source code in pydantic/json_schema.py

def generator_schema(self, schema: core_schema.GeneratorSchema) -> JsonSchemaValue:
    """Returns a JSON schema that represents the provided GeneratorSchema.

    Args:
        schema: The schema.

    Returns:
        The generated JSON schema.
    """
    items_schema = {} if 'items_schema' not in schema else self.generate_inner(schema['items_schema'])
    json_schema = {'type': 'array', 'items': items_schema}
    self.update_with_validations(json_schema, schema, self.ValidationsMapping.array)
    return json_schema

dict_schema ¶

dict_schema(schema)

Generates a JSON schema that matches a dict schema.

Parameters:

Name	Type	Description	Default
`schema`	`core_schema.DictSchema`	The core schema.	required

Returns:

Type	Description
`JsonSchemaValue`	The generated JSON schema.

Source code in pydantic/json_schema.py

def dict_schema(self, schema: core_schema.DictSchema) -> JsonSchemaValue:
    """Generates a JSON schema that matches a dict schema.

    Args:
        schema: The core schema.

    Returns:
        The generated JSON schema.
    """
    json_schema: JsonSchemaValue = {'type': 'object'}

    keys_schema = self.generate_inner(schema['keys_schema']).copy() if 'keys_schema' in schema else {}
    keys_pattern = keys_schema.pop('pattern', None)

    values_schema = self.generate_inner(schema['values_schema']).copy() if 'values_schema' in schema else {}
    values_schema.pop('title', None)  # don't give a title to the additionalProperties
    if values_schema or keys_pattern is not None:  # don't add additionalProperties if it's empty
        if keys_pattern is None:
            json_schema['additionalProperties'] = values_schema
        else:
            json_schema['patternProperties'] = {keys_pattern: values_schema}

    self.update_with_validations(json_schema, schema, self.ValidationsMapping.object)
    return json_schema

function_before_schema ¶

function_before_schema(schema)

Generates a JSON schema that matches a function-before schema.

Parameters:

Name	Type	Description	Default
`schema`	`core_schema.BeforeValidatorFunctionSchema`	The core schema.	required

Returns:

Type	Description
`JsonSchemaValue`	The generated JSON schema.

Source code in pydantic/json_schema.py

def function_before_schema(self, schema: core_schema.BeforeValidatorFunctionSchema) -> JsonSchemaValue:
    """Generates a JSON schema that matches a function-before schema.

    Args:
        schema: The core schema.

    Returns:
        The generated JSON schema.
    """
    return self._function_schema(schema)

function_after_schema ¶

function_after_schema(schema)

Generates a JSON schema that matches a function-after schema.

Parameters:

Name	Type	Description	Default
`schema`	`core_schema.AfterValidatorFunctionSchema`	The core schema.	required

Returns:

Type	Description
`JsonSchemaValue`	The generated JSON schema.

Source code in pydantic/json_schema.py

def function_after_schema(self, schema: core_schema.AfterValidatorFunctionSchema) -> JsonSchemaValue:
    """Generates a JSON schema that matches a function-after schema.

    Args:
        schema: The core schema.

    Returns:
        The generated JSON schema.
    """
    return self._function_schema(schema)

function_plain_schema ¶

function_plain_schema(schema)

Generates a JSON schema that matches a function-plain schema.

Parameters:

Name	Type	Description	Default
`schema`	`core_schema.PlainValidatorFunctionSchema`	The core schema.	required

Returns:

Type	Description
`JsonSchemaValue`	The generated JSON schema.

Source code in pydantic/json_schema.py

def function_plain_schema(self, schema: core_schema.PlainValidatorFunctionSchema) -> JsonSchemaValue:
    """Generates a JSON schema that matches a function-plain schema.

    Args:
        schema: The core schema.

    Returns:
        The generated JSON schema.
    """
    return self._function_schema(schema)

function_wrap_schema ¶

function_wrap_schema(schema)

Generates a JSON schema that matches a function-wrap schema.

Parameters:

Name	Type	Description	Default
`schema`	`core_schema.WrapValidatorFunctionSchema`	The core schema.	required

Returns:

Type	Description
`JsonSchemaValue`	The generated JSON schema.

Source code in pydantic/json_schema.py

def function_wrap_schema(self, schema: core_schema.WrapValidatorFunctionSchema) -> JsonSchemaValue:
    """Generates a JSON schema that matches a function-wrap schema.

    Args:
        schema: The core schema.

    Returns:
        The generated JSON schema.
    """
    return self._function_schema(schema)

default_schema ¶

default_schema(schema)

Generates a JSON schema that matches a schema with a default value.

Parameters:

Name	Type	Description	Default
`schema`	`core_schema.WithDefaultSchema`	The core schema.	required

Returns:

Type	Description
`JsonSchemaValue`	The generated JSON schema.

Source code in pydantic/json_schema.py

def default_schema(self, schema: core_schema.WithDefaultSchema) -> JsonSchemaValue:
    """Generates a JSON schema that matches a schema with a default value.

    Args:
        schema: The core schema.

    Returns:
        The generated JSON schema.
    """
    json_schema = self.generate_inner(schema['schema'])

    if 'default' not in schema:
        return json_schema
    default = schema['default']
    # Note: if you want to include the value returned by the default_factory,
    # override this method and replace the code above with:
    # if 'default' in schema:
    #     default = schema['default']
    # elif 'default_factory' in schema:
    #     default = schema['default_factory']()
    # else:
    #     return json_schema

    try:
        encoded_default = self.encode_default(default)
    except pydantic_core.PydanticSerializationError:
        self.emit_warning(
            'non-serializable-default',
            f'Default value {default} is not JSON serializable; excluding default from JSON schema',
        )
        # Return the inner schema, as though there was no default
        return json_schema

    if '$ref' in json_schema:
        # Since reference schemas do not support child keys, we wrap the reference schema in a single-case allOf:
        return {'allOf': [json_schema], 'default': encoded_default}
    else:
        json_schema['default'] = encoded_default
        return json_schema

nullable_schema ¶

nullable_schema(schema)

Generates a JSON schema that matches a schema that allows null values.

Parameters:

Name	Type	Description	Default
`schema`	`core_schema.NullableSchema`	The core schema.	required

Returns:

Type	Description
`JsonSchemaValue`	The generated JSON schema.

Source code in pydantic/json_schema.py

def nullable_schema(self, schema: core_schema.NullableSchema) -> JsonSchemaValue:
    """Generates a JSON schema that matches a schema that allows null values.

    Args:
        schema: The core schema.

    Returns:
        The generated JSON schema.
    """
    null_schema = {'type': 'null'}
    inner_json_schema = self.generate_inner(schema['schema'])

    if inner_json_schema == null_schema:
        return null_schema
    else:
        # Thanks to the equality check against `null_schema` above, I think 'oneOf' would also be valid here;
        # I'll use 'anyOf' for now, but it could be changed it if it would work better with some external tooling
        return self.get_flattened_anyof([inner_json_schema, null_schema])

union_schema ¶

union_schema(schema)

Generates a JSON schema that matches a schema that allows values matching any of the given schemas.

Parameters:

Name	Type	Description	Default
`schema`	`core_schema.UnionSchema`	The core schema.	required

Returns:

Type	Description
`JsonSchemaValue`	The generated JSON schema.

Source code in pydantic/json_schema.py

def union_schema(self, schema: core_schema.UnionSchema) -> JsonSchemaValue:
    """Generates a JSON schema that matches a schema that allows values matching any of the given schemas.

    Args:
        schema: The core schema.

    Returns:
        The generated JSON schema.
    """
    generated: list[JsonSchemaValue] = []

    choices = schema['choices']
    for s in choices:
        try:
            generated.append(self.generate_inner(s))
        except PydanticOmit:
            continue
        except PydanticInvalidForJsonSchema as exc:
            self.emit_warning('skipped-choice', exc.message)
    if len(generated) == 1:
        return generated[0]
    return self.get_flattened_anyof(generated)

tagged_union_schema ¶

tagged_union_schema(schema)

Generates a JSON schema that matches a schema that allows values matching any of the given schemas, where the schemas are tagged with a discriminator field that indicates which schema should be used to validate the value.

Parameters:

Name	Type	Description	Default
`schema`	`core_schema.TaggedUnionSchema`	The core schema.	required

Returns:

Type	Description
`JsonSchemaValue`	The generated JSON schema.

Source code in pydantic/json_schema.py

def tagged_union_schema(self, schema: core_schema.TaggedUnionSchema) -> JsonSchemaValue:
    """Generates a JSON schema that matches a schema that allows values matching any of the given schemas, where
    the schemas are tagged with a discriminator field that indicates which schema should be used to validate
    the value.

    Args:
        schema: The core schema.

    Returns:
        The generated JSON schema.
    """
    generated: dict[str, JsonSchemaValue] = {}
    for k, v in schema['choices'].items():
        if isinstance(k, Enum):
            k = k.value
        if not isinstance(v, (str, int)):
            try:
                # Use str(k) since keys must be strings for json; while not technically correct,
                # it's the closest that can be represented in valid JSON
                generated[str(k)] = self.generate_inner(v).copy()
            except PydanticOmit:
                continue
            except PydanticInvalidForJsonSchema as exc:
                self.emit_warning('skipped-choice', exc.message)

    # Populate the schema with any "indirect" references
    for k, v in schema['choices'].items():
        if isinstance(v, (str, int)):
            while isinstance(schema['choices'][v], (str, int)):
                v = schema['choices'][v]
                assert isinstance(v, (int, str))
            if str(v) in generated:
                # while it might seem unnecessary to check `if str(v) in generated`, a PydanticInvalidForJsonSchema
                # may have been raised above, which would mean that the schema we want to reference won't be present
                generated[str(k)] = generated[str(v)]

    one_of_choices = _deduplicate_schemas(generated.values())
    json_schema: JsonSchemaValue = {'oneOf': one_of_choices}

    # This reflects the v1 behavior; TODO: we should make it possible to exclude OpenAPI stuff from the JSON schema
    openapi_discriminator = self._extract_discriminator(schema, one_of_choices)
    if openapi_discriminator is not None:
        json_schema['discriminator'] = {
            'propertyName': openapi_discriminator,
            'mapping': {k: v.get('$ref', v) for k, v in generated.items()},
        }

    return json_schema

chain_schema ¶

chain_schema(schema)

Generates a JSON schema that matches a core_schema.ChainSchema.

When generating a schema for validation, we return the validation JSON schema for the first step in the chain. For serialization, we return the serialization JSON schema for the last step in the chain.

Parameters:

Name	Type	Description	Default
`schema`	`core_schema.ChainSchema`	The core schema.	required

Returns:

Type	Description
`JsonSchemaValue`	The generated JSON schema.

Source code in pydantic/json_schema.py

def chain_schema(self, schema: core_schema.ChainSchema) -> JsonSchemaValue:
    """Generates a JSON schema that matches a core_schema.ChainSchema.

    When generating a schema for validation, we return the validation JSON schema for the first step in the chain.
    For serialization, we return the serialization JSON schema for the last step in the chain.

    Args:
        schema: The core schema.

    Returns:
        The generated JSON schema.
    """
    step_index = 0 if self.mode == 'validation' else -1  # use first step for validation, last for serialization
    return self.generate_inner(schema['steps'][step_index])

lax_or_strict_schema ¶

lax_or_strict_schema(schema)

Generates a JSON schema that matches a schema that allows values matching either the lax schema or the strict schema.

Parameters:

Name	Type	Description	Default
`schema`	`core_schema.LaxOrStrictSchema`	The core schema.	required

Returns:

Type	Description
`JsonSchemaValue`	The generated JSON schema.

Source code in pydantic/json_schema.py

def lax_or_strict_schema(self, schema: core_schema.LaxOrStrictSchema) -> JsonSchemaValue:
    """Generates a JSON schema that matches a schema that allows values matching either the lax schema or the
    strict schema.

    Args:
        schema: The core schema.

    Returns:
        The generated JSON schema.
    """
    # TODO: Need to read the default value off of model config or whatever
    use_strict = schema.get('strict', False)  # TODO: replace this default False
    # If your JSON schema fails to generate it is probably
    # because one of the following two branches failed.
    if use_strict:
        return self.generate_inner(schema['strict_schema'])
    else:
        return self.generate_inner(schema['lax_schema'])

json_or_python_schema ¶

json_or_python_schema(schema)

Generates a JSON schema that matches a schema that allows values matching either the JSON schema or the Python schema.

The JSON schema is used instead of the Python schema. If you want to use the Python schema, you should override this method.

Parameters:

Name	Type	Description	Default
`schema`	`core_schema.JsonOrPythonSchema`	The core schema.	required

Returns:

Type	Description
`JsonSchemaValue`	The generated JSON schema.

Source code in pydantic/json_schema.py

def json_or_python_schema(self, schema: core_schema.JsonOrPythonSchema) -> JsonSchemaValue:
    """Generates a JSON schema that matches a schema that allows values matching either the JSON schema or the
    Python schema.

    The JSON schema is used instead of the Python schema. If you want to use the Python schema, you should override
    this method.

    Args:
        schema: The core schema.

    Returns:
        The generated JSON schema.
    """
    return self.generate_inner(schema['json_schema'])

typed_dict_schema ¶

typed_dict_schema(schema)

Generates a JSON schema that matches a schema that defines a typed dict.

Parameters:

Name	Type	Description	Default
`schema`	`core_schema.TypedDictSchema`	The core schema.	required

Returns:

Type	Description
`JsonSchemaValue`	The generated JSON schema.

Source code in pydantic/json_schema.py

def typed_dict_schema(self, schema: core_schema.TypedDictSchema) -> JsonSchemaValue:
    """Generates a JSON schema that matches a schema that defines a typed dict.

    Args:
        schema: The core schema.

    Returns:
        The generated JSON schema.
    """
    total = schema.get('total', True)
    named_required_fields: list[tuple[str, bool, CoreSchemaField]] = [
        (name, self.field_is_required(field, total), field)
        for name, field in schema['fields'].items()
        if self.field_is_present(field)
    ]
    if self.mode == 'serialization':
        named_required_fields.extend(self._name_required_computed_fields(schema.get('computed_fields', [])))
    json_schema = self._named_required_fields_schema(named_required_fields)
    config: CoreConfig | None = schema.get('config', None)

    extra = (config or {}).get('extra_fields_behavior', 'ignore')
    if extra == 'forbid':
        json_schema['additionalProperties'] = False
    elif extra == 'allow':
        json_schema['additionalProperties'] = True

    return json_schema

typed_dict_field_schema ¶

typed_dict_field_schema(schema)

Generates a JSON schema that matches a schema that defines a typed dict field.

Parameters:

Name	Type	Description	Default
`schema`	`core_schema.TypedDictField`	The core schema.	required

Returns:

Type	Description
`JsonSchemaValue`	The generated JSON schema.

Source code in pydantic/json_schema.py

def typed_dict_field_schema(self, schema: core_schema.TypedDictField) -> JsonSchemaValue:
    """Generates a JSON schema that matches a schema that defines a typed dict field.

    Args:
        schema: The core schema.

    Returns:
        The generated JSON schema.
    """
    return self.generate_inner(schema['schema'])

dataclass_field_schema ¶

dataclass_field_schema(schema)

Generates a JSON schema that matches a schema that defines a dataclass field.

Parameters:

Name	Type	Description	Default
`schema`	`core_schema.DataclassField`	The core schema.	required

Returns:

Type	Description
`JsonSchemaValue`	The generated JSON schema.

Source code in pydantic/json_schema.py

def dataclass_field_schema(self, schema: core_schema.DataclassField) -> JsonSchemaValue:
    """Generates a JSON schema that matches a schema that defines a dataclass field.

    Args:
        schema: The core schema.

    Returns:
        The generated JSON schema.
    """
    return self.generate_inner(schema['schema'])

model_field_schema ¶

model_field_schema(schema)

Generates a JSON schema that matches a schema that defines a model field.

Parameters:

Name	Type	Description	Default
`schema`	`core_schema.ModelField`	The core schema.	required

Returns:

Type	Description
`JsonSchemaValue`	The generated JSON schema.

Source code in pydantic/json_schema.py

def model_field_schema(self, schema: core_schema.ModelField) -> JsonSchemaValue:
    """Generates a JSON schema that matches a schema that defines a model field.

    Args:
        schema: The core schema.

    Returns:
        The generated JSON schema.
    """
    return self.generate_inner(schema['schema'])

computed_field_schema ¶

computed_field_schema(schema)

Generates a JSON schema that matches a schema that defines a computed field.

Parameters:

Name	Type	Description	Default
`schema`	`core_schema.ComputedField`	The core schema.	required

Returns:

Type	Description
`JsonSchemaValue`	The generated JSON schema.

Source code in pydantic/json_schema.py

def computed_field_schema(self, schema: core_schema.ComputedField) -> JsonSchemaValue:
    """Generates a JSON schema that matches a schema that defines a computed field.

    Args:
        schema: The core schema.

    Returns:
        The generated JSON schema.
    """
    return self.generate_inner(schema['return_schema'])

model_schema ¶

model_schema(schema)

Generates a JSON schema that matches a schema that defines a model.

Parameters:

Name	Type	Description	Default
`schema`	`core_schema.ModelSchema`	The core schema.	required

Returns:

Type	Description
`JsonSchemaValue`	The generated JSON schema.

Source code in pydantic/json_schema.py

def model_schema(self, schema: core_schema.ModelSchema) -> JsonSchemaValue:
    """Generates a JSON schema that matches a schema that defines a model.

    Args:
        schema: The core schema.

    Returns:
        The generated JSON schema.
    """
    # We do not use schema['model'].model_json_schema() here
    # because it could lead to inconsistent refs handling, etc.
    json_schema = self.generate_inner(schema['schema'])

    cls = cast('type[BaseModel]', schema['cls'])
    config = cls.model_config
    title = config.get('title')

    json_schema_extra = config.get('json_schema_extra')
    if cls.__pydantic_root_model__:
        root_json_schema_extra = cls.model_fields['root'].json_schema_extra
        if json_schema_extra and root_json_schema_extra:
            raise ValueError(
                '"model_config[\'json_schema_extra\']" and "Field.json_schema_extra" on "RootModel.root"'
                ' field must not be set simultaneously'
            )
        if root_json_schema_extra:
            json_schema_extra = root_json_schema_extra

    json_schema = self._update_class_schema(json_schema, title, config.get('extra', None), cls, json_schema_extra)

    return json_schema

resolve_schema_to_update ¶

resolve_schema_to_update(json_schema)

Resolve a JsonSchemaValue to the non-ref schema if it is a $ref schema.

Parameters:

Name	Type	Description	Default
`json_schema`	`JsonSchemaValue`	The schema to resolve.	required

Returns:

Type	Description
`JsonSchemaValue`	The resolved schema.

Source code in pydantic/json_schema.py

def resolve_schema_to_update(self, json_schema: JsonSchemaValue) -> JsonSchemaValue:
    """Resolve a JsonSchemaValue to the non-ref schema if it is a $ref schema.

    Args:
        json_schema: The schema to resolve.

    Returns:
        The resolved schema.
    """
    if '$ref' in json_schema:
        schema_to_update = self.get_schema_from_definitions(JsonRef(json_schema['$ref']))
        if schema_to_update is None:
            raise RuntimeError(f'Cannot update undefined schema for $ref={json_schema["$ref"]}')
        return self.resolve_schema_to_update(schema_to_update)
    else:
        schema_to_update = json_schema
    return schema_to_update

model_fields_schema ¶

model_fields_schema(schema)

Generates a JSON schema that matches a schema that defines a model's fields.

Parameters:

Name	Type	Description	Default
`schema`	`core_schema.ModelFieldsSchema`	The core schema.	required

Returns:

Type	Description
`JsonSchemaValue`	The generated JSON schema.

Source code in pydantic/json_schema.py

def model_fields_schema(self, schema: core_schema.ModelFieldsSchema) -> JsonSchemaValue:
    """Generates a JSON schema that matches a schema that defines a model's fields.

    Args:
        schema: The core schema.

    Returns:
        The generated JSON schema.
    """
    named_required_fields: list[tuple[str, bool, CoreSchemaField]] = [
        (name, self.field_is_required(field, total=True), field)
        for name, field in schema['fields'].items()
        if self.field_is_present(field)
    ]
    if self.mode == 'serialization':
        named_required_fields.extend(self._name_required_computed_fields(schema.get('computed_fields', [])))
    json_schema = self._named_required_fields_schema(named_required_fields)
    extra_validator = schema.get('extra_validator', None)
    if extra_validator is not None:
        schema_to_update = self.resolve_schema_to_update(json_schema)
        schema_to_update['additionalProperties'] = self.generate_inner(extra_validator)
    return json_schema

field_is_present ¶

field_is_present(field)

Whether the field should be included in the generated JSON schema.

Parameters:

Name	Type	Description	Default
`field`	`CoreSchemaField`	The schema for the field itself.	required

Returns:

Type	Description
`bool`	`True` if the field should be included in the generated JSON schema, `False` otherwise.

Source code in pydantic/json_schema.py

def field_is_present(self, field: CoreSchemaField) -> bool:
    """Whether the field should be included in the generated JSON schema.

    Args:
        field: The schema for the field itself.

    Returns:
        `True` if the field should be included in the generated JSON schema, `False` otherwise.
    """
    if self.mode == 'serialization':
        # If you still want to include the field in the generated JSON schema,
        # override this method and return True
        return not field.get('serialization_exclude')
    elif self.mode == 'validation':
        return True
    else:
        assert_never(self.mode)

field_is_required ¶

field_is_required(field, total)

Whether the field should be marked as required in the generated JSON schema. (Note that this is irrelevant if the field is not present in the JSON schema.).

Parameters:

Name	Type	Description	Default
`field`	`core_schema.ModelField \| core_schema.DataclassField \| core_schema.TypedDictField`	The schema for the field itself.	required
`total`	`bool`	Only applies to `TypedDictField`s. Indicates if the `TypedDict` this field belongs to is total, in which case any fields that don't explicitly specify `required=False` are required.	required

Returns:

Type	Description
`bool`	`True` if the field should be marked as required in the generated JSON schema, `False` otherwise.

Source code in pydantic/json_schema.py

def field_is_required(
    self,
    field: core_schema.ModelField | core_schema.DataclassField | core_schema.TypedDictField,
    total: bool,
) -> bool:
    """Whether the field should be marked as required in the generated JSON schema.
    (Note that this is irrelevant if the field is not present in the JSON schema.).

    Args:
        field: The schema for the field itself.
        total: Only applies to `TypedDictField`s.
            Indicates if the `TypedDict` this field belongs to is total, in which case any fields that don't
            explicitly specify `required=False` are required.

    Returns:
        `True` if the field should be marked as required in the generated JSON schema, `False` otherwise.
    """
    if self.mode == 'serialization':
        return not field.get('serialization_exclude')
    elif self.mode == 'validation':
        if field['type'] == 'typed-dict-field':
            return field.get('required', total)
        else:
            return field['schema']['type'] != 'default'
    else:
        assert_never(self.mode)

dataclass_args_schema ¶

dataclass_args_schema(schema)

Generates a JSON schema that matches a schema that defines a dataclass's constructor arguments.

Parameters:

Name	Type	Description	Default
`schema`	`core_schema.DataclassArgsSchema`	The core schema.	required

Returns:

Type	Description
`JsonSchemaValue`	The generated JSON schema.

Source code in pydantic/json_schema.py

def dataclass_args_schema(self, schema: core_schema.DataclassArgsSchema) -> JsonSchemaValue:
    """Generates a JSON schema that matches a schema that defines a dataclass's constructor arguments.

    Args:
        schema: The core schema.

    Returns:
        The generated JSON schema.
    """
    named_required_fields: list[tuple[str, bool, CoreSchemaField]] = [
        (field['name'], self.field_is_required(field, total=True), field)
        for field in schema['fields']
        if self.field_is_present(field)
    ]
    if self.mode == 'serialization':
        named_required_fields.extend(self._name_required_computed_fields(schema.get('computed_fields', [])))
    return self._named_required_fields_schema(named_required_fields)

dataclass_schema ¶

dataclass_schema(schema)

Generates a JSON schema that matches a schema that defines a dataclass.

Parameters:

Name	Type	Description	Default
`schema`	`core_schema.DataclassSchema`	The core schema.	required

Returns:

Type	Description
`JsonSchemaValue`	The generated JSON schema.

Source code in pydantic/json_schema.py

def dataclass_schema(self, schema: core_schema.DataclassSchema) -> JsonSchemaValue:
    """Generates a JSON schema that matches a schema that defines a dataclass.

    Args:
        schema: The core schema.

    Returns:
        The generated JSON schema.
    """
    json_schema = self.generate_inner(schema['schema']).copy()

    cls = schema['cls']
    config: ConfigDict = getattr(cls, '__pydantic_config__', cast('ConfigDict', {}))

    title = config.get('title') or cls.__name__

    json_schema_extra = config.get('json_schema_extra')
    json_schema = self._update_class_schema(json_schema, title, config.get('extra', None), cls, json_schema_extra)

    # Dataclass-specific handling of description
    if is_dataclass(cls) and not hasattr(cls, '__pydantic_validator__'):
        # vanilla dataclass; don't use cls.__doc__ as it will contain the class signature by default
        description = None
    else:
        description = None if cls.__doc__ is None else inspect.cleandoc(cls.__doc__)
    if description:
        json_schema['description'] = description

    return json_schema

arguments_schema ¶

arguments_schema(schema)

Generates a JSON schema that matches a schema that defines a function's arguments.

Parameters:

Name	Type	Description	Default
`schema`	`core_schema.ArgumentsSchema`	The core schema.	required

Returns:

Type	Description
`JsonSchemaValue`	The generated JSON schema.

Source code in pydantic/json_schema.py

def arguments_schema(self, schema: core_schema.ArgumentsSchema) -> JsonSchemaValue:
    """Generates a JSON schema that matches a schema that defines a function's arguments.

    Args:
        schema: The core schema.

    Returns:
        The generated JSON schema.
    """
    metadata = _core_metadata.CoreMetadataHandler(schema).metadata
    prefer_positional = metadata.get('pydantic_js_prefer_positional_arguments')

    arguments = schema['arguments_schema']
    kw_only_arguments = [a for a in arguments if a.get('mode') == 'keyword_only']
    kw_or_p_arguments = [a for a in arguments if a.get('mode') in {'positional_or_keyword', None}]
    p_only_arguments = [a for a in arguments if a.get('mode') == 'positional_only']
    var_args_schema = schema.get('var_args_schema')
    var_kwargs_schema = schema.get('var_kwargs_schema')

    if prefer_positional:
        positional_possible = not kw_only_arguments and not var_kwargs_schema
        if positional_possible:
            return self.p_arguments_schema(p_only_arguments + kw_or_p_arguments, var_args_schema)

    keyword_possible = not p_only_arguments and not var_args_schema
    if keyword_possible:
        return self.kw_arguments_schema(kw_or_p_arguments + kw_only_arguments, var_kwargs_schema)

    if not prefer_positional:
        positional_possible = not kw_only_arguments and not var_kwargs_schema
        if positional_possible:
            return self.p_arguments_schema(p_only_arguments + kw_or_p_arguments, var_args_schema)

    # TODO: When support for Python 3.7 is dropped, uncomment the block on `test_json_schema`
    # to cover this test case.
    raise PydanticInvalidForJsonSchema(  # pragma: no cover
        'Unable to generate JSON schema for arguments validator with positional-only and keyword-only arguments'
    )

kw_arguments_schema ¶

kw_arguments_schema(arguments, var_kwargs_schema)

Generates a JSON schema that matches a schema that defines a function's keyword arguments.

Parameters:

Name	Type	Description	Default
`arguments`	`list[core_schema.ArgumentsParameter]`	The core schema.	required

Returns:

Type	Description
`JsonSchemaValue`	The generated JSON schema.

Source code in pydantic/json_schema.py

def kw_arguments_schema(
    self, arguments: list[core_schema.ArgumentsParameter], var_kwargs_schema: CoreSchema | None
) -> JsonSchemaValue:
    """Generates a JSON schema that matches a schema that defines a function's keyword arguments.

    Args:
        arguments: The core schema.

    Returns:
        The generated JSON schema.
    """
    properties: dict[str, JsonSchemaValue] = {}
    required: list[str] = []
    for argument in arguments:
        name = self.get_argument_name(argument)
        argument_schema = self.generate_inner(argument['schema']).copy()
        argument_schema['title'] = self.get_title_from_name(name)
        properties[name] = argument_schema

        if argument['schema']['type'] != 'default':
            # This assumes that if the argument has a default value,
            # the inner schema must be of type WithDefaultSchema.
            # I believe this is true, but I am not 100% sure
            required.append(name)

    json_schema: JsonSchemaValue = {'type': 'object', 'properties': properties}
    if required:
        json_schema['required'] = required

    if var_kwargs_schema:
        additional_properties_schema = self.generate_inner(var_kwargs_schema)
        if additional_properties_schema:
            json_schema['additionalProperties'] = additional_properties_schema
    else:
        json_schema['additionalProperties'] = False
    return json_schema

p_arguments_schema ¶

p_arguments_schema(arguments, var_args_schema)

Generates a JSON schema that matches a schema that defines a function's positional arguments.

Parameters:

Name	Type	Description	Default
`arguments`	`list[core_schema.ArgumentsParameter]`	The core schema.	required

Returns:

Type	Description
`JsonSchemaValue`	The generated JSON schema.

Source code in pydantic/json_schema.py

def p_arguments_schema(
    self, arguments: list[core_schema.ArgumentsParameter], var_args_schema: CoreSchema | None
) -> JsonSchemaValue:
    """Generates a JSON schema that matches a schema that defines a function's positional arguments.

    Args:
        arguments: The core schema.

    Returns:
        The generated JSON schema.
    """
    prefix_items: list[JsonSchemaValue] = []
    min_items = 0

    for argument in arguments:
        name = self.get_argument_name(argument)

        argument_schema = self.generate_inner(argument['schema']).copy()
        argument_schema['title'] = self.get_title_from_name(name)
        prefix_items.append(argument_schema)

        if argument['schema']['type'] != 'default':
            # This assumes that if the argument has a default value,
            # the inner schema must be of type WithDefaultSchema.
            # I believe this is true, but I am not 100% sure
            min_items += 1

    json_schema: JsonSchemaValue = {'type': 'array', 'prefixItems': prefix_items}
    if min_items:
        json_schema['minItems'] = min_items

    if var_args_schema:
        items_schema = self.generate_inner(var_args_schema)
        if items_schema:
            json_schema['items'] = items_schema
    else:
        json_schema['maxItems'] = len(prefix_items)

    return json_schema

get_argument_name ¶

get_argument_name(argument)

Retrieves the name of an argument.

Parameters:

Name	Type	Description	Default
`argument`	`core_schema.ArgumentsParameter`	The core schema.	required

Returns:

Type	Description
`str`	The name of the argument.

Source code in pydantic/json_schema.py

def get_argument_name(self, argument: core_schema.ArgumentsParameter) -> str:
    """Retrieves the name of an argument.

    Args:
        argument: The core schema.

    Returns:
        The name of the argument.
    """
    name = argument['name']
    if self.by_alias:
        alias = argument.get('alias')
        if isinstance(alias, str):
            name = alias
        else:
            pass  # might want to do something else?
    return name

call_schema ¶

call_schema(schema)

Generates a JSON schema that matches a schema that defines a function call.

Parameters:

Name	Type	Description	Default
`schema`	`core_schema.CallSchema`	The core schema.	required

Returns:

Type	Description
`JsonSchemaValue`	The generated JSON schema.

Source code in pydantic/json_schema.py

def call_schema(self, schema: core_schema.CallSchema) -> JsonSchemaValue:
    """Generates a JSON schema that matches a schema that defines a function call.

    Args:
        schema: The core schema.

    Returns:
        The generated JSON schema.
    """
    return self.generate_inner(schema['arguments_schema'])

custom_error_schema ¶

custom_error_schema(schema)

Generates a JSON schema that matches a schema that defines a custom error.

Parameters:

Name	Type	Description	Default
`schema`	`core_schema.CustomErrorSchema`	The core schema.	required

Returns:

Type	Description
`JsonSchemaValue`	The generated JSON schema.

Source code in pydantic/json_schema.py

def custom_error_schema(self, schema: core_schema.CustomErrorSchema) -> JsonSchemaValue:
    """Generates a JSON schema that matches a schema that defines a custom error.

    Args:
        schema: The core schema.

    Returns:
        The generated JSON schema.
    """
    return self.generate_inner(schema['schema'])

json_schema ¶

json_schema(schema)

Generates a JSON schema that matches a schema that defines a JSON object.

Parameters:

Name	Type	Description	Default
`schema`	`core_schema.JsonSchema`	The core schema.	required

Returns:

Type	Description
`JsonSchemaValue`	The generated JSON schema.

Source code in pydantic/json_schema.py

def json_schema(self, schema: core_schema.JsonSchema) -> JsonSchemaValue:
    """Generates a JSON schema that matches a schema that defines a JSON object.

    Args:
        schema: The core schema.

    Returns:
        The generated JSON schema.
    """
    content_core_schema = schema.get('schema') or core_schema.any_schema()
    content_json_schema = self.generate_inner(content_core_schema)
    if self.mode == 'validation':
        return {'type': 'string', 'contentMediaType': 'application/json', 'contentSchema': content_json_schema}
    else:
        # self.mode == 'serialization'
        return content_json_schema

url_schema ¶

url_schema(schema)

Generates a JSON schema that matches a schema that defines a URL.

Parameters:

Name	Type	Description	Default
`schema`	`core_schema.UrlSchema`	The core schema.	required

Returns:

Type	Description
`JsonSchemaValue`	The generated JSON schema.

Source code in pydantic/json_schema.py

def url_schema(self, schema: core_schema.UrlSchema) -> JsonSchemaValue:
    """Generates a JSON schema that matches a schema that defines a URL.

    Args:
        schema: The core schema.

    Returns:
        The generated JSON schema.
    """
    json_schema = {'type': 'string', 'format': 'uri', 'minLength': 1}
    self.update_with_validations(json_schema, schema, self.ValidationsMapping.string)
    return json_schema

multi_host_url_schema ¶

multi_host_url_schema(schema)

Generates a JSON schema that matches a schema that defines a URL that can be used with multiple hosts.

Parameters:

Name	Type	Description	Default
`schema`	`core_schema.MultiHostUrlSchema`	The core schema.	required

Returns:

Type	Description
`JsonSchemaValue`	The generated JSON schema.

Source code in pydantic/json_schema.py

def multi_host_url_schema(self, schema: core_schema.MultiHostUrlSchema) -> JsonSchemaValue:
    """Generates a JSON schema that matches a schema that defines a URL that can be used with multiple hosts.

    Args:
        schema: The core schema.

    Returns:
        The generated JSON schema.
    """
    # Note: 'multi-host-uri' is a custom/pydantic-specific format, not part of the JSON Schema spec
    json_schema = {'type': 'string', 'format': 'multi-host-uri', 'minLength': 1}
    self.update_with_validations(json_schema, schema, self.ValidationsMapping.string)
    return json_schema

uuid_schema ¶

uuid_schema(schema)

Generates a JSON schema that matches a UUID.

Parameters:

Name	Type	Description	Default
`schema`	`core_schema.UuidSchema`	The core schema.	required

Returns:

Type	Description
`JsonSchemaValue`	The generated JSON schema.

Source code in pydantic/json_schema.py

def uuid_schema(self, schema: core_schema.UuidSchema) -> JsonSchemaValue:
    """Generates a JSON schema that matches a UUID.

    Args:
        schema: The core schema.

    Returns:
        The generated JSON schema.
    """
    return {'type': 'string', 'format': 'uuid'}

definitions_schema ¶

definitions_schema(schema)

Generates a JSON schema that matches a schema that defines a JSON object with definitions.

Parameters:

Name	Type	Description	Default
`schema`	`core_schema.DefinitionsSchema`	The core schema.	required

Returns:

Type	Description
`JsonSchemaValue`	The generated JSON schema.

Source code in pydantic/json_schema.py

def definitions_schema(self, schema: core_schema.DefinitionsSchema) -> JsonSchemaValue:
    """Generates a JSON schema that matches a schema that defines a JSON object with definitions.

    Args:
        schema: The core schema.

    Returns:
        The generated JSON schema.
    """
    for definition in schema['definitions']:
        try:
            self.generate_inner(definition)
        except PydanticInvalidForJsonSchema as e:
            core_ref: CoreRef = CoreRef(definition['ref'])  # type: ignore
            self._core_defs_invalid_for_json_schema[self.get_defs_ref((core_ref, self.mode))] = e
            continue
    return self.generate_inner(schema['schema'])

definition_ref_schema ¶

definition_ref_schema(schema)

Generates a JSON schema that matches a schema that references a definition.

Parameters:

Name	Type	Description	Default
`schema`	`core_schema.DefinitionReferenceSchema`	The core schema.	required

Returns:

Type	Description
`JsonSchemaValue`	The generated JSON schema.

Source code in pydantic/json_schema.py

def definition_ref_schema(self, schema: core_schema.DefinitionReferenceSchema) -> JsonSchemaValue:
    """Generates a JSON schema that matches a schema that references a definition.

    Args:
        schema: The core schema.

    Returns:
        The generated JSON schema.
    """
    core_ref = CoreRef(schema['schema_ref'])
    _, ref_json_schema = self.get_cache_defs_ref_schema(core_ref)
    return ref_json_schema

ser_schema ¶

ser_schema(schema)

Generates a JSON schema that matches a schema that defines a serialized object.

Parameters:

Name	Type	Description	Default
`schema`	`core_schema.SerSchema \| core_schema.IncExSeqSerSchema \| core_schema.IncExDictSerSchema`	The core schema.	required

Returns:

Type	Description
`JsonSchemaValue \| None`	The generated JSON schema.

Source code in pydantic/json_schema.py

def ser_schema(
    self, schema: core_schema.SerSchema | core_schema.IncExSeqSerSchema | core_schema.IncExDictSerSchema
) -> JsonSchemaValue | None:
    """Generates a JSON schema that matches a schema that defines a serialized object.

    Args:
        schema: The core schema.

    Returns:
        The generated JSON schema.
    """
    schema_type = schema['type']
    if schema_type == 'function-plain' or schema_type == 'function-wrap':
        # PlainSerializerFunctionSerSchema or WrapSerializerFunctionSerSchema
        return_schema = schema.get('return_schema')
        if return_schema is not None:
            return self.generate_inner(return_schema)
    elif schema_type == 'format' or schema_type == 'to-string':
        # FormatSerSchema or ToStringSerSchema
        return self.str_schema(core_schema.str_schema())
    elif schema['type'] == 'model':
        # ModelSerSchema
        return self.generate_inner(schema['schema'])
    return None

get_title_from_name ¶

get_title_from_name(name)

Retrieves a title from a name.

Parameters:

Name	Type	Description	Default
`name`	`str`	The name to retrieve a title from.	required

Returns:

Type	Description
`str`	The title.

Source code in pydantic/json_schema.py

def get_title_from_name(self, name: str) -> str:
    """Retrieves a title from a name.

    Args:
        name: The name to retrieve a title from.

    Returns:
        The title.
    """
    return name.title().replace('_', ' ')

field_title_should_be_set ¶

field_title_should_be_set(schema)

Returns true if a field with the given schema should have a title set based on the field name.

Intuitively, we want this to return true for schemas that wouldn't otherwise provide their own title (e.g., int, float, str), and false for those that would (e.g., BaseModel subclasses).

Parameters:

Name	Type	Description	Default
`schema`	`CoreSchemaOrField`	The schema to check.	required

Returns:

Type	Description
`bool`	`True` if the field should have a title set, `False` otherwise.

Source code in pydantic/json_schema.py

def field_title_should_be_set(self, schema: CoreSchemaOrField) -> bool:
    """Returns true if a field with the given schema should have a title set based on the field name.

    Intuitively, we want this to return true for schemas that wouldn't otherwise provide their own title
    (e.g., int, float, str), and false for those that would (e.g., BaseModel subclasses).

    Args:
        schema: The schema to check.

    Returns:
        `True` if the field should have a title set, `False` otherwise.
    """
    if _core_utils.is_core_schema_field(schema):
        if schema['type'] == 'computed-field':
            field_schema = schema['return_schema']
        else:
            field_schema = schema['schema']
        return self.field_title_should_be_set(field_schema)

    elif _core_utils.is_core_schema(schema):
        if schema.get('ref'):  # things with refs, such as models and enums, should not have titles set
            return False
        if schema['type'] in {'default', 'nullable', 'definitions'}:
            return self.field_title_should_be_set(schema['schema'])  # type: ignore[typeddict-item]
        if _core_utils.is_function_with_inner_schema(schema):
            return self.field_title_should_be_set(schema['schema'])
        if schema['type'] == 'definition-ref':
            # Referenced schemas should not have titles set for the same reason
            # schemas with refs should not
            return False
        return True  # anything else should have title set

    else:
        raise PydanticInvalidForJsonSchema(f'Unexpected schema type: schema={schema}')  # pragma: no cover

normalize_name ¶

normalize_name(name)

Normalizes a name to be used as a key in a dictionary.

Parameters:

Name	Type	Description	Default
`name`	`str`	The name to normalize.	required

Returns:

Type	Description
`str`	The normalized name.

Source code in pydantic/json_schema.py

def normalize_name(self, name: str) -> str:
    """Normalizes a name to be used as a key in a dictionary.

    Args:
        name: The name to normalize.

    Returns:
        The normalized name.
    """
    return re.sub(r'[^a-zA-Z0-9.\-_]', '_', name).replace('.', '__')

get_defs_ref ¶

get_defs_ref(core_mode_ref)

Override this method to change the way that definitions keys are generated from a core reference.

Parameters:

Name	Type	Description	Default
`core_mode_ref`	`CoreModeRef`	The core reference.	required

Returns:

Type	Description
`DefsRef`	The definitions key.

Source code in pydantic/json_schema.py

def get_defs_ref(self, core_mode_ref: CoreModeRef) -> DefsRef:
    """Override this method to change the way that definitions keys are generated from a core reference.

    Args:
        core_mode_ref: The core reference.

    Returns:
        The definitions key.
    """
    # Split the core ref into "components"; generic origins and arguments are each separate components
    core_ref, mode = core_mode_ref
    components = re.split(r'([\][,])', core_ref)
    # Remove IDs from each component
    components = [x.split(':')[0] for x in components]
    core_ref_no_id = ''.join(components)
    # Remove everything before the last period from each "component"
    components = [re.sub(r'(?:[^.[\]]+\.)+((?:[^.[\]]+))', r'\1', x) for x in components]
    short_ref = ''.join(components)

    mode_title = _MODE_TITLE_MAPPING[mode]

    # It is important that the generated defs_ref values be such that at least one choice will not
    # be generated for any other core_ref. Currently, this should be the case because we include
    # the id of the source type in the core_ref
    name = DefsRef(self.normalize_name(short_ref))
    name_mode = DefsRef(self.normalize_name(short_ref + mode_title))
    module_qualname = DefsRef(self.normalize_name(core_ref_no_id))
    module_qualname_mode = DefsRef(module_qualname + mode_title)
    module_qualname_id = DefsRef(self.normalize_name(core_ref))
    occurrence_index = self._collision_index.get(module_qualname_id)
    if occurrence_index is None:
        self._collision_counter[module_qualname] += 1
        occurrence_index = self._collision_index[module_qualname_id] = self._collision_counter[module_qualname]

    module_qualname_occurrence = DefsRef(f'{module_qualname}__{occurrence_index}')
    module_qualname_occurrence_mode = DefsRef(f'{module_qualname}{mode_title}__{occurrence_index}')

    self._prioritized_defsref_choices[module_qualname_occurrence_mode] = [
        name,
        name_mode,
        module_qualname,
        module_qualname_mode,
        module_qualname_occurrence,
        module_qualname_occurrence_mode,
    ]

    return module_qualname_occurrence_mode

get_cache_defs_ref_schema ¶

get_cache_defs_ref_schema(core_ref)

This method wraps the get_defs_ref method with some cache-lookup/population logic, and returns both the produced defs_ref and the JSON schema that will refer to the right definition.

Parameters:

Name	Type	Description	Default
`core_ref`	`CoreRef`	The core reference to get the definitions reference for.	required

Returns:

Type	Description
`tuple[DefsRef, JsonSchemaValue]`	A tuple of the definitions reference and the JSON schema that will refer to it.

Source code in pydantic/json_schema.py

def get_cache_defs_ref_schema(self, core_ref: CoreRef) -> tuple[DefsRef, JsonSchemaValue]:
    """This method wraps the get_defs_ref method with some cache-lookup/population logic,
    and returns both the produced defs_ref and the JSON schema that will refer to the right definition.

    Args:
        core_ref: The core reference to get the definitions reference for.

    Returns:
        A tuple of the definitions reference and the JSON schema that will refer to it.
    """
    core_mode_ref = (core_ref, self.mode)
    maybe_defs_ref = self.core_to_defs_refs.get(core_mode_ref)
    if maybe_defs_ref is not None:
        json_ref = self.core_to_json_refs[core_mode_ref]
        return maybe_defs_ref, {'$ref': json_ref}

    defs_ref = self.get_defs_ref(core_mode_ref)

    # populate the ref translation mappings
    self.core_to_defs_refs[core_mode_ref] = defs_ref
    self.defs_to_core_refs[defs_ref] = core_mode_ref

    json_ref = JsonRef(self.ref_template.format(model=defs_ref))
    self.core_to_json_refs[core_mode_ref] = json_ref
    self.json_to_defs_refs[json_ref] = defs_ref
    ref_json_schema = {'$ref': json_ref}
    return defs_ref, ref_json_schema

handle_ref_overrides ¶

handle_ref_overrides(json_schema)

It is not valid for a schema with a top-level $ref to have sibling keys.

During our own schema generation, we treat sibling keys as overrides to the referenced schema, but this is not how the official JSON schema spec works.

Because of this, we first remove any sibling keys that are redundant with the referenced schema, then if any remain, we transform the schema from a top-level '$ref' to use allOf to move the $ref out of the top level. (See bottom of https://swagger.io/docs/specification/using-ref/ for a reference about this behavior)

Source code in pydantic/json_schema.py

def handle_ref_overrides(self, json_schema: JsonSchemaValue) -> JsonSchemaValue:
    """It is not valid for a schema with a top-level $ref to have sibling keys.

    During our own schema generation, we treat sibling keys as overrides to the referenced schema,
    but this is not how the official JSON schema spec works.

    Because of this, we first remove any sibling keys that are redundant with the referenced schema, then if
    any remain, we transform the schema from a top-level '$ref' to use allOf to move the $ref out of the top level.
    (See bottom of https://swagger.io/docs/specification/using-ref/ for a reference about this behavior)
    """
    if '$ref' in json_schema:
        # prevent modifications to the input; this copy may be safe to drop if there is significant overhead
        json_schema = json_schema.copy()

        referenced_json_schema = self.get_schema_from_definitions(JsonRef(json_schema['$ref']))
        if referenced_json_schema is None:
            # This can happen when building schemas for models with not-yet-defined references.
            # It may be a good idea to do a recursive pass at the end of the generation to remove
            # any redundant override keys.
            if len(json_schema) > 1:
                # Make it an allOf to at least resolve the sibling keys issue
                json_schema = json_schema.copy()
                json_schema.setdefault('allOf', [])
                json_schema['allOf'].append({'$ref': json_schema['$ref']})
                del json_schema['$ref']

            return json_schema
        for k, v in list(json_schema.items()):
            if k == '$ref':
                continue
            if k in referenced_json_schema and referenced_json_schema[k] == v:
                del json_schema[k]  # redundant key
        if len(json_schema) > 1:
            # There is a remaining "override" key, so we need to move $ref out of the top level
            json_ref = JsonRef(json_schema['$ref'])
            del json_schema['$ref']
            assert 'allOf' not in json_schema  # this should never happen, but just in case
            json_schema['allOf'] = [{'$ref': json_ref}]

    return json_schema

encode_default ¶

encode_default(dft)

Encode a default value to a JSON-serializable value.

This is used to encode default values for fields in the generated JSON schema.

Parameters:

Name	Type	Description	Default
`dft`	`Any`	The default value to encode.	required

Returns:

Type	Description
`Any`	The encoded default value.

Source code in pydantic/json_schema.py

def encode_default(self, dft: Any) -> Any:
    """Encode a default value to a JSON-serializable value.

    This is used to encode default values for fields in the generated JSON schema.

    Args:
        dft: The default value to encode.

    Returns:
        The encoded default value.
    """
    return pydantic_core.to_jsonable_python(dft)

update_with_validations ¶

update_with_validations(json_schema, core_schema, mapping)

Update the json_schema with the corresponding validations specified in the core_schema, using the provided mapping to translate keys in core_schema to the appropriate keys for a JSON schema.

Parameters:

Name	Type	Description	Default
`json_schema`	`JsonSchemaValue`	The JSON schema to update.	required
`core_schema`	`CoreSchema`	The core schema to get the validations from.	required
`mapping`	`dict[str, str]`	A mapping from core_schema attribute names to the corresponding JSON schema attribute names.	required

Source code in pydantic/json_schema.py

def update_with_validations(
    self, json_schema: JsonSchemaValue, core_schema: CoreSchema, mapping: dict[str, str]
) -> None:
    """Update the json_schema with the corresponding validations specified in the core_schema,
    using the provided mapping to translate keys in core_schema to the appropriate keys for a JSON schema.

    Args:
        json_schema: The JSON schema to update.
        core_schema: The core schema to get the validations from.
        mapping: A mapping from core_schema attribute names to the corresponding JSON schema attribute names.
    """
    for core_key, json_schema_key in mapping.items():
        if core_key in core_schema:
            json_schema[json_schema_key] = core_schema[core_key]  # type: ignore[literal-required]

get_json_ref_counts ¶

get_json_ref_counts(json_schema)

Get all values corresponding to the key '$ref' anywhere in the json_schema.

Source code in pydantic/json_schema.py

def get_json_ref_counts(self, json_schema: JsonSchemaValue) -> dict[JsonRef, int]:
    """Get all values corresponding to the key '$ref' anywhere in the json_schema."""
    json_refs: dict[JsonRef, int] = Counter()

    def _add_json_refs(schema: Any) -> None:
        if isinstance(schema, dict):
            if '$ref' in schema:
                json_ref = JsonRef(schema['$ref'])
                if not isinstance(json_ref, str):
                    return  # in this case, '$ref' might have been the name of a property
                already_visited = json_ref in json_refs
                json_refs[json_ref] += 1
                if already_visited:
                    return  # prevent recursion on a definition that was already visited
                defs_ref = self.json_to_defs_refs[json_ref]
                if defs_ref in self._core_defs_invalid_for_json_schema:
                    raise self._core_defs_invalid_for_json_schema[defs_ref]
                _add_json_refs(self.definitions[defs_ref])

            for v in schema.values():
                _add_json_refs(v)
        elif isinstance(schema, list):
            for v in schema:
                _add_json_refs(v)

    _add_json_refs(json_schema)
    return json_refs

emit_warning ¶

emit_warning(kind, detail)

This method simply emits PydanticJsonSchemaWarnings based on handling in the warning_message method.

Source code in pydantic/json_schema.py

def emit_warning(self, kind: JsonSchemaWarningKind, detail: str) -> None:
    """This method simply emits PydanticJsonSchemaWarnings based on handling in the `warning_message` method."""
    message = self.render_warning_message(kind, detail)
    if message is not None:
        warnings.warn(message, PydanticJsonSchemaWarning)

render_warning_message ¶

render_warning_message(kind, detail)

This method is responsible for ignoring warnings as desired, and for formatting the warning messages.

You can override the value of ignored_warning_kinds in a subclass of GenerateJsonSchema to modify what warnings are generated. If you want more control, you can override this method; just return None in situations where you don't want warnings to be emitted.

Parameters:

Name	Type	Description	Default
`kind`	`JsonSchemaWarningKind`	The kind of warning to render. It can be one of the following: 'skipped-choice': A choice field was skipped because it had no valid choices. 'non-serializable-default': A default value was skipped because it was not JSON-serializable.	required
`detail`	`str`	A string with additional details about the warning.	required

Returns:

Type	Description
`str \| None`	The formatted warning message, or `None` if no warning should be emitted.

Source code in pydantic/json_schema.py

def render_warning_message(self, kind: JsonSchemaWarningKind, detail: str) -> str | None:
    """This method is responsible for ignoring warnings as desired, and for formatting the warning messages.

    You can override the value of `ignored_warning_kinds` in a subclass of GenerateJsonSchema
    to modify what warnings are generated. If you want more control, you can override this method;
    just return None in situations where you don't want warnings to be emitted.

    Args:
        kind: The kind of warning to render. It can be one of the following:

            - 'skipped-choice': A choice field was skipped because it had no valid choices.
            - 'non-serializable-default': A default value was skipped because it was not JSON-serializable.
        detail: A string with additional details about the warning.

    Returns:
        The formatted warning message, or `None` if no warning should be emitted.
    """
    if kind in self.ignored_warning_kinds:
        return None
    return f'{detail} [{kind}]'

WithJsonSchema `dataclass` ¶

Add this as an annotation on a field to override the (base) JSON schema that would be generated for that field. This provides a way to set a JSON schema for types that would otherwise raise errors when producing a JSON schema, such as Callable, or types that have an is-instance core schema, without needing to go so far as creating a custom subclass of pydantic.json_schema.GenerateJsonSchema. Note that any modifications to the schema that would normally be made (such as setting the title for model fields) will still be performed.

If mode is set this will only apply to that schema generation mode, allowing you to set different json schemas for validation and serialization.

Examples `dataclass` ¶

Add examples to a JSON schema.

Examples should be a map of example names (strings) to example values (any valid JSON).

If mode is set this will only apply to that schema generation mode, allowing you to add different examples for validation and serialization.

SkipJsonSchema `dataclass` ¶

Add this as an annotation on a field to skip generating a JSON schema for that field.

Example

from pydantic import BaseModel
from pydantic.json_schema import SkipJsonSchema

class Model(BaseModel):
    a: int | SkipJsonSchema[None] = None


print(Model.model_json_schema())
#> {'properties': {'a': {'default': None, 'title': 'A', 'type': 'integer'}}, 'title': 'Model', 'type': 'object'}

update_json_schema ¶

update_json_schema(schema, updates)

Update a JSON schema by providing a dictionary of updates.

This function sets the provided key-value pairs in the schema and returns the updated schema.

Parameters:

Name	Type	Description	Default
`schema`	`JsonSchemaValue`	The JSON schema to update.	required
`updates`	`dict[str, Any]`	A dictionary of key-value pairs to set in the schema.	required

Returns:

Type	Description
`JsonSchemaValue`	The updated JSON schema.

Source code in pydantic/json_schema.py

def update_json_schema(schema: JsonSchemaValue, updates: dict[str, Any]) -> JsonSchemaValue:
    """Update a JSON schema by providing a dictionary of updates.

    This function sets the provided key-value pairs in the schema and returns the updated schema.

    Args:
        schema: The JSON schema to update.
        updates: A dictionary of key-value pairs to set in the schema.

    Returns:
        The updated JSON schema.
    """
    schema.update(updates)
    return schema

model_json_schema ¶

model_json_schema(
    cls,
    by_alias=True,
    ref_template=DEFAULT_REF_TEMPLATE,
    schema_generator=GenerateJsonSchema,
    mode="validation",
)

Utility function to generate a JSON Schema for a model.

Parameters:

Name	Type	Description	Default
`cls`	`type[BaseModel] \| type[PydanticDataclass]`	The model class to generate a JSON Schema for.	required
`by_alias`	`bool`	If `True` (the default), fields will be serialized according to their alias. If `False`, fields will be serialized according to their attribute name.	`True`
`ref_template`	`str`	The template to use for generating JSON Schema references.	`DEFAULT_REF_TEMPLATE`
`schema_generator`	`type[GenerateJsonSchema]`	The class to use for generating the JSON Schema.	`GenerateJsonSchema`
`mode`	`JsonSchemaMode`	The mode to use for generating the JSON Schema. It can be one of the following: 'validation': Generate a JSON Schema for validating data. 'serialization': Generate a JSON Schema for serializing data.	`'validation'`

Returns:

Type	Description
`dict[str, Any]`	The generated JSON Schema.

Source code in pydantic/json_schema.py

def model_json_schema(
    cls: type[BaseModel] | type[PydanticDataclass],
    by_alias: bool = True,
    ref_template: str = DEFAULT_REF_TEMPLATE,
    schema_generator: type[GenerateJsonSchema] = GenerateJsonSchema,
    mode: JsonSchemaMode = 'validation',
) -> dict[str, Any]:
    """Utility function to generate a JSON Schema for a model.

    Args:
        cls: The model class to generate a JSON Schema for.
        by_alias: If `True` (the default), fields will be serialized according to their alias.
            If `False`, fields will be serialized according to their attribute name.
        ref_template: The template to use for generating JSON Schema references.
        schema_generator: The class to use for generating the JSON Schema.
        mode: The mode to use for generating the JSON Schema. It can be one of the following:

            - 'validation': Generate a JSON Schema for validating data.
            - 'serialization': Generate a JSON Schema for serializing data.

    Returns:
        The generated JSON Schema.
    """
    schema_generator_instance = schema_generator(by_alias=by_alias, ref_template=ref_template)
    return schema_generator_instance.generate(cls.__pydantic_core_schema__, mode=mode)

models_json_schema ¶

models_json_schema(
    models,
    *,
    by_alias=True,
    title=None,
    description=None,
    ref_template=DEFAULT_REF_TEMPLATE,
    schema_generator=GenerateJsonSchema
)

Utility function to generate a JSON Schema for multiple models.

Parameters:

Name	Type	Description	Default
`models`	`Sequence[tuple[type[BaseModel] \| type[PydanticDataclass], JsonSchemaMode]]`	A sequence of tuples of the form (model, mode).	required
`by_alias`	`bool`	Whether field aliases should be used as keys in the generated JSON Schema.	`True`
`title`	`str \| None`	The title of the generated JSON Schema.	`None`
`description`	`str \| None`	The description of the generated JSON Schema.	`None`
`ref_template`	`str`	The reference template to use for generating JSON Schema references.	`DEFAULT_REF_TEMPLATE`
`schema_generator`	`type[GenerateJsonSchema]`	The schema generator to use for generating the JSON Schema.	`GenerateJsonSchema`

Returns:

Type Description

tuple[dict[tuple[type[BaseModel] | type[PydanticDataclass], JsonSchemaMode], JsonSchemaValue], JsonSchemaValue]

A tuple where: - The first element is a dictionary whose keys are tuples of JSON schema key type and JSON mode, and whose values are the JSON schema corresponding to that pair of inputs. (These schemas may have JsonRef references to definitions that are defined in the second returned element.) - The second element is a JSON schema containing all definitions referenced in the first returned element, along with the optional title and description keys.

Source code in pydantic/json_schema.py

def models_json_schema(
    models: Sequence[tuple[type[BaseModel] | type[PydanticDataclass], JsonSchemaMode]],
    *,
    by_alias: bool = True,
    title: str | None = None,
    description: str | None = None,
    ref_template: str = DEFAULT_REF_TEMPLATE,
    schema_generator: type[GenerateJsonSchema] = GenerateJsonSchema,
) -> tuple[dict[tuple[type[BaseModel] | type[PydanticDataclass], JsonSchemaMode], JsonSchemaValue], JsonSchemaValue]:
    """Utility function to generate a JSON Schema for multiple models.

    Args:
        models: A sequence of tuples of the form (model, mode).
        by_alias: Whether field aliases should be used as keys in the generated JSON Schema.
        title: The title of the generated JSON Schema.
        description: The description of the generated JSON Schema.
        ref_template: The reference template to use for generating JSON Schema references.
        schema_generator: The schema generator to use for generating the JSON Schema.

    Returns:
        A tuple where:
            - The first element is a dictionary whose keys are tuples of JSON schema key type and JSON mode, and
                whose values are the JSON schema corresponding to that pair of inputs. (These schemas may have
                JsonRef references to definitions that are defined in the second returned element.)
            - The second element is a JSON schema containing all definitions referenced in the first returned
                    element, along with the optional title and description keys.
    """
    instance = schema_generator(by_alias=by_alias, ref_template=ref_template)
    inputs = [(m, mode, m.__pydantic_core_schema__) for m, mode in models]
    json_schemas_map, definitions = instance.generate_definitions(inputs)

    json_schema: dict[str, Any] = {}
    if definitions:
        json_schema['$defs'] = definitions
    if title:
        json_schema['title'] = title
    if description:
        json_schema['description'] = description

    return json_schemas_map, json_schema

json_schema

CoreSchemaOrFieldType module-attribute ¶

JsonSchemaValue module-attribute ¶

JsonSchemaMode module-attribute ¶

JsonSchemaWarningKind module-attribute ¶

DEFAULT_REF_TEMPLATE module-attribute ¶

PydanticJsonSchemaWarning ¶

GenerateJsonSchema ¶

ValidationsMapping ¶

build_schema_type_to_method ¶

generate_definitions ¶

generate ¶

generate_inner ¶

any_schema ¶

none_schema ¶

bool_schema ¶

int_schema ¶

float_schema ¶

str_schema ¶

bytes_schema ¶

date_schema ¶

time_schema ¶

datetime_schema ¶

timedelta_schema ¶

literal_schema ¶

is_instance_schema ¶

is_subclass_schema ¶

callable_schema ¶

list_schema ¶

tuple_positional_schema ¶

tuple_variable_schema ¶

set_schema ¶

frozenset_schema ¶

generator_schema ¶

dict_schema ¶

function_before_schema ¶

function_after_schema ¶

function_plain_schema ¶

function_wrap_schema ¶

default_schema ¶

nullable_schema ¶

union_schema ¶

tagged_union_schema ¶

chain_schema ¶

lax_or_strict_schema ¶

json_or_python_schema ¶

typed_dict_schema ¶

typed_dict_field_schema ¶

dataclass_field_schema ¶

model_field_schema ¶

computed_field_schema ¶

model_schema ¶

resolve_schema_to_update ¶

model_fields_schema ¶

field_is_present ¶

field_is_required ¶

dataclass_args_schema ¶

dataclass_schema ¶

arguments_schema ¶

kw_arguments_schema ¶

p_arguments_schema ¶

get_argument_name ¶

call_schema ¶

custom_error_schema ¶

json_schema ¶

url_schema ¶

multi_host_url_schema ¶

uuid_schema ¶

definitions_schema ¶

definition_ref_schema ¶

ser_schema ¶

get_title_from_name ¶

field_title_should_be_set ¶

normalize_name ¶

get_defs_ref ¶

get_cache_defs_ref_schema ¶

handle_ref_overrides ¶

encode_default ¶

update_with_validations ¶

get_json_ref_counts ¶

CoreSchemaOrFieldType `module-attribute` ¶

JsonSchemaValue `module-attribute` ¶

JsonSchemaMode `module-attribute` ¶

JsonSchemaWarningKind `module-attribute` ¶

DEFAULT_REF_TEMPLATE `module-attribute` ¶

WithJsonSchema `dataclass` ¶

Examples `dataclass` ¶

SkipJsonSchema `dataclass` ¶