Pydantic中自定义类型的JSON Schema序列化问题解析

在Pydantic V2版本中，开发者在使用自定义类型时可能会遇到JSON Schema生成时默认值序列化的问题。本文将通过一个典型场景，深入分析问题原因并提供解决方案。

问题场景

假设我们有一个外部定义的Voltage类，无法修改其源代码。我们希望在Pydantic模型中使用这个类，并为其生成正确的JSON Schema。

class Voltage:
    def __init__(self, value: float):
        self.__value = value

    def get(self) -> float:
        return self.__value

    def __str__(self):
        return f"{self.__value}V"

初步实现方案

按照Pydantic文档的建议，我们使用Annotated来包装这个类，添加序列化器和验证器：

PydanticVoltage = Annotated[
    Voltage,
    pydantic.WithJsonSchema({"type": "number"}),
    pydantic.PlainSerializer(lambda v: v.get()),
    pydantic.BeforeValidator(lambda v: Voltage(v)),
]

class MyClass(pydantic.BaseModel):
    model_config = pydantic.ConfigDict(arbitrary_types_allowed=True)
    voltage: PydanticVoltage = Voltage(17)

遇到的问题

此时生成JSON Schema会出现警告："Default value 0V is not JSON serializable; excluding default from JSON schema"。这表明虽然我们定义了序列化器，但在生成Schema时并未被正确应用。

问题根源

经过分析，发现问题的关键在于序列化器的位置。Pydantic的JSON Schema生成器在默认情况下不会自动应用内层定义的序列化器。

解决方案

临时解决方案

将PlainSerializer移到最外层可以解决当前问题：

PydanticVoltage = Annotated[
    Voltage,
    pydantic.WithJsonSchema({"type": "number"}),
    pydantic.BeforeValidator(lambda v: Voltage(v)),
    pydantic.PlainSerializer(lambda v: v.get()),
]

未来版本改进

在Pydantic 2.12版本中，这个问题将得到修复。对于需要验证模式的情况，开发者需要显式指定json_schema_input_type参数。

最佳实践建议

1. 对于自定义类型的序列化，始终将序列化器放在最外层
2. 明确区分验证模式和序列化模式的需求
3. 对于复杂类型，考虑实现__get_pydantic_core_schema__方法

总结

Pydantic在处理自定义类型的JSON Schema生成时，需要注意序列化器的应用顺序。了解这一机制有助于开发者更好地设计模型和类型适配器，避免潜在的问题。随着Pydantic的版本更新，这一体验将会更加完善。