JSON Schema

使用文档

JSON Schema

json_schema 模块包含类和函数，允许自定义生成 JSON Schema 的方式。

通常，您不需要直接使用此模块；相反，您可以使用 BaseModel.model_json_schema 和 TypeAdapter.json_schema。

CoreSchemaOrFieldType 模块属性

CoreSchemaOrFieldType = Literal[
    CoreSchemaType, CoreSchemaFieldType
]

表示 core_schema.CoreSchemaType 和 core_schema.CoreSchemaFieldType 联合的已定义模式类型的类型别名。

JsonSchemaValue 模块属性

JsonSchemaValue = dict[str, Any]

JSON 模式值的类型别名。这是一个将字符串键映射到任意 JSON 值的字典。

JsonSchemaMode 模块属性

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

表示 JSON 模式模式的类型别名；可以是 'validation'（验证）或 'serialization'（序列化）。

对于某些类型，验证的输入与序列化的输出不同。例如，计算字段只在序列化时存在，而不应在验证时提供。此标志提供了一种方法来指示您是需要验证输入所需的 JSON 模式，还是与序列化输出匹配的 JSON 模式。

JsonSchemaWarningKind 模块属性

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

表示 JSON 模式生成过程中可能发出的警告类型的类型别名。

有关更多详细信息，请参阅 GenerateJsonSchema.render_warning_message。

NoDefault 模块属性

NoDefault = object()

一个用于指示在为具有默认值的核心模式生成 JSON Schema 时不应使用默认值的哨兵值。

DEFAULT_REF_TEMPLATE 模块属性

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

用于生成引用名称的默认格式字符串。

PydanticJsonSchemaWarning

基类：UserWarning

此类别用于发出 JSON 模式生成过程中产生的警告。有关更多详细信息，请参阅 GenerateJsonSchema.emit_warning 和 GenerateJsonSchema.render_warning_message 方法；可以重写这些方法来控制警告行为。

GenerateJsonSchema

GenerateJsonSchema(
    by_alias: bool = True,
    ref_template: str = DEFAULT_REF_TEMPLATE,
    union_format: Literal[
        "any_of", "primitive_type_array"
    ] = "any_of",
)

使用文档

自定义 JSON 模式生成过程

用于生成 JSON 模式的类。

此类根据配置的参数生成 JSON 模式。默认模式方言是 https://json-schema.fullstack.org.cn/draft/2020-12/schema。该类使用 by_alias 配置如何处理具有多个名称的字段，并使用 ref_template 格式化引用名称。

属性

名称	类型	描述
schema_dialect		用于生成模式的 JSON 模式方言。有关方言的更多信息，请参阅 JSON Schema 文档中的 声明方言。
ignored_warning_kinds	set[JsonSchemaWarningKind]	生成模式时要忽略的警告。如果参数 kind 在 ignored_warning_kinds 中，则 self.render_warning_message 将不执行任何操作；可以在子类上修改此值，以轻松控制发出哪些警告。
by_alias		生成模式时是否使用字段别名。
ref_template		生成引用名称时使用的格式字符串。
core_to_json_refs	dict[CoreModeRef, JsonRef]	核心引用到 JSON 引用的映射。
core_to_defs_refs	dict[CoreModeRef, DefsRef]	核心引用到定义引用的映射。
defs_to_core_refs	dict[DefsRef, CoreModeRef]	定义引用到核心引用的映射。
json_to_defs_refs	dict[JsonRef, DefsRef]	JSON 引用到定义引用的映射。
definitions	dict[DefsRef, JsonSchemaValue]	模式中的定义。

参数

名称	类型	描述	默认值
by_alias	bool	在生成的模式中是否使用字段别名。	True
ref_template	str	生成引用名称时使用的格式字符串。	DEFAULT_REF_TEMPLATE
union_format	Literal['any_of', 'primitive_type_array']	组合联合模式时使用的格式。可以是以下之一： 'any_of': 使用 anyOf 关键字组合模式（默认）。 'primitive_type_array': 使用 type 关键字作为字符串数组，包含组合中的每种类型。如果任何模式不是原始类型（string、boolean、null、integer 或 number）或包含约束/元数据，则回退到 any_of。	'any_of'

抛出

类型	描述
JsonSchemaError	如果在生成模式后不小心重用了类的实例。

源代码位于 pydantic/json_schema.py

def __init__(
    self,
    by_alias: bool = True,
    ref_template: str = DEFAULT_REF_TEMPLATE,
    union_format: Literal['any_of', 'primitive_type_array'] = 'any_of',
) -> None:
    self.by_alias = by_alias
    self.ref_template = ref_template
    self.union_format: Literal['any_of', 'primitive_type_array'] = union_format

    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._config_wrapper_stack = _config.ConfigWrapperStack(_config.ConfigWrapper({}))

    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 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 reuse
    # of a single instance of a schema generator
    self._used = False

ValidationsMapping

此类仅包含从 core_schema 属性名称到相应 JSON 模式属性名称的映射。尽管我怀疑不太可能需要，但原则上您可以在 GenerateJsonSchema 的子类中（通过继承 GenerateJsonSchema.ValidationsMapping）覆盖此类以更改这些映射。

build_schema_type_to_method

build_schema_type_to_method() -> dict[
    CoreSchemaOrFieldType,
    Callable[[CoreSchemaOrField], JsonSchemaValue],
]

构建一个将字段映射到生成 JSON 模式的方法的字典。

返回

类型	描述
dict[CoreSchemaOrFieldType, Callable[[CoreSchemaOrField], JsonSchemaValue]]	一个包含 CoreSchemaOrFieldType 到处理方法映射的字典。

抛出

类型	描述
TypeError	如果尚未为给定的 pydantic 核心模式类型定义用于生成 JSON 模式的方法。

源代码位于 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] = list(get_literal_values(CoreSchemaOrFieldType))
    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
            if os.getenv('PYDANTIC_PRIVATE_ALLOW_UNHANDLED_SCHEMA_TYPES'):
                continue
            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: Sequence[
        tuple[JsonSchemaKeyT, JsonSchemaMode, CoreSchema]
    ]
) -> tuple[
    dict[
        tuple[JsonSchemaKeyT, JsonSchemaMode],
        JsonSchemaValue,
    ],
    dict[DefsRef, JsonSchemaValue],
]

从核心模式列表生成 JSON 模式定义，将生成的定义与将输入键链接到定义引用的映射配对。

参数

名称	类型	描述	默认值
inputs	Sequence[tuple[JsonSchemaKeyT, JsonSchemaMode, CoreSchema]]	元组序列，其中： 第一个元素是 JSON 模式键类型。 第二个元素是 JSON 模式：'validation' 或 'serialization'。 第三个元素是核心模式。	必需

返回

类型	描述
tuple[dict[tuple[JsonSchemaKeyT, JsonSchemaMode], JsonSchemaValue], dict[DefsRef, JsonSchemaValue]]	一个元组，其中： 第一个元素是一个字典，其键是 JSON 模式键类型和 JSON 模式的元组，其值是与该输入对对应的 JSON 模式。（这些模式可能包含对第二个返回元素中定义的定义的 JsonRef 引用。） 第二个元素是一个字典，其键是第一个返回元素中 JSON 模式的定义引用，其值是实际的 JSON 模式定义。

抛出

类型	描述
PydanticUserError	如果 JSON 模式生成器已被用于生成 JSON 模式，则引发此错误。

源代码位于 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 _, 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, self.sort(json_schema['$defs'])  # type: ignore

generate

generate(
    schema: CoreSchema, mode: JsonSchemaMode = "validation"
) -> JsonSchemaValue

以指定模式为指定模式生成 JSON 模式。

参数

名称	类型	描述	默认值
schema	CoreSchema	一个 Pydantic 模型。	必需
mode	JsonSchemaMode	生成模式的模式。默认为 'validation'。	'validation'

返回

类型	描述
JsonSchemaValue	表示指定模式的 JSON 模式。

抛出

类型	描述
PydanticUserError	如果 JSON 模式生成器已被用于生成 JSON 模式。

