本文详解如何在 Pydantic（v2+）中精准定义并验证符合 JSON 序列化规范的嵌套字典结构，推荐使用内置 JsonValue 类型替代手动递归注解，避免循环引用错误，并确保类型安全与序列化兼容性。
本文详解如何在 pydantic（v2+）中精准定义并 validate 符合 json 序列化规范的嵌套字典结构，推荐使用内置 jsonvalue 类型替代手动递归注解，避免循环引用错误，并确保类型安全与序列化兼容性。
在构建 API 请求体、配置解析或第三方数据校验场景中，我们常需确保某个字段是「真正可无损转为 JSON 的 Python 值」——即仅包含 str、int、float、bool、None、list（元素也为 JSON 兼容值）、dict（键为 str，值为 JSON 兼容值）。此时，简单使用 Dict[str, Any] 过于宽泛（允许 datetime、UUID、自定义类等非 JSON 类型），而 Json[str] 又仅接受 JSON 字符串（需额外 json.loads 解析），均不符合需求。
Pydantic v2 起原生提供了 JsonValue 类型（位于 pydantic.types），它正是为此设计的递归 JSON 兼容值类型别名，定义如下：
from pydantic.types import JsonValue # 等价于： # JsonValue = Union[ # str, int, float, bool, None, # List['JsonValue'], # Dict[str, 'JsonValue'] # ]
该类型严格限定所有嵌套层级的值均为 JSON 标准可序列化内容，且完全支持 Pydantic 的自动验证、类型转换与错误提示。
✅ 正确用法：直接使用 JsonValue 或组合 Dict[str, JsonValue]
若字段应为任意 JSON 兼容值（如 { "data": [1, "hello", {"nested": true}] }），直接注解为 JsonValue 即可：
from pydantic import BaseModel, ValidationError
from pydantic.types import JsonValue
class Payload(BaseModel):
content: JsonValue
# ✅ 合法输入（全部可被 json.dumps() 序列化）
valid = Payload(content={"users": [{"id": 1, "active": True}], "count": 3.14})
# ❌ 非法输入：包含不可序列化类型
try:
Payload(content={"timestamp": datetime.now()})
except ValidationError as e:
print(e)
# > 1 validation error for Payload
# > content.timestamp
# > Input should be a valid string, integer, float, boolean or None [type=invalid_type, ...]若你明确要求字段必须是字典类型（即 JSON object），而非任意 JSON 值（如不能是字符串或列表），则应使用 Dict[str, JsonValue]：
from typing import Dict
from pydantic.types import JsonValue
class Config(BaseModel):
metadata: Dict[str, JsonValue] # 强制为 dict，且所有 value 必须 JSON 兼容
# ✅ 合法
Config(metadata={"version": "1.0", "features": ["auth", "logging"]})
# ❌ 错误：不是 dict
Config(metadata="not-a-dict") # → validation error
# ❌ 错误：dict 中含非法值
Config(metadata={"error": set([1, 2])}) # → validation error (set 不可 JSON 序列化)⚠️ 注意事项与最佳实践
- 不要手动定义递归类型：如问题中尝试的 Union[Dict[str, 'Json'], ...] 会因前向引用未解析导致 RecursionError 或 NameError；JsonValue 已由 Pydantic 内部妥善处理。
- JsonValue ≠ Json[str]：前者表示 已解析的 Python 值（类型为 dict/list 等），后者表示 原始 JSON 字符串（类型为 str，需 json.loads 才能使用）。
- 性能与序列化：JsonValue 字段在模型实例化时即完成深度验证，确保 .model_dump() 或 .model_dump_json() 总能成功输出标准 JSON。
- 兼容性：JsonValue 自 Pydantic v2.5+ 稳定可用；旧版本可临时使用 Any + 自定义 validator，但不推荐。
✅ 总结
当需要表达“一个结构合法、可直接 json.dumps() 的嵌套字典（或更广义的 JSON 值）”时，请始终优先选用 pydantic.types.JsonValue。它语义清晰、开箱即用、零配置验证，并与 Pydantic 的整个类型系统无缝集成——这是 Pydantic 对 JSON Schema 兼容性承诺的专业实现，也是现代 Python 数据验证的最佳实践。
