将 JSON 转换为 Python Pydantic model!

输入 JSON,即可生成包含嵌套对象的 Python Pydantic model 代码!支持 Pydantic v2 BaseModel, dataclass, FastAPI。SQLAlchemy 请在上方标签中选择。
JSON
结果
 

将 JSON 转换为 Python Pydantic model!

这个转换器把 JSON 结构转换成 Pydantic v2 的 BaseModel 类,或标准库的 @dataclass 代码。字段名会按 Python 风格改写成 snake_case,每个嵌套对象都有自己的类。

定义 FastAPI 的请求和响应 schema、给用 requests 或 httpx 获取的数据加上类型提示,或者整理那些靠字符串 key 在 dict 里层层翻找的 ETL 和爬虫脚本时,都可以用它。

使用方法

  1. 粘贴要建模的 JSON。
  2. 在 类型名 中输入顶层模型的名称(例如 Forecast)。
  3. 在 风格 中,需要校验和别名时选 Pydantic (v2),想要无依赖的模型时选 dataclass。
  4. 把结果复制到 models.py 之类的模块中。风格和类型名会保存在 URL 中。

示例

输入 (JSON)
{
  "city": "Seoul",
  "updatedAt": "2024-05-01T09:00:00+09:00",
  "current": { "temp": 18.5, "humidity": 40 },
  "hourly": [
    { "hour": 10, "temp": 19, "rain_mm": 0 },
    { "hour": 11, "temp": 20.5, "rain_mm": 0.4, "alert": "shower" }
  ]
}
输出 (Python · Pydantic v2)
from __future__ import annotations

from pydantic import BaseModel, ConfigDict, Field


class Hourly(BaseModel):
    hour: int
    temp: float
    rain_mm: float
    alert: str | None = None


class Current(BaseModel):
    temp: float
    humidity: int


class Forecast(BaseModel):
    model_config = ConfigDict(populate_by_name=True)

    city: str
    updated_at: str = Field(alias="updatedAt")
    current: Current
    hourly: list[Hourly]

updatedAt 变成 updated_at 字段,并通过 Field(alias="updatedAt") 与原始 key 对应。在 hourly 中,temp 混有整数和小数,所以变成 float;只在第二项中出现的 alert 是 str | None = None。类按子类在前的顺序输出。

支持的功能

  • Pydantic v2:改名的字段使用 Field(alias=...),model_config = ConfigDict(populate_by_name=True) 让你也能用 Python 名称赋值。
  • dataclass:没有默认值的字段会被移到 = None 字段之前,以避免 TypeError: non-default argument follows default argument;原始 key 以 # JSON: "updatedAt" 注释的形式保留。
  • 类型:str、int、float、bool、list[...],混合类型的值为 Any。
  • 在部分元素中缺失或包含 null 的字段变成 X | None = None。
  • class、from、type 等 Python 关键字会加上后缀下划线(class_)。
  • 包含 from __future__ import annotations,类之间可以互相引用而不受顺序限制。
  • 顶层为数组时生成 Root = list[RootItem] 这样的别名。

使用场景

FastAPI 的响应模型和请求体

根据与前端约定好的 JSON 生成 BaseModel,用在 response_model= 中或作为接口参数,OpenAPI 文档也会自动随之更新。

校验第三方 API 的响应

把调用包在 Forecast.model_validate(resp.json()) 中,当服务商改变某个字段的类型时,ValidationError 会准确指出出问题的字段路径。

替换脚本中的 dict 查找

把 data["current"]["temp"] 改成 forecast.current.temp,就能获得编辑器补全,mypy 或 pyright 也能检查代码。

注意事项与限制

  • @dataclass 不会把嵌套的 dict 转换成对象。执行 Forecast(**data) 后,current 仍然是 dict;如果需要嵌套转换,请使用 Pydantic 或 dacite 之类的辅助库。
  • 在 Pydantic 中要以原始 JSON key(updatedAt)序列化回去,请调用 model_dump(by_alias=True) 或 model_dump_json(by_alias=True)。
  • 输出使用 str | None 语法,所以 Pydantic 模型要求 Python 3.10 或更高版本。
  • 日期和时间字符串输出为 str。在 Pydantic 中,只要把注解改成 datetime 就能解析 ISO 8601 值。
  • 不会生成 Pydantic v1 的写法(class Config、parse_obj)。

常见问题

populate_by_name=True 有什么用?

默认情况下,带别名的字段只接受别名(updatedAt)作为输入。开启这个设置后,也可以写 Forecast(updated_at=...),在测试中很方便。

可选字段我更喜欢写成 Optional[str]。

str | None 和 Optional[str] 含义相同。如果需要兼容 Python 3.9,请从 typing 导入 Optional 并替换注解。

能输出 TypedDict 或 attrs 类吗?

支持的风格是 Pydantic v2 和 dataclass。如果需要 TypedDict 或 @attrs.define 类,dataclass 的字段列表可以直接搬过去。

key 已经是 snake_case 时还会加别名吗?

不会。Python 名称与原始 key 相同时,不会输出 Field(alias=...) 或 ConfigDict,得到的是 rain_mm: float 这样简单的行。