源代码位于 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)

    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 and ref_json_schema is not None and len(json_schema) == 1:
            # "Unpack" the ref since this is the only reference and there are no sibling keys
            json_schema = ref_json_schema.copy()  # copy to prevent recursive dict reference
            json_ref_counts[ref] -= 1
            ref = cast(JsonRef, json_schema.get('$ref'))
        ref = None

    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 self.sort(json_schema)

generate_inner

generate_inner(
    schema: CoreSchemaOrField,
) -> JsonSchemaValue

为给定的核心模式生成 JSON 模式。

参数

名称	类型	描述	默认值
schema	CoreSchemaOrField	给定的核心模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

TODO：这里的嵌套函数定义似乎是不好的做法，我希望在未来的 PR 中解开它们。如果我们可以稍微缩短 JSON 模式生成的调用堆栈，那就太好了，我认为这里有这种潜力。

源代码位于 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.

    TODO: the nested function definitions here seem like bad practice, I'd like to unpack these
    in a future PR. It'd be great if we could shorten the call stack a bit for JSON schema generation,
    and I think there's potential for that here.
    """
    # 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]}

    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'])
            # 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 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:
            # In this case, we skip the JSON Schema generation of the schema
            # and use the `'serialization'` schema instead (canonical example:
            # `Annotated[int, PlainSerializer(str)]`).
            ser_schema = schema_or_field['serialization']  # type: ignore
            json_schema = self.ser_schema(ser_schema)

            # It might be that the 'serialization'` is skipped depending on `when_used`.
            # This is only relevant for `nullable` schemas though, so we special case here.
            if (
                json_schema is not None
                and ser_schema.get('when_used') in ('unless-none', 'json-unless-none')
                and schema_or_field['type'] == 'nullable'
            ):
                json_schema = self.get_union_of_schemas([{'type': 'null'}, json_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}')
        return json_schema

    current_handler = _schema_generation_shared.GenerateJsonSchemaHandler(self, handler_func)

    metadata = cast(_core_metadata.CoreMetadata, schema.get('metadata', {}))

    # TODO: I dislike that we have to wrap these basic dict updates in callables, is there any way around this?

    if js_updates := metadata.get('pydantic_js_updates'):

        def js_updates_handler_func(
            schema_or_field: CoreSchemaOrField,
            current_handler: GetJsonSchemaHandler = current_handler,
        ) -> JsonSchemaValue:
            json_schema = {**current_handler(schema_or_field), **js_updates}
            return json_schema

        current_handler = _schema_generation_shared.GenerateJsonSchemaHandler(self, js_updates_handler_func)

    if js_extra := metadata.get('pydantic_js_extra'):

        def js_extra_handler_func(
            schema_or_field: CoreSchemaOrField,
            current_handler: GetJsonSchemaHandler = current_handler,
        ) -> JsonSchemaValue:
            json_schema = current_handler(schema_or_field)
            if isinstance(js_extra, dict):
                json_schema.update(to_jsonable_python(js_extra))
            elif callable(js_extra):
                # similar to typing issue in _update_class_schema when we're working with callable js extra
                js_extra(json_schema)  # type: ignore
            return json_schema

        current_handler = _schema_generation_shared.GenerateJsonSchemaHandler(self, js_extra_handler_func)

    for js_modify_function in 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.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:
            return js_modify_function(schema_or_field, current_handler)

        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)
    return json_schema

sort

sort(
    value: JsonSchemaValue, parent_key: str | None = None
) -> JsonSchemaValue

重写此方法以自定义 JSON 模式的排序（例如，完全不排序，无条件排序所有键等）。

默认情况下，按字母顺序对 JSON 模式中的键进行排序，跳过 'properties' 和 'default' 键以保留字段定义顺序。此排序是递归的，因此它也将对所有嵌套字典进行排序。

源代码位于 pydantic/json_schema.py

def sort(self, value: JsonSchemaValue, parent_key: str | None = None) -> JsonSchemaValue:
    """Override this method to customize the sorting of the JSON schema (e.g., don't sort at all, sort all keys unconditionally, etc.)

    By default, alphabetically sort the keys in the JSON schema, skipping the 'properties' and 'default' keys to preserve field definition order.
    This sort is recursive, so it will sort all nested dictionaries as well.
    """
    sorted_dict: dict[str, JsonSchemaValue] = {}
    keys = value.keys()
    if parent_key not in ('properties', 'default'):
        keys = sorted(keys)
    for key in keys:
        sorted_dict[key] = self._sort_recursive(value[key], parent_key=key)
    return sorted_dict

invalid_schema

invalid_schema(schema: InvalidSchema) -> JsonSchemaValue

占位符 - 永远不应调用。

源代码位于 pydantic/json_schema.py

def invalid_schema(self, schema: core_schema.InvalidSchema) -> JsonSchemaValue:
    """Placeholder - should never be called."""

    raise RuntimeError('Cannot generate schema for invalid_schema. This is a bug! Please report it.')

any_schema

any_schema(schema: AnySchema) -> JsonSchemaValue

生成匹配任何值的 JSON 模式。

参数

名称	类型	描述	默认值
schema	AnySchema	核心模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

源代码位于 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: NoneSchema) -> JsonSchemaValue

生成匹配 None 的 JSON 模式。

参数

名称	类型	描述	默认值
schema	NoneSchema	核心模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

源代码位于 pydantic/json_schema.py

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

    Args:
        schema: The core schema.

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

bool_schema

bool_schema(schema: BoolSchema) -> JsonSchemaValue

生成匹配布尔值的 JSON 模式。

参数

名称	类型	描述	默认值
schema	BoolSchema	核心模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

源代码位于 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: IntSchema) -> JsonSchemaValue

生成匹配整数值的 JSON 模式。

参数

名称	类型	描述	默认值
schema	IntSchema	核心模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

源代码位于 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: FloatSchema) -> JsonSchemaValue

生成匹配浮点值的 JSON 模式。

参数

名称	类型	描述	默认值
schema	FloatSchema	核心模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

源代码位于 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

decimal_schema

decimal_schema(schema: DecimalSchema) -> JsonSchemaValue

生成匹配十进制值的 JSON 模式。

参数

名称	类型	描述	默认值
schema	DecimalSchema	核心模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

源代码位于 pydantic/json_schema.py

def decimal_schema(self, schema: core_schema.DecimalSchema) -> JsonSchemaValue:
    """Generates a JSON schema that matches a decimal value.

    Args:
        schema: The core schema.

    Returns:
        The generated JSON schema.
    """

    def get_decimal_pattern(schema: core_schema.DecimalSchema) -> str:
        max_digits = schema.get('max_digits')
        decimal_places = schema.get('decimal_places')

        pattern = (
            r'^(?!^[-+.]*$)[+-]?0*'  # check it is not empty string and not one or sequence of ".+-" characters.
        )

        # Case 1: Both max_digits and decimal_places are set
        if max_digits is not None and decimal_places is not None:
            integer_places = max(0, max_digits - decimal_places)
            pattern += (
                rf'(?:'
                rf'\d{{0,{integer_places}}}'
                rf'|'
                rf'(?=[\d.]{{1,{max_digits + 1}}}0*$)'
                rf'\d{{0,{integer_places}}}\.\d{{0,{decimal_places}}}0*$'
                rf')'
            )

        # Case 2: Only max_digits is set
        elif max_digits is not None and decimal_places is None:
            pattern += (
                rf'(?:'
                rf'\d{{0,{max_digits}}}'
                rf'|'
                rf'(?=[\d.]{{1,{max_digits + 1}}}0*$)'
                rf'\d*\.\d*0*$'
                rf')'
            )

        # Case 3: Only decimal_places is set
        elif max_digits is None and decimal_places is not None:
            pattern += rf'\d*\.?\d{{0,{decimal_places}}}0*$'

        # Case 4: Both are None (no restrictions)
        else:
            pattern += r'\d*\.?\d*$'  # look for arbitrary integer or decimal

        return pattern

    json_schema = self.str_schema(core_schema.str_schema(pattern=get_decimal_pattern(schema)))
    if self.mode == 'validation':
        multiple_of = schema.get('multiple_of')
        le = schema.get('le')
        ge = schema.get('ge')
        lt = schema.get('lt')
        gt = schema.get('gt')
        json_schema = {
            'anyOf': [
                self.float_schema(
                    core_schema.float_schema(
                        allow_inf_nan=schema.get('allow_inf_nan'),
                        multiple_of=None if multiple_of is None else float(multiple_of),
                        le=None if le is None else float(le),
                        ge=None if ge is None else float(ge),
                        lt=None if lt is None else float(lt),
                        gt=None if gt is None else float(gt),
                    )
                ),
                json_schema,
            ],
        }
    return json_schema

str_schema

str_schema(schema: StringSchema) -> JsonSchemaValue

生成匹配字符串值的 JSON 模式。

参数

名称	类型	描述	默认值
schema	StringSchema	核心模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

源代码位于 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)
    if isinstance(json_schema.get('pattern'), Pattern):
        # TODO: should we add regex flags to the pattern?
        json_schema['pattern'] = json_schema.get('pattern').pattern  # type: ignore
    return json_schema

bytes_schema

bytes_schema(schema: BytesSchema) -> JsonSchemaValue

生成匹配字节值的 JSON 模式。

参数

名称	类型	描述	默认值
schema	BytesSchema	核心模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

源代码位于 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': 'base64url' if self._config.ser_json_bytes == 'base64' else 'binary'}
    self.update_with_validations(json_schema, schema, self.ValidationsMapping.bytes)
    return json_schema

date_schema

date_schema(schema: DateSchema) -> JsonSchemaValue

生成匹配日期值的 JSON 模式。

参数

名称	类型	描述	默认值
schema	DateSchema	核心模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

源代码位于 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.
    """
    return {'type': 'string', 'format': 'date'}

time_schema

time_schema(schema: TimeSchema) -> JsonSchemaValue

生成匹配时间值的 JSON 模式。

参数

名称	类型	描述	默认值
schema	TimeSchema	核心模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

源代码位于 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: DatetimeSchema) -> JsonSchemaValue

