pydantic模型转json schema时字段缺失需用field显式声明description/examples，union/optional生成的nullable需自定义generatejsonschema处理；校验不一致因jsonschema仅做结构检查，不执行pydantic运行时逻辑，关键路径应使用model_validate()。
pydantic 模型转 jsonschema 时字段缺失或类型错乱
直接调用 model.json_schema() 通常能生成可用 schema，但常见字段如 description、examples、nullable 不会自动出现，除非你在字段注解里显式加了 Field(..., description="...")。更隐蔽的问题是：如果用了 Union[str, None] 或 Optional[str]，生成的 schema 默认带 "type": ["string", "null"]，但某些 JSON Schema 验证器（比如旧版 jsonschema Python 库）不认 "null" 类型，只认 "type": "string" + "nullable": true（需启用 OpenAPI 3.1 兼容模式）。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 用
model.json_schema(schema_generator=GenerateJsonSchema)并传入自定义GenerateJsonSchema子类，覆盖_generate_nullable_schema方法来统一输出"nullable": true - 若只需快速兼容老验证器，加参数
mode="validation"（默认值），避免意外触发 OpenAPI 专用字段 - 字段级文档必须靠
Field(description=...)，光写 docstring 不生效
用 jsonschema.validate() 校验 pydantic 生成的 schema 时抛 ValidationError: Additional properties are not allowed
这是典型 schema 和数据结构不匹配——不是校验逻辑错了，而是你拿 pydantic 模型生成的 schema 去校验一个“多字段”的原始 dict，而该模型本身没声明这些字段（即没设 extra="allow"）。pydantic 默认拒绝未知字段，生成的 schema 也带 "additionalProperties": false，但外部数据可能带调试字段、时间戳、trace_id 等。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 校验前先确认数据是否真的该被模型完全覆盖；如果不是，要么改模型（加
Config.extra = "allow"），要么在校验前用dict.keys() & set(model.__fields__.keys())过滤字段 - 别依赖
jsonschema.validate()的报错信息反推 pydantic 行为——它不会告诉你哪个字段触发了additionalProperties，只会笼统报错 - 若必须保留严格校验，用
model.model_validate(data)替代纯 jsonschema 校验，错误位置和原因更准
嵌套模型 + 循环引用导致 RecursionError 或 schema 无限展开
pydantic v2 对循环引用支持有限：比如 A 包含 B 字段，B 又包含 A 字段，调用 A.json_schema() 会直接爆栈。即使加了 from __future__ import annotations 和字符串前向引用（"A"），生成器仍可能在解析时展开过深。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 优先用
pydantic.BaseModel.model_rebuild()显式重建模型，尤其在模块间交叉引用后 - 对已知循环结构，手动用
JsonSchemaValue注入占位 schema，例如：field: "A" = Field(default=None, json_schema_extra={"$ref": "#/definitions/A"})，再单独在顶层json_schema()["definitions"]里补定义 - 避免在
Field(default_factory=...)里动态构造嵌套模型实例，这会让 schema 生成器误判为需递归展开
校验结果和 pydantic 报错不一致，比如 jsonschema 说 ok，但 model.model_validate() 报 value_error.missing
根本原因是两者校验层级不同：jsonschema 只做结构+类型检查，不执行 pydantic 的运行时逻辑，比如 BeforeValidator、default_factory、alias 映射、strict=True 强制类型等。一个字段在 schema 里是 "type": "string"，但 pydantic 实际要求它必须是 str（不能是 int 转来的），jsonschema 不管这个。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 不要把 jsonschema 校验当作 pydantic 校验的替代品，它只是前置过滤；关键路径必须走
model_validate() - 如果要用 jsonschema 做快速预筛，确保模型里没用
before_validator、after_validator、default_factory这类无法映射到 schema 的特性 - 检查
Config.strict是否开启——开启后 pydantic 会拒绝隐式类型转换，而 jsonschema 默认允许数字字符串过 string 类型校验
最麻烦的其实是混合使用场景：前端用 jsonschema 做表单生成，后端用 pydantic 做解析。这时候 schema 必须手工对齐 strict 模式、nullable 处理、日期格式（date vs string with format: date），差一点就丢数据或报错。
