如何在 Pydantic v2 中彻底排除字段的 JSON Schema 生成

本文详解如何使用 skipjsonschema 类型注解，从 pydantic 模型的 json schema 中完全移除指定字段，避免其出现在 $defs 或 properties 中，适用于内部状态、临时计算字段等无需暴露给 api 文档或客户端的场景。

本文详解如何使用 skipjsonschema 类型注解，从 pydantic 模型的 json schema 中完全移除指定字段，避免其出现在 $defs 或 properties 中，适用于内部状态、临时计算字段等无需暴露给 api 文档或客户端的场景。

在 Pydantic v2 中，仅靠 Field(exclude=True) 或 Field(exclude_schema=True) 无法真正从生成的 JSON Schema 中移除字段——正如你在示例中观察到的：items_dict 字段仍保留在 properties 中，且 exclude_schema=true 仅是元数据标记，并非标准 JSON Schema 属性，对大多数 OpenAPI 工具链（如 Swagger UI、Redoc）无效。

✅ 正确且推荐的方式是使用 pydantic.json_schema.SkipJsonSchema 类型包装器。它是一个类型注解级别的“指令”，告诉 Pydantic 在构建 JSON Schema 时完全跳过该字段的模式定义，既不生成其属性描述，也不将其加入 required 列表或 $defs 引用。

✅ 正确用法示例

from pydantic.json_schema import SkipJsonSchema
from pydantic import BaseModel
import json

class MyItem(BaseModel):
    name: str
    data: str

class MyObject(BaseModel):
    # ✅ 该字段将完全不出现在 model_json_schema() 输出中
    items_dict: SkipJsonSchema[dict[str, MyItem]]

    # 其他正常字段仍可参与序列化与校验
    id: int
    title: str

# 验证 Schema 是否已排除
schema = MyObject.model_json_schema()
print(json.dumps(schema, indent=2))

输出 Schema 将不含 items_dict 字段的任何痕迹：

EasySite

零代码AI网站开发工具

下载

{
  "$defs": {
    "MyItem": {
      "properties": {
        "name": { "title": "Name", "type": "string" },
        "data": { "title": "Data", "type": "string" }
      },
      "required": ["name", "data"],
      "title": "MyItem",
      "type": "object"
    }
  },
  "properties": {
    "id": { "title": "Id", "type": "integer" },
    "title": { "title": "Title", "type": "string" }
  },
  "required": ["id", "title"],
  "title": "MyObject",
  "type": "object"
}

? 注意：SkipJsonSchema[T] 仅影响 JSON Schema 生成（如 model_json_schema()、FastAPI 的 OpenAPI 文档），不影响模型实例化、验证或 .model_dump() 序列化行为。若你还希望该字段在 .model_dump() 中被排除，请额外配合 Field(exclude=True)：

items_dict: SkipJsonSchema[dict[str, MyItem]] = Field(default_factory=dict, exclude=True)

⚠️ 常见误区与注意事项

• ❌ Field(exclude_schema=True) 是无效的：Pydantic v2 不识别该参数，它会被静默忽略（你的原始代码中该参数未生效）。
• ❌ Field(exclude=True) 只影响 .model_dump() 和 .model_dump_json()，对 Schema 无影响。
• ✅ SkipJsonSchema 必须作为类型注解的一部分（即 field_name: SkipJsonSchema[Type]），不能仅用于 Field() 参数。
• ✅ 支持嵌套和泛型：SkipJsonSchema[List[MyItem]]、SkipJsonSchema[Optional[str]] 均有效。
• ? 在 FastAPI 中，此方式可确保字段不会出现在自动生成的 Swagger/OpenAPI 文档中，提升 API 文档的专业性与安全性。

✅ 总结

掌握 SkipJsonSchema 是构建清晰、安全、专业 Pydantic API 的关键实践之一——让 Schema 真实反映外部契约，而非内部实现细节。