生成匹配日期时间值的 JSON 模式。

参数

名称	类型	描述	默认值
schema	DatetimeSchema	核心模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

源代码位于 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: TimedeltaSchema,
) -> JsonSchemaValue

生成匹配 timedelta 值的 JSON 模式。

参数

名称	类型	描述	默认值
schema	TimedeltaSchema	核心模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

源代码位于 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.
    """
    if self._config.ser_json_timedelta == 'float':
        return {'type': 'number'}
    return {'type': 'string', 'format': 'duration'}

literal_schema

literal_schema(schema: LiteralSchema) -> JsonSchemaValue

生成匹配字面值的 JSON 模式。

参数

名称	类型	描述	默认值
schema	LiteralSchema	核心模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

源代码位于 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 = [to_jsonable_python(v.value if isinstance(v, Enum) else v) for v in schema['expected']]

    result: dict[str, Any] = {}
    if len(expected) == 1:
        result['const'] = expected[0]
    else:
        result['enum'] = expected

    types = {type(e) for e in expected}
    if types == {str}:
        result['type'] = 'string'
    elif types == {int}:
        result['type'] = 'integer'
    elif types == {float}:
        result['type'] = 'number'
    elif types == {bool}:
        result['type'] = 'boolean'
    elif types == {list}:
        result['type'] = 'array'
    elif types == {type(None)}:
        result['type'] = 'null'
    return result

missing_sentinel_schema

missing_sentinel_schema(
    schema: MissingSentinelSchema,
) -> JsonSchemaValue

生成匹配 MISSING 哨兵值的 JSON 模式。

参数

名称	类型	描述	默认值
schema	MissingSentinelSchema	核心模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

源代码位于 pydantic/json_schema.py

def missing_sentinel_schema(self, schema: core_schema.MissingSentinelSchema) -> JsonSchemaValue:
    """Generates a JSON schema that matches the `MISSING` sentinel value.

    Args:
        schema: The core schema.

    Returns:
        The generated JSON schema.
    """
    raise PydanticOmit

enum_schema

enum_schema(schema: EnumSchema) -> JsonSchemaValue

生成匹配枚举值的 JSON 模式。

参数

名称	类型	描述	默认值
schema	EnumSchema	核心模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

源代码位于 pydantic/json_schema.py

def enum_schema(self, schema: core_schema.EnumSchema) -> JsonSchemaValue:
    """Generates a JSON schema that matches an Enum value.

    Args:
        schema: The core schema.

    Returns:
        The generated JSON schema.
    """
    enum_type = schema['cls']
    description = None if not enum_type.__doc__ else inspect.cleandoc(enum_type.__doc__)
    if (
        description == 'An enumeration.'
    ):  # This is the default value provided by enum.EnumMeta.__new__; don't use it
        description = None
    result: dict[str, Any] = {'title': enum_type.__name__, 'description': description}
    result = {k: v for k, v in result.items() if v is not None}

    expected = [to_jsonable_python(v.value) for v in schema['members']]

    result['enum'] = expected

    types = {type(e) for e in expected}
    if isinstance(enum_type, str) or types == {str}:
        result['type'] = 'string'
    elif isinstance(enum_type, int) or types == {int}:
        result['type'] = 'integer'
    elif isinstance(enum_type, float) or types == {float}:
        result['type'] = 'number'
    elif types == {bool}:
        result['type'] = 'boolean'
    elif types == {list}:
        result['type'] = 'array'

    return result

is_instance_schema

is_instance_schema(
    schema: IsInstanceSchema,
) -> JsonSchemaValue

处理用于检查值是否为类实例的核心模式的 JSON 模式生成。

除非在子类中重写，否则此操作会引发错误。

参数

名称	类型	描述	默认值
schema	IsInstanceSchema	核心模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

源代码位于 pydantic/json_schema.py

def is_instance_schema(self, schema: core_schema.IsInstanceSchema) -> JsonSchemaValue:
    """Handles JSON schema generation for a core schema that checks if a value is an instance of a class.

    Unless overridden in a subclass, this raises an error.

    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: IsSubclassSchema,
) -> JsonSchemaValue

处理用于检查值是否为类子类的核心模式的 JSON 模式生成。

为了与 v1 兼容，这不会引发错误，但可以重写以更改此行为。

参数

名称	类型	描述	默认值
schema	IsSubclassSchema	核心模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

源代码位于 pydantic/json_schema.py

