Pydantic中WithJsonSchema与默认值结合时的JSON Schema生成问题分析

在Pydantic V2版本中，开发者发现了一个关于WithJsonSchema注解与字段默认值结合使用时JSON Schema生成异常的问题。这个问题涉及到Pydantic核心的JSON Schema生成机制，值得深入探讨其技术原理和解决方案。

问题现象

当开发者使用Annotated类型结合WithJsonSchema定义字段，并为该字段设置默认值时，生成的JSON Schema会出现预期之外的行为。具体表现为：

1. 对于非可选字段，默认值会被正确添加但WithJsonSchema指定的模式会被忽略
2. 对于可选字段，默认值会以奇怪的方式出现在anyOf结构中

技术原理分析

Pydantic的JSON Schema生成机制基于核心模式(core schema)工作。当字段有默认值时，核心模式会使用"default"类型，并将原始模式包装在"schema"键下。

在生成JSON Schema时，Pydantic会先处理内部模式(此时WithJsonSchema会生效)，然后再添加默认值等额外信息。这种分步处理导致了WithJsonSchema的覆盖效果被部分破坏。

设计考量

WithJsonSchema的设计初衷是提供对JSON Schema生成过程的完全控制。按照文档示例，开发者需要显式指定所有必要的Schema属性(如"type")。然而实际实现中，默认值等信息的处理打破了这种完全控制。

解决方案探讨

目前社区提出了几种可能的解决方案：

1. 浅拷贝/深拷贝方案：在处理过程中创建模式对象的副本，避免意外修改
2. 特殊处理WithJsonSchema：在JSON Schema生成时特别处理这类注解
3. 调整设计理念：将WithJsonSchema视为"预处理"阶段，而非完全覆盖

从实现复杂度和向后兼容性考虑，第一种方案可能是最稳妥的选择。第二种方案虽然理论上更干净，但会显著增加代码复杂度和维护成本。

最佳实践建议

对于开发者而言，在使用WithJsonSchema时应当：

1. 显式指定所有必要的Schema属性
2. 注意默认值可能带来的Schema变化
3. 对于复杂场景，考虑使用json_schema_extra进行后处理

Pydantic团队需要权衡设计一致性和实现复杂度，决定最终的修复方向。无论采用哪种方案，理解这一机制有助于开发者更好地利用Pydantic的Schema生成能力。