本文详解如何使用 skipjsonschema 类型注解，精准、可靠地将 pydantic 模型中的特定字段从生成的 json schema 中完全移除，避免 field(exclude=true) 等误用方式导致的 schema 泄露问题。
本文详解如何使用 skipjsonschema 类型注解，精准、可靠地将 pydantic 模型中的特定字段从生成的 json schema 中完全移除，避免 field(exclude=true) 等误用方式导致的 schema 泄露问题。
在 Pydantic v2 中，开发者常误以为 Field(exclude=True) 或 Field(exclude_schema=True) 能让字段彻底“消失”于 JSON Schema —— 实际上，这些参数仅影响序列化行为（如 model_dump()）或文档生成逻辑，而对 model_json_schema() 的输出无任何作用。正如问题中所示，items_dict 字段仍完整出现在 schema 的 properties 中，甚至附带了无效的 "exclude_schema": true 字段（该键本身不属于 OpenAPI 规范，会被忽略）。
✅ 正确且唯一推荐的方式是：使用 pydantic.json_schema.SkipJsonSchema 作为类型注解包装器。它向 schema 生成器明确声明：“此字段不应出现在任何 JSON Schema 输出中”，从而实现真正的 schema 级别排除。
✅ 正确用法示例
from pydantic.json_schema import SkipJsonSchema
from pydantic import BaseModel
import json
class MyItem(BaseModel):
name: str
data: str
class MyObject(BaseModel):
visible_in_schema: str
# ✅ 完全从 schema 中剔除：不生成 properties、不参与 required 列表、不污染 $defs
internal_cache: SkipJsonSchema[dict[str, MyItem]]
@property
def items_list(self) -> list[MyItem]:
return list(self.internal_cache.values()) if self.internal_cache else []
# 构造实例（internal_cache 仍可正常赋值与使用）
obj = MyObject(
visible_in_schema="public",
internal_cache={"a": MyItem(name="item1", data="data1")}
)
# 查看生成的 JSON Schema
print(json.dumps(obj.model_json_schema(), indent=2))输出 Schema 将完全不包含 internal_cache 字段：
{
"properties": {
"visible_in_schema": {
"title": "Visible In Schema",
"type": "string"
}
},
"required": ["visible_in_schema"],
"title": "MyObject",
"type": "object"
}⚠️ 注意事项与最佳实践
- SkipJsonSchema[T] 不影响运行时行为：字段仍可被赋值、验证（若含校验逻辑）、访问，仅 schema 生成阶段被跳过；
- 支持嵌套与泛型：SkipJsonSchema[list[MyItem]]、SkipJsonSchema[Optional[Dict[str, int]]] 均有效；
- 不可与 Field(default=...) 等参数混用在同个注解中（类型注解应为纯 SkipJsonSchema[T]），默认值需在字段赋值时处理；
- 若需同时排除序列化 和 schema，应组合使用：
hidden_field: SkipJsonSchema[str] = Field(..., exclude=True) # schema + dump 双重排除
- SkipJsonSchema 自 Pydantic v2.4 起稳定可用，确保你的版本 ≥ 2.4（推荐使用最新版）。
✅ 总结
永远不要依赖 Field(exclude_schema=True) —— 它是无效的遗留参数。要实现字段的JSON Schema 级别排除，唯一可靠、语义清晰、官方支持的方式就是 SkipJsonSchema[T]。它轻量、类型安全、零副作用，是构建干净、专业 API 文档与类型定义的关键工具。