def is_subclass_schema(self, schema: core_schema.IsSubclassSchema) -> JsonSchemaValue:
    """Handles JSON schema generation for a core schema that checks if a value is a subclass of a class.

    For backwards compatibility with v1, this does not raise an error, but can be overridden to change this.

    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: CallableSchema) -> JsonSchemaValue

生成匹配可调用值的 JSON 模式。

除非在子类中重写，否则此操作会引发错误。

参数

名称	类型	描述	默认值
schema	CallableSchema	核心模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

源代码位于 pydantic/json_schema.py

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

    Unless overridden in a subclass, this raises an error.

    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: ListSchema) -> JsonSchemaValue

返回匹配列表模式的模式。

参数

名称	类型	描述	默认值
schema	ListSchema	核心模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

源代码位于 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: TupleSchema,
) -> JsonSchemaValue

已被 tuple_schema 替换。

源代码位于 pydantic/json_schema.py

@deprecated('`tuple_positional_schema` is deprecated. Use `tuple_schema` instead.', category=None)
@final
def tuple_positional_schema(self, schema: core_schema.TupleSchema) -> JsonSchemaValue:
    """Replaced by `tuple_schema`."""
    warnings.warn(
        '`tuple_positional_schema` is deprecated. Use `tuple_schema` instead.',
        PydanticDeprecatedSince26,
        stacklevel=2,
    )
    return self.tuple_schema(schema)

tuple_variable_schema

tuple_variable_schema(
    schema: TupleSchema,
) -> JsonSchemaValue

已被 tuple_schema 替换。

源代码位于 pydantic/json_schema.py

@deprecated('`tuple_variable_schema` is deprecated. Use `tuple_schema` instead.', category=None)
@final
def tuple_variable_schema(self, schema: core_schema.TupleSchema) -> JsonSchemaValue:
    """Replaced by `tuple_schema`."""
    warnings.warn(
        '`tuple_variable_schema` is deprecated. Use `tuple_schema` instead.',
        PydanticDeprecatedSince26,
        stacklevel=2,
    )
    return self.tuple_schema(schema)

tuple_schema

tuple_schema(schema: TupleSchema) -> JsonSchemaValue

生成匹配元组模式的 JSON 模式，例如 tuple[int, str, bool] 或 tuple[int, ...]。

参数

名称	类型	描述	默认值
schema	TupleSchema	核心模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

源代码位于 pydantic/json_schema.py

def tuple_schema(self, schema: core_schema.TupleSchema) -> JsonSchemaValue:
    """Generates a JSON schema that matches a tuple schema e.g. `tuple[int,
    str, bool]` or `tuple[int, ...]`.

    Args:
        schema: The core schema.

    Returns:
        The generated JSON schema.
    """
    json_schema: JsonSchemaValue = {'type': 'array'}
    if 'variadic_item_index' in schema:
        variadic_item_index = schema['variadic_item_index']
        if variadic_item_index > 0:
            json_schema['minItems'] = variadic_item_index
            json_schema['prefixItems'] = [
                self.generate_inner(item) for item in schema['items_schema'][:variadic_item_index]
            ]
        if variadic_item_index + 1 == len(schema['items_schema']):
            # if the variadic item is the last item, then represent it faithfully
            json_schema['items'] = self.generate_inner(schema['items_schema'][variadic_item_index])
        else:
            # otherwise, 'items' represents the schema for the variadic
            # item plus the suffix, so just allow anything for simplicity
            # for now
            json_schema['items'] = True
    else:
        prefixItems = [self.generate_inner(item) for item in schema['items_schema']]
        if prefixItems:
            json_schema['prefixItems'] = prefixItems
        json_schema['minItems'] = len(prefixItems)
        json_schema['maxItems'] = len(prefixItems)
    self.update_with_validations(json_schema, schema, self.ValidationsMapping.array)
    return json_schema

set_schema

set_schema(schema: SetSchema) -> JsonSchemaValue

生成匹配集合模式的 JSON 模式。

参数

名称	类型	描述	默认值
schema	SetSchema	核心模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

源代码位于 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: FrozenSetSchema,
) -> JsonSchemaValue

生成匹配 frozenset 模式的 JSON 模式。

参数

名称	类型	描述	默认值
schema	FrozenSetSchema	核心模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

源代码位于 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: GeneratorSchema,
) -> JsonSchemaValue

返回表示所提供 GeneratorSchema 的 JSON 模式。

参数

名称	类型	描述	默认值
schema	GeneratorSchema	模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

源代码位于 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: DictSchema) -> JsonSchemaValue

生成匹配字典模式的 JSON 模式。

参数

名称	类型	描述	默认值
schema	DictSchema	核心模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

源代码位于 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 {}
    if '$ref' not in keys_schema:
        keys_pattern = keys_schema.pop('pattern', None)
        # Don't give a title to patternProperties/propertyNames:
        keys_schema.pop('title', None)
    else:
        # Here, we assume that if the keys schema is a definition reference,
        # it can't be a simple string core schema (and thus no pattern can exist).
        # However, this is only in practice (in theory, a definition reference core
        # schema could be generated for a simple string schema).
        # Note that we avoid calling `self.resolve_ref_schema`, as it might not exist yet.
        keys_pattern = None

    values_schema = self.generate_inner(schema['values_schema']).copy() if 'values_schema' in schema else {}
    # don't give a title to additionalProperties:
    values_schema.pop('title', None)

    if values_schema or keys_pattern is not None:
        if keys_pattern is None:
            json_schema['additionalProperties'] = values_schema
        else:
            json_schema['patternProperties'] = {keys_pattern: values_schema}
    else:  # for `dict[str, Any]`, we allow any key and any value, since `str` is the default key type
        json_schema['additionalProperties'] = True

    if (
        # The len check indicates that constraints are probably present:
        (keys_schema.get('type') == 'string' and len(keys_schema) > 1)
        # If this is a definition reference schema, it most likely has constraints:
        or '$ref' in keys_schema
    ):
        keys_schema.pop('type', None)
        json_schema['propertyNames'] = keys_schema

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

function_before_schema

function_before_schema(
    schema: BeforeValidatorFunctionSchema,
) -> JsonSchemaValue

生成匹配函数前置模式的 JSON 模式。

参数

名称	类型	描述	默认值
schema	BeforeValidatorFunctionSchema	核心模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

源代码位于 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.
    """
    if self.mode == 'validation' and (input_schema := schema.get('json_schema_input_schema')):
        return self.generate_inner(input_schema)

    return self.generate_inner(schema['schema'])

function_after_schema

function_after_schema(
    schema: AfterValidatorFunctionSchema,
) -> JsonSchemaValue

生成匹配函数后置模式的 JSON 模式。

参数

名称	类型	描述	默认值
schema	AfterValidatorFunctionSchema	核心模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

源代码位于 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.generate_inner(schema['schema'])

function_plain_schema

function_plain_schema(
    schema: PlainValidatorFunctionSchema,
) -> JsonSchemaValue

生成匹配函数纯模式的 JSON 模式。

参数

名称	类型	描述	默认值
schema	PlainValidatorFunctionSchema	核心模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

源代码位于 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.
    """
    if self.mode == 'validation' and (input_schema := schema.get('json_schema_input_schema')):
        return self.generate_inner(input_schema)

    return self.handle_invalid_for_json_schema(
        schema, f'core_schema.PlainValidatorFunctionSchema ({schema["function"]})'
    )

function_wrap_schema

function_wrap_schema(
    schema: WrapValidatorFunctionSchema,
) -> JsonSchemaValue

生成匹配函数包装模式的 JSON 模式。

参数

名称	类型	描述	默认值
schema	WrapValidatorFunctionSchema	核心模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

源代码位于 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.
    """
    if self.mode == 'validation' and (input_schema := schema.get('json_schema_input_schema')):
        return self.generate_inner(input_schema)

    return self.generate_inner(schema['schema'])

default_schema

default_schema(
    schema: WithDefaultSchema,
) -> JsonSchemaValue

生成匹配具有默认值的模式的 JSON 模式。

参数

名称	类型	描述	默认值
schema	WithDefaultSchema	核心模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

源代码位于 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'])

    default = self.get_default_value(schema)
    if default is NoDefault or default is MISSING:
        return json_schema

    # we reflect the application of custom plain, no-info serializers to defaults for
    # JSON Schemas viewed in serialization mode:
    # TODO: improvements along with https://github.com/pydantic/pydantic/issues/8208
    if self.mode == 'serialization':
        # `_get_ser_schema_for_default_value()` is used to unpack potentially nested validator schemas:
        ser_schema = _get_ser_schema_for_default_value(schema['schema'])
        if (
            ser_schema is not None
            and (ser_func := ser_schema.get('function'))
            and not (default is None and ser_schema.get('when_used') in ('unless-none', 'json-unless-none'))
        ):
            try:
                default = ser_func(default)  # type: ignore
            except Exception:
                # It might be that the provided default needs to be validated (read: parsed) first
                # (assuming `validate_default` is enabled). However, we can't perform
                # such validation during JSON Schema generation so we don't support
                # this pattern for now.
                # (One example is when using `foo: ByteSize = '1MB'`, which validates and
                # serializes as an int. In this case, `ser_func` is `int` and `int('1MB')` fails).
                self.emit_warning(
                    'non-serializable-default',
                    f'Unable to serialize value {default!r} with the plain serializer; excluding default from JSON schema',
                )
                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

    json_schema['default'] = encoded_default
    return json_schema

get_default_value

get_default_value(schema: WithDefaultSchema) -> Any

获取在为具有默认值的核心模式生成 JSON Schema 时使用的默认值。

默认实现是使用静态定义的默认值。如果想使用默认工厂，可以重写此方法。

参数

名称	类型	描述	默认值
schema	WithDefaultSchema	'with-default' 核心模式。	必需

返回

类型	描述
Any	要使用的默认值，如果没有可用的默认值，则为 NoDefault。

源代码位于 pydantic/json_schema.py

