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

本文详解如何使用 skipjsonschema 精准排除 pydantic 模型字段在 model_json_schema() 中的输出，避免 field(exclude=true) 等误用方式导致 schema 仍残留字段的问题。

本文详解如何使用 skipjsonschema 精准排除 pydantic 模型字段在 model_json_schema() 中的输出，避免 field(exclude=true) 等误用方式导致 schema 仍残留字段的问题。

在 Pydantic（尤其是 v2.x）中，开发者常混淆「序列化排除」与「Schema 排除」两个概念：

• Field(exclude=True) 或 model_dump(exclude=...) 仅影响运行时数据序列化（如 model_dump() / model_json()），不影响 JSON Schema 生成；
• Field(exclude_schema=True) 是无效参数——Pydantic v2 并未实现该参数，它会被静默忽略，因此字段仍会出现在 model_json_schema() 输出中（正如问题示例所示）。

✅ 正确方案：使用 pydantic.json_schema.SkipJsonSchema 类型包装器。

SkipJsonSchema[T] 是 Pydantic 官方提供的类型注解工具，用于声明性地告知 JSON Schema 生成器：此字段不应出现在任何 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):
    # ✅ 此字段将完全从 JSON Schema 中消失
    items_dict: dict[str, MyItem] = SkipJsonSchema[dict[str, MyItem]]

    # 其他正常字段照常参与 schema 生成
    title: str
    version: int = 1

# 验证效果
schema = MyObject.model_json_schema()
print(json.dumps(schema, indent=2))

输出 Schema 将不包含 items_dict 字段：

{
  "properties": {
    "title": {
      "title": "Title",
      "type": "string"
    },
    "version": {
      "default": 1,
      "title": "Version",
      "type": "integer"
    }
  },
  "required": ["title"],
  "title": "MyObject",
  "type": "object"
}

⚠️ 注意事项与最佳实践

• 仅作用于 Schema，不影响模型行为：SkipJsonSchema 不改变字段的验证、默认值、赋值逻辑或序列化行为。若还需运行时排除该字段，请额外配合 exclude 参数：

  

  畅图

  AI可视化工具

  下载

  # 同时排除 schema 和序列化结果
  internal_cache: SkipJsonSchema[dict] = Field(default_factory=dict, exclude=True)

• 不可与 Field(...) 混合用于同一字段：SkipJsonSchema 是类型注解层级的声明，应直接用于字段类型，而非 Field() 的参数。以下写法错误：

  # ❌ 错误：SkipJsonSchema 是类型，不是 Field 参数
  bad_field: str = Field(..., default=SkipJsonSchema[str])

• 支持嵌套与泛型：可安全用于复杂类型，如 SkipJsonSchema[List[MyModel]]、SkipJsonSchema[Optional[Dict[str, Any]]] 等。

• 文档兼容性：生成的 OpenAPI/Swagger 文档（如 FastAPI）会自动尊重 SkipJsonSchema，确保 API 文档不暴露内部字段。

✅ 总结

牢记：Schema 排除 ≠ 序列化排除。SkipJsonSchema 是 Pydantic v2 中专为 Schema 场景设计的精准控制机制，是解决“字段仍在 schema 中出现”问题的唯一可靠方案。