def get_default_value(self, schema: core_schema.WithDefaultSchema) -> Any:
    """Get the default value to be used when generating a JSON Schema for a core schema with a default.

    The default implementation is to use the statically defined default value. This method can be overridden
    if you want to make use of the default factory.

    Args:
        schema: The `'with-default'` core schema.

    Returns:
        The default value to use, or [`NoDefault`][pydantic.json_schema.NoDefault] if no default
            value is available.
    """
    return schema.get('default', NoDefault)

nullable_schema

nullable_schema(schema: NullableSchema) -> JsonSchemaValue

生成匹配允许空值的模式的 JSON 模式。

参数

名称	类型	描述	默认值
schema	NullableSchema	核心模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

源代码位于 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:
        return self.get_union_of_schemas([inner_json_schema, null_schema])

union_schema

union_schema(schema: UnionSchema) -> JsonSchemaValue

生成匹配允许值与给定任何模式匹配的模式的 JSON 模式。

参数

名称	类型	描述	默认值
schema	UnionSchema	核心模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

源代码位于 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 choice in choices:
        # choice will be a tuple if an explicit label was provided
        choice_schema = choice[0] if isinstance(choice, tuple) else choice
        try:
            generated.append(self.generate_inner(choice_schema))
        except PydanticOmit:
            continue
        except PydanticInvalidForJsonSchema as exc:
            self.emit_warning('skipped-choice', exc.message)
    if len(generated) == 1:
        return generated[0]
    return self.get_union_of_schemas(generated)

get_union_of_schemas

get_union_of_schemas(
    schemas: list[JsonSchemaValue],
) -> JsonSchemaValue

返回所提供的 JSON Schema 联合的 JSON Schema 表示。

结果取决于配置的 'union_format'。

参数

名称	类型	描述	默认值
schemas	列表[JsonSchemaValue]	要包含在联合中的 JSON Schema 列表。	必需

返回

类型	描述
JsonSchemaValue	表示模式联合的 JSON 模式。

源代码位于 pydantic/json_schema.py

def get_union_of_schemas(self, schemas: list[JsonSchemaValue]) -> JsonSchemaValue:
    """Returns the JSON Schema representation for the union of the provided JSON Schemas.

    The result depends on the configured `'union_format'`.

    Args:
        schemas: The list of JSON Schemas to be included in the union.

    Returns:
        The JSON Schema representing the union of schemas.
    """
    if self.union_format == 'primitive_type_array':
        types: list[str] = []
        for schema in schemas:
            schema_types: list[str] | str | None = schema.get('type')
            if schema_types is None:
                # No type, meaning it can be a ref or an empty schema.
                break
            if not isinstance(schema_types, list):
                schema_types = [schema_types]
            if not all(t in _PRIMITIVE_JSON_SCHEMA_TYPES for t in schema_types):
                break
            if len(schema) != 1:
                # We only want to include types that don't have any constraints. For instance,
                # if `schemas = [{'type': 'string', 'maxLength': 3}, {'type': 'string', 'minLength': 5}]`,
                # we don't want to produce `{'type': 'string', 'maxLength': 3, 'minLength': 5}`.
                # Same if we have some metadata (e.g. `title`) on a specific union member, we want to preserve it.
                break

            types.extend(schema_types)
        else:
            # If we got there, all the schemas where valid to be used with the `'primitive_type_array` format
            return {'type': list(dict.fromkeys(types))}

    return self.get_flattened_anyof(schemas)

tagged_union_schema

tagged_union_schema(
    schema: TaggedUnionSchema,
) -> JsonSchemaValue

生成匹配模式的 JSON 模式，该模式允许值与给定模式中的任何一个匹配，其中模式用指示应使用哪个模式验证值的鉴别器字段进行标记。

参数

名称	类型	描述	默认值
schema	TaggedUnionSchema	核心模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

源代码位于 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
        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)

    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: ChainSchema) -> JsonSchemaValue

生成匹配 core_schema.ChainSchema 的 JSON 模式。

为验证生成模式时，我们返回链中第一步的验证 JSON 模式。对于序列化，我们返回链中最后一步的序列化 JSON 模式。

参数

名称	类型	描述	默认值
schema	ChainSchema	核心模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

源代码位于 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: LaxOrStrictSchema,
) -> JsonSchemaValue

生成匹配允许值与宽松模式或严格模式匹配的模式的 JSON 模式。

参数

名称	类型	描述	默认值
schema	LaxOrStrictSchema	核心模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

源代码位于 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: JsonOrPythonSchema,
) -> JsonSchemaValue

生成匹配允许值与 JSON 模式或 Python 模式匹配的模式的 JSON 模式。

使用 JSON 模式而不是 Python 模式。如果要使用 Python 模式，则应重写此方法。

参数

名称	类型	描述	默认值
schema	JsonOrPythonSchema	核心模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

源代码位于 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: TypedDictSchema,
) -> JsonSchemaValue

生成匹配定义 TypedDict 的模式的 JSON 模式。

参数

名称	类型	描述	默认值
schema	TypedDictSchema	核心模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

源代码位于 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', [])))
    cls = schema.get('cls')
    config = _get_typed_dict_config(cls)
    with self._config_wrapper_stack.push(config):
        json_schema = self._named_required_fields_schema(named_required_fields)

    # There's some duplication between `extra_behavior` and
    # the config's `extra`/core config's `extra_fields_behavior`.
    # However, it is common to manually create TypedDictSchemas,
    # where you don't necessarily have a class.
    # At runtime, `extra_behavior` takes priority over the config
    # for validation, so follow the same for the JSON Schema:
    if schema.get('extra_behavior') == 'forbid':
        json_schema['additionalProperties'] = False
    elif schema.get('extra_behavior') == 'allow':
        if 'extras_schema' in schema and schema['extras_schema'] != {'type': 'any'}:
            json_schema['additionalProperties'] = self.generate_inner(schema['extras_schema'])
        else:
            json_schema['additionalProperties'] = True

    if cls is not None:
        # `_update_class_schema()` will not override
        # `additionalProperties` if already present:
        self._update_class_schema(json_schema, cls, config)
    elif 'additionalProperties' not in json_schema:
        extra = schema.get('config', {}).get('extra_fields_behavior')
        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: TypedDictField,
) -> JsonSchemaValue

生成匹配定义 TypedDict 字段的模式的 JSON 模式。

参数

名称	类型	描述	默认值
schema	TypedDictField	核心模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

源代码位于 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: DataclassField,
) -> JsonSchemaValue

生成匹配定义数据类字段的模式的 JSON 模式。

参数

名称	类型	描述	默认值
schema	DataclassField	核心模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

源代码位于 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: ModelField) -> JsonSchemaValue

生成匹配定义模型字段的模式的 JSON 模式。

参数

名称	类型	描述	默认值
schema	ModelField	核心模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

源代码位于 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: ComputedField,
) -> JsonSchemaValue

生成匹配定义计算字段的模式的 JSON 模式。

参数

名称	类型	描述	默认值
schema	ComputedField	核心模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

源代码位于 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: ModelSchema) -> JsonSchemaValue

生成匹配定义模型的模式的 JSON 模式。

参数

名称	类型	描述	默认值
schema	ModelSchema	核心模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

源代码位于 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.
    cls = cast('type[BaseModel]', schema['cls'])
    config = cls.model_config

    with self._config_wrapper_stack.push(config):
        json_schema = self.generate_inner(schema['schema'])

    self._update_class_schema(json_schema, cls, config)

    return json_schema

resolve_ref_schema

resolve_ref_schema(
    json_schema: JsonSchemaValue,
) -> JsonSchemaValue

如果 JsonSchemaValue 是 $ref 模式，则将其解析为非引用模式。

参数

名称	类型	描述	默认值
json_schema	JsonSchemaValue	要解析的模式。	必需

返回

类型	描述
JsonSchemaValue	解析后的模式。

抛出

类型	描述
RuntimeError	如果在定义中找不到模式引用。

源代码位于 pydantic/json_schema.py

def resolve_ref_schema(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.

    Raises:
        RuntimeError: If the schema reference can't be found in definitions.
    """
    while '$ref' in json_schema:
        ref = json_schema['$ref']
        schema_to_update = self.get_schema_from_definitions(JsonRef(ref))
        if schema_to_update is None:
            raise RuntimeError(f'Cannot update undefined schema for $ref={ref}')
        json_schema = schema_to_update
    return json_schema

model_fields_schema

model_fields_schema(
    schema: ModelFieldsSchema,
) -> JsonSchemaValue

生成匹配定义模型字段的模式的 JSON 模式。

参数

名称	类型	描述	默认值
schema	ModelFieldsSchema	核心模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

源代码位于 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)
    extras_schema = schema.get('extras_schema', None)
    if extras_schema is not None:
        schema_to_update = self.resolve_ref_schema(json_schema)
        schema_to_update['additionalProperties'] = self.generate_inner(extras_schema)
    return json_schema

field_is_present

field_is_present(field: CoreSchemaField) -> bool

字段是否应包含在生成的 JSON 模式中。

参数

名称	类型	描述	默认值
field	CoreSchemaField	字段本身的模式。	必需

返回

类型	描述
bool	如果字段应包含在生成的 JSON 模式中，则为 True，否则为 False。

源代码位于 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: ModelField | DataclassField | TypedDictField,
    total: bool,
) -> bool

字段是否应在生成的 JSON 模式中标记为必需。（请注意，如果字段不存在于 JSON 模式中，则此项无关紧要。）

参数

名称	类型	描述	默认值
field	ModelField | DataclassField | TypedDictField	字段本身的模式。	必需
total	bool	仅适用于 TypedDictField。指示此字段所属的 TypedDict 是否是完整的，在这种情况下，任何未明确指定 required=False 的字段都是必需的。	必需

返回

类型	描述
bool	如果字段应在生成的 JSON 模式中标记为必需，则为 True，否则为 False。

源代码位于 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' and self._config.json_schema_serialization_defaults_required:
        return not field.get('serialization_exclude')
    else:
        if field['type'] == 'typed-dict-field':
            return field.get('required', total)
        else:
            return field['schema']['type'] != 'default'

dataclass_args_schema

dataclass_args_schema(
    schema: DataclassArgsSchema,
) -> JsonSchemaValue

生成匹配定义数据类构造函数参数的模式的 JSON 模式。

参数

名称	类型	描述	默认值
schema	DataclassArgsSchema	核心模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

源代码位于 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: DataclassSchema,
) -> JsonSchemaValue

生成匹配定义数据类的模式的 JSON 模式。

参数

名称	类型	描述	默认值
schema	DataclassSchema	核心模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

源代码位于 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.
    """
    from ._internal._dataclasses import is_stdlib_dataclass

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

    with self._config_wrapper_stack.push(config):
        json_schema = self.generate_inner(schema['schema']).copy()

    self._update_class_schema(json_schema, cls, config)

    # Dataclass-specific handling of description
    if is_stdlib_dataclass(cls):
        # 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: ArgumentsSchema,
) -> JsonSchemaValue

生成匹配定义函数参数的模式的 JSON 模式。

参数

名称	类型	描述	默认值
schema	ArgumentsSchema	核心模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

源代码位于 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.
    """
    prefer_positional = schema.get('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)

    raise PydanticInvalidForJsonSchema(
        'Unable to generate JSON schema for arguments validator with positional-only and keyword-only arguments'
    )

kw_arguments_schema

kw_arguments_schema(
    arguments: list[ArgumentsParameter],
    var_kwargs_schema: CoreSchema | None,
) -> JsonSchemaValue

生成匹配定义函数关键字参数的模式的 JSON 模式。

参数

名称	类型	描述	默认值
arguments	列表[ArgumentsParameter]	核心模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

源代码位于 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()
        if 'title' not in argument_schema and self.field_title_should_be_set(argument['schema']):
            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: list[ArgumentsParameter],
    var_args_schema: CoreSchema | None,
) -> JsonSchemaValue

生成匹配定义函数位置参数的模式的 JSON 模式。

参数

名称	类型	描述	默认值
arguments	列表[ArgumentsParameter]	核心模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

源代码位于 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()
        if 'title' not in argument_schema and self.field_title_should_be_set(argument['schema']):
            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'}
    if prefix_items:
        json_schema['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: ArgumentsParameter | ArgumentsV3Parameter,
) -> str

检索参数的名称。

参数

名称	类型	描述	默认值
argument	ArgumentsParameter | ArgumentsV3Parameter	核心模式。	必需

返回

类型	描述
str	参数的名称。

源代码位于 pydantic/json_schema.py

def get_argument_name(self, argument: core_schema.ArgumentsParameter | core_schema.ArgumentsV3Parameter) -> 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

arguments_v3_schema

arguments_v3_schema(
    schema: ArgumentsV3Schema,
) -> JsonSchemaValue

生成匹配定义函数参数的模式的 JSON 模式。

参数

名称	类型	描述	默认值
schema	ArgumentsV3Schema	核心模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

源代码位于 pydantic/json_schema.py

def arguments_v3_schema(self, schema: core_schema.ArgumentsV3Schema) -> 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.
    """
    arguments = schema['arguments_schema']
    properties: dict[str, JsonSchemaValue] = {}
    required: list[str] = []
    for argument in arguments:
        mode = argument.get('mode', 'positional_or_keyword')
        name = self.get_argument_name(argument)
        argument_schema = self.generate_inner(argument['schema']).copy()
        if mode == 'var_args':
            argument_schema = {'type': 'array', 'items': argument_schema}
        elif mode == 'var_kwargs_uniform':
            argument_schema = {'type': 'object', 'additionalProperties': argument_schema}

        argument_schema.setdefault('title', self.get_title_from_name(name))
        properties[name] = argument_schema

        if (
            (mode == 'var_kwargs_unpacked_typed_dict' and 'required' in argument_schema)
            or mode not in {'var_args', 'var_kwargs_uniform', 'var_kwargs_unpacked_typed_dict'}
            and 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
    return json_schema

call_schema

call_schema(schema: CallSchema) -> JsonSchemaValue

生成匹配定义函数调用的模式的 JSON 模式。

参数

名称	类型	描述	默认值
schema	CallSchema	核心模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

源代码位于 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: CustomErrorSchema,
) -> JsonSchemaValue

生成匹配定义自定义错误的模式的 JSON 模式。

参数

名称	类型	描述	默认值
schema	CustomErrorSchema	核心模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

源代码位于 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: JsonSchema) -> JsonSchemaValue

生成匹配定义 JSON 对象的模式的 JSON 模式。

参数

名称	类型	描述	默认值
schema	JsonSchema	核心模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

源代码位于 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: UrlSchema) -> JsonSchemaValue

生成匹配定义 URL 的模式的 JSON 模式。

参数

名称	类型	描述	默认值
schema	UrlSchema	核心模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

源代码位于 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: MultiHostUrlSchema,
) -> JsonSchemaValue

生成匹配定义可在多个主机上使用的 URL 的模式的 JSON 模式。

参数

名称	类型	描述	默认值
schema	MultiHostUrlSchema	核心模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

源代码位于 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: UuidSchema) -> JsonSchemaValue

生成匹配 UUID 的 JSON 模式。

参数

名称	类型	描述	默认值
schema	UuidSchema	核心模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

源代码位于 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: DefinitionsSchema,
) -> JsonSchemaValue

生成匹配定义带有定义的 JSON 对象的模式的 JSON 模式。

参数

名称	类型	描述	默认值
schema	DefinitionsSchema	核心模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

源代码位于 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:  # noqa: PERF203
            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: DefinitionReferenceSchema,
) -> JsonSchemaValue

生成匹配引用定义的模式的 JSON 模式。

参数

名称	类型	描述	默认值
schema	DefinitionReferenceSchema	核心模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

源代码位于 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: (
        SerSchema | IncExSeqSerSchema | IncExDictSerSchema
    ),
) -> JsonSchemaValue | None

生成匹配定义序列化对象的模式的 JSON 模式。

参数

名称	类型	描述	默认值
schema	SerSchema | IncExSeqSerSchema | IncExDictSerSchema	核心模式。	必需

返回

类型	描述
JsonSchemaValue | 无	生成的 JSON 模式。

源代码位于 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

complex_schema

complex_schema(schema: ComplexSchema) -> JsonSchemaValue

生成匹配复数的 JSON 模式。

JSON 没有表示复数的标准方法。复数不是数字类型。在这里，我们按照 Python 定义的规则将复数表示为字符串。例如，'1+2j' 是一个可接受的复数字符串。详细信息可在 Python 的 complex 文档中找到。

参数

名称	类型	描述	默认值
schema	ComplexSchema	核心模式。	必需

返回

类型	描述
JsonSchemaValue	生成的 JSON 模式。

源代码位于 pydantic/json_schema.py

def complex_schema(self, schema: core_schema.ComplexSchema) -> JsonSchemaValue:
    """Generates a JSON schema that matches a complex number.

    JSON has no standard way to represent complex numbers. Complex number is not a numeric
    type. Here we represent complex number as strings following the rule defined by Python.
    For instance, '1+2j' is an accepted complex string. Details can be found in
    [Python's `complex` documentation][complex].

    Args:
        schema: The core schema.

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

get_title_from_name

get_title_from_name(name: str) -> str

从名称中检索标题。

参数

名称	类型	描述	默认值
name	str	要从中检索标题的名称。	必需

返回

类型	描述
str	标题。

源代码位于 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('_', ' ').strip()

field_title_should_be_set

field_title_should_be_set(
    schema: CoreSchemaOrField,
) -> bool

如果具有给定模式的字段应根据字段名称设置标题，则返回 true。

直观地，我们希望这对于不会自行提供标题的模式（例如 int、float、str）返回 true，对于会提供标题的模式（例如 BaseModel 子类）返回 false。

参数

名称	类型	描述	默认值
schema	CoreSchemaOrField	要检查的模式。	必需

返回

类型	描述
bool	如果字段应设置标题，则为 True，否则为 False。

源代码位于 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: str) -> str

规范化名称以用作字典中的键。

参数

名称	类型	描述	默认值
name	str	要规范化的名称。	必需

返回

类型	描述
str	规范化后的名称。

源代码位于 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: CoreModeRef) -> DefsRef

重写此方法以更改从核心引用生成定义键的方式。

参数

名称	类型	描述	默认值
core_mode_ref	CoreModeRef	核心引用。	必需

返回

类型	描述
DefsRef	定义键。

源代码位于 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.rsplit(':', 1)[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) + f'-{mode_title}')
    module_qualname = DefsRef(self.normalize_name(core_ref_no_id))
    module_qualname_mode = DefsRef(f'{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}__{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: CoreRef,
) -> tuple[DefsRef, JsonSchemaValue]

此方法使用一些缓存查找/填充逻辑包装 get_defs_ref 方法，并返回生成的 defs_ref 和将引用正确定义的 JSON 模式。

参数

名称	类型	描述	默认值
core_ref	CoreRef	要获取定义引用的核心引用。	必需

返回

类型	描述
tuple[DefsRef, JsonSchemaValue]	定义引用和将引用它的 JSON 模式的元组。

源代码位于 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: JsonSchemaValue,
) -> JsonSchemaValue

删除与引用模式重复的任何同级键。

参数

名称	类型	描述	默认值
json_schema	JsonSchemaValue	要从中删除冗余同级键的模式。	必需

返回

类型	描述
JsonSchemaValue	已删除冗余同级键的模式。

源代码位于 pydantic/json_schema.py

def handle_ref_overrides(self, json_schema: JsonSchemaValue) -> JsonSchemaValue:
    """Remove any sibling keys that are redundant with the referenced schema.

    Args:
        json_schema: The schema to remove redundant sibling keys from.

    Returns:
        The schema with redundant sibling keys removed.
    """
    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.
            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

    return json_schema

encode_default

encode_default(dft: Any) -> Any

将默认值编码为可 JSON 序列化的值。

这用于编码生成的 JSON 模式中字段的默认值。

参数

名称	类型	描述	默认值
dft	Any	要编码的默认值。	必需

返回

类型	描述
Any	编码后的默认值。

源代码位于 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.
    """
    from .type_adapter import TypeAdapter, _type_has_config

    config = self._config
    try:
        default = (
            dft
            if _type_has_config(type(dft))
            else TypeAdapter(type(dft), config=config.config_dict).dump_python(
                dft, by_alias=self.by_alias, mode='json'
            )
        )
    except PydanticSchemaGenerationError:
        raise pydantic_core.PydanticSerializationError(f'Unable to encode default value {dft}')

    return pydantic_core.to_jsonable_python(
        default, timedelta_mode=config.ser_json_timedelta, bytes_mode=config.ser_json_bytes, by_alias=self.by_alias
    )

update_with_validations

update_with_validations(
    json_schema: JsonSchemaValue,
    core_schema: CoreSchema,
    mapping: dict[str, str],
) -> None

使用提供的映射将 core_schema 中的键转换为 JSON 模式的适当键，从而使用 core_schema 中指定的相应验证更新 json_schema。

参数

名称	类型	描述	默认值
json_schema	JsonSchemaValue	要更新的 JSON 模式。	必需
core_schema	CoreSchema	要从中获取验证的核心模式。	必需
mapping	dict[str, str]	从 core_schema 属性名称到相应 JSON 模式属性名称的映射。	必需

源代码位于 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]

get_json_ref_counts

get_json_ref_counts(
    json_schema: JsonSchemaValue,
) -> dict[JsonRef, int]

获取 json_schema 中任何地方与键 '$ref' 对应的所有值。

源代码位于 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
                try:
                    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])
                except KeyError:
                    if not json_ref.startswith(('http://', 'https://')):
                        raise

            for k, v in schema.items():
                if k == 'examples' and isinstance(v, list):
                    # Skip examples that may contain arbitrary values and references
                    # (see the comment in `_get_all_json_refs` for more details).
                    continue
                _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: JsonSchemaWarningKind, detail: str
) -> None

此方法仅根据 warning_message 方法中的处理发出 PydanticJsonSchemaWarnings。

源代码位于 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: JsonSchemaWarningKind, detail: str
) -> str | None

此方法负责根据需要忽略警告并格式化警告消息。

您可以在 GenerateJsonSchema 的子类中覆盖 ignored_warning_kinds 的值，以修改生成哪些警告。如果需要更多控制，可以重写此方法；只需在不想发出警告的情况下返回 None 即可。

参数

名称	类型	描述	默认值
kind	JsonSchemaWarningKind	要渲染的警告类型。它可以是以下之一： 'skipped-choice'：由于没有有效选择而跳过了选择字段。 'non-serializable-default'：由于不可 JSON 序列化而跳过了默认值。	必需
detail	str	包含警告附加详细信息的字符串。	必需

返回

类型	描述
str | None	格式化的警告消息，如果不需要发出警告，则为 None。

源代码位于 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 数据类

WithJsonSchema(
    json_schema: JsonSchemaValue | None,
    mode: (
        Literal["validation", "serialization"] | None
    ) = None,
)

使用文档

WithJsonSchema 注释

将其作为字段上的注释添加，以覆盖将为该字段生成的（基本）JSON 模式。这提供了一种为在生成 JSON 模式时会引发错误（例如 Callable 或具有 is-instance 核心模式的类型）的类型设置 JSON 模式的方法，而无需创建 pydantic.json_schema.GenerateJsonSchema 的自定义子类。请注意，仍将执行对模式的任何*修改*（例如设置模型字段的标题）。

如果设置了 mode，则仅适用于该模式生成模式，允许您为验证和序列化设置不同的 JSON 模式。

Examples

Examples(
    examples: dict[str, Any],
    mode: (
        Literal["validation", "serialization"] | None
    ) = None,
)

Examples(
    examples: list[Any],
    mode: (
        Literal["validation", "serialization"] | None
    ) = None,
)

Examples(
    examples: dict[str, Any] | list[Any],
    mode: (
        Literal["validation", "serialization"] | None
    ) = None,
)

向 JSON 模式添加示例。

如果 JSON Schema 已经包含示例，则提供的示例将被追加。

如果设置了 mode，则仅适用于该模式生成模式，允许您为验证和序列化添加不同的示例。

源代码位于 pydantic/json_schema.py

def __init__(
    self, examples: dict[str, Any] | list[Any], mode: Literal['validation', 'serialization'] | None = None
) -> None:
    if isinstance(examples, dict):
        warnings.warn(
            'Using a dict for `examples` is deprecated, use a list instead.',
            PydanticDeprecatedSince29,
            stacklevel=2,
        )
    self.examples = examples
    self.mode = mode

SkipJsonSchema 数据类

SkipJsonSchema()

使用文档

SkipJsonSchema 注释

将其作为字段上的注释添加，以跳过为该字段生成 JSON 模式。

示例

from pprint import pprint
from typing import Union

from pydantic import BaseModel
from pydantic.json_schema import SkipJsonSchema

class Model(BaseModel):
    a: Union[int, None] = None  # (1)!
    b: Union[int, SkipJsonSchema[None]] = None  # (2)!
    c: SkipJsonSchema[Union[int, None]] = None  # (3)!

pprint(Model.model_json_schema())
'''
{
    'properties': {
        'a': {
            'anyOf': [
                {'type': 'integer'},
                {'type': 'null'}
            ],
            'default': None,
            'title': 'A'
        },
        'b': {
            'default': None,
            'title': 'B',
            'type': 'integer'
        }
    },
    'title': 'Model',
    'type': 'object'
}
'''

1. 整数和 null 类型都包含在 a 的模式中。
2. 整数类型是 b 的模式中唯一包含的类型。
3. c 字段的整个内容从模式中省略。

model_json_schema

model_json_schema(
    cls: type[BaseModel] | type[PydanticDataclass],
    by_alias: bool = True,
    ref_template: str = DEFAULT_REF_TEMPLATE,
    union_format: Literal[
        "any_of", "primitive_type_array"
    ] = "any_of",
    schema_generator: type[
        GenerateJsonSchema
    ] = GenerateJsonSchema,
    mode: JsonSchemaMode = "validation",
) -> dict[str, Any]

用于为模型生成 JSON Schema 的实用函数。

参数

名称	类型	描述	默认值
cls	类型[BaseModel] | 类型[PydanticDataclass]	要生成 JSON Schema 的模型类。	必需
by_alias	bool	如果为 True（默认值），字段将根据其别名序列化。如果为 False，字段将根据其属性名称序列化。	True
ref_template	str	用于生成 JSON Schema 引用的模板。	DEFAULT_REF_TEMPLATE
union_format	Literal['any_of', 'primitive_type_array']	组合联合模式时使用的格式。可以是以下之一： 'any_of': 使用 anyOf 关键字组合模式（默认）。 'primitive_type_array': 使用 type 关键字作为字符串数组，包含组合中的每种类型。如果任何模式不是原始类型（string、boolean、null、integer 或 number）或包含约束/元数据，则回退到 any_of。	'any_of'
schema_generator	类型[GenerateJsonSchema]	用于生成 JSON Schema 的类。	GenerateJsonSchema
mode	JsonSchemaMode	用于生成 JSON Schema 的模式。它可以是以下之一： 'validation'：生成用于验证数据的 JSON Schema。 'serialization'：生成用于序列化数据的 JSON Schema。	'validation'

返回

类型	描述
dict[Any, Any]	生成的 JSON Schema。

源代码位于 pydantic/json_schema.py

def model_json_schema(
    cls: type[BaseModel] | type[PydanticDataclass],
    by_alias: bool = True,
    ref_template: str = DEFAULT_REF_TEMPLATE,
    union_format: Literal['any_of', 'primitive_type_array'] = 'any_of',
    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.
        union_format: The format to use when combining schemas from unions together. Can be one of:

            - `'any_of'`: Use the [`anyOf`](https://json-schema.fullstack.org.cn/understanding-json-schema/reference/combining#anyOf)
              keyword to combine schemas (the default).
            - `'primitive_type_array'`: Use the [`type`](https://json-schema.fullstack.org.cn/understanding-json-schema/reference/type)
              keyword as an array of strings, containing each type of the combination. If any of the schemas is not a primitive
              type (`string`, `boolean`, `null`, `integer` or `number`) or contains constraints/metadata, falls back to
              `any_of`.
        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.
    """
    from .main import BaseModel

    schema_generator_instance = schema_generator(
        by_alias=by_alias, ref_template=ref_template, union_format=union_format
    )

    if isinstance(cls.__pydantic_core_schema__, _mock_val_ser.MockCoreSchema):
        cls.__pydantic_core_schema__.rebuild()

    if cls is BaseModel:
        raise AttributeError('model_json_schema() must be called on a subclass of BaseModel, not BaseModel itself.')

    assert not isinstance(cls.__pydantic_core_schema__, _mock_val_ser.MockCoreSchema), 'this is a bug! please report it'
    return schema_generator_instance.generate(cls.__pydantic_core_schema__, mode=mode)

models_json_schema

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,
    union_format: Literal[
        "any_of", "primitive_type_array"
    ] = "any_of",
    schema_generator: type[
        GenerateJsonSchema
    ] = GenerateJsonSchema
) -> tuple[
    dict[
        tuple[
            type[BaseModel] | type[PydanticDataclass],
            JsonSchemaMode,
        ],
        JsonSchemaValue,
    ],
    JsonSchemaValue,
]

用于为多个模型生成 JSON Schema 的实用函数。

参数

名称	类型	描述	默认值
models	序列[元组[类型[BaseModel] | 类型[PydanticDataclass], JsonSchemaMode]]	形式为 (model, mode) 的元组序列。	必需
by_alias	bool	字段别名是否应在生成的 JSON Schema 中用作键。	True
title	str | None	生成的 JSON Schema 的标题。	None
描述	str | None	生成的 JSON Schema 的描述。	None
ref_template	str	用于生成 JSON Schema 引用的引用模板。	DEFAULT_REF_TEMPLATE
union_format	Literal['any_of', 'primitive_type_array']	组合联合模式时使用的格式。可以是以下之一： 'any_of': 使用 anyOf 关键字组合模式（默认）。 'primitive_type_array': 使用 type 关键字作为字符串数组，包含组合中的每种类型。如果任何模式不是原始类型（string、boolean、null、integer 或 number）或包含约束/元数据，则回退到 any_of。	'any_of'
schema_generator	类型[GenerateJsonSchema]	用于生成 JSON Schema 的模式生成器。	GenerateJsonSchema

返回

类型	描述
tuple[dict[tuple[类型[BaseModel] | 类型[PydanticDataclass], JsonSchemaMode], JsonSchemaValue], JsonSchemaValue]	一个元组，其中： - 第一个元素是一个字典，其键是 JSON 模式键类型和 JSON 模式的元组，其值是与该输入对对应的 JSON 模式。（这些模式可能包含对第二个返回元素中定义的定义的 JsonRef 引用。） - 第二个元素是一个 JSON 模式，其中包含第一个返回元素中引用的所有定义，以及可选的标题和描述键。

源代码位于 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,
    union_format: Literal['any_of', 'primitive_type_array'] = 'any_of',
    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.
        union_format: The format to use when combining schemas from unions together. Can be one of:

            - `'any_of'`: Use the [`anyOf`](https://json-schema.fullstack.org.cn/understanding-json-schema/reference/combining#anyOf)
              keyword to combine schemas (the default).
            - `'primitive_type_array'`: Use the [`type`](https://json-schema.fullstack.org.cn/understanding-json-schema/reference/type)
              keyword as an array of strings, containing each type of the combination. If any of the schemas is not a primitive
              type (`string`, `boolean`, `null`, `integer` or `number`) or contains constraints/metadata, falls back to
              `any_of`.
        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.
    """
    for cls, _ in models:
        if isinstance(cls.__pydantic_core_schema__, _mock_val_ser.MockCoreSchema):
            cls.__pydantic_core_schema__.rebuild()

    instance = schema_generator(by_alias=by_alias, ref_template=ref_template, union_format=union_format)
    inputs: list[tuple[type[BaseModel] | type[PydanticDataclass], JsonSchemaMode, CoreSchema]] = [
        (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