JSON 转 Zod Schema

从 JSON 数据即时生成 Zod 验证 schema,支持嵌套对象、数组、nullable 字段和可选属性。在浏览器中运行。

  • 在浏览器中处理
  • 工具不会把输入上传到 ZeroTool 服务器
  • 免费 · 无需注册
设置 Schema 常量和推断类型使用的名称。留空时使用 Root。修改名称后点击生成 Zod Schema 应用。
为生成的 z.object Schema 添加 .strict(),让 Zod 拒绝多余字段。点击生成 Zod Schema 应用此选项。
立即按当前 JSON、根名和严格模式生成。也可按 Ctrl/⌘+Enter 生成。
用含嵌套对象、数组和 null 的示例替换输入,再按当前根名和严格模式生成。
清空 JSON、输出和状态,保留根名及严格模式。在工具内按 Ctrl/⌘+L 还会清空根名。
输入合法 JSON。停止输入 300 毫秒后自动生成;JSON 无效时清空输出。根值可以是对象、数组或基本类型。
Zod Schema 输出
复制当前显示的完整 TypeScript 代码,包括 Zod 导入、Schema 和推断类型。输出为空时不复制。

输入 JSON 或载入示例以生成 Zod Schema。

示例、说明与常见问题 带实际输出的示例、与同类工具的差别,以及常见问题。

输出是什么样子

输出是一段可以直接粘进 .ts 文件的代码:第一行 import { z } from "zod";,中间是 const 名称Schema = …;,最后是 export type 名称 = z.infer<typeof 名称Schema>;。schema 常量没有 export,别的模块要用时自己加上。名称取自「根 Schema 名称」,留空时用 Root。

示例:中文键名的订单

低代码平台或报表导出的 JSON 常用中文键名。根名称填 Order:

{"订单号":"A-1001","收货地址":{"省份":"浙江省","城市":"杭州市"},"商品列表":[{"名称":"龙井茶","数量":2,"单价":128.5},{"名称":"茶具","数量":1,"单价":299,"备注":"礼盒装"}]}

输出:

import { z } from "zod";

const OrderSchema = z.object({
  "订单号": z.string(),
  "收货地址": z.object({
    "省份": z.string(),
    "城市": z.string(),
  }),
  "商品列表": z.array(z.object({
    "名称": z.string(),
    "数量": z.number().int(),
    "单价": z.union([z.number(), z.number().int()]),
    "备注": z.string().optional(),
  })),
});

export type Order = z.infer<typeof OrderSchema>;

三处值得注意:

  • 中文键名一律加引号,这是合法的 JavaScript 对象键。
  • 单价 在第一件商品是 128.5、第二件是 299,生成器把两种数字都列进 z.union。这个 union 等价于 z.number(),直接改成 z.number() 更清楚。如果样本里的价格碰巧都是整数,就只会得到 z.number().int(),以后遇到 128.5 会校验失败,所以价格字段要手动检查。
  • 备注 只在第二件商品里出现,所以加了 .optional()。

根名称按 ECMAScript 标识符规则处理,首字母变成大写:中文等各国文字的字母、数字以及 $、_ 都保留,用户 得到 用户Schema;其他字符被去掉、后一个字母变成大写,user profile 得到 UserProfileSchema;不能作为开头的加前缀 T,2fa 得到 T2faSchema。什么都不剩时用 Root。

示例:后端返回的 19 位 ID

很多 Java 后端用 MyBatis-Plus 的 IdType.ASSIGN_ID 生成主键。按 MyBatis-Plus 注解文档,它默认用雪花算法,适用于 Long、Integer、String 类型的主键。主键是 Long 时,接口返回的 JSON 里会是一个很长的数字。根名称填 UserResult:

{"code":200,"msg":"操作成功","data":{"id":1830000000000000001,"userName":"张三","remark":null}}

输出:

import { z } from "zod";

const UserResultSchema = z.object({
  code: z.number().int(),
  msg: z.string(),
  data: z.object({
    id: z.number().int(),
    userName: z.string(),
    remark: z.null(),
  }),
});

export type UserResult = z.infer<typeof UserResultSchema>;

1830000000000000001 大于 Number.MAX_SAFE_INTEGER(9007199254740991,见 MDN),JSON.parse 读出来是 1830000000000000000,生成器和你的前端拿到的都是这个已经变了的值。用这份 schema 去校验这份样本,两个版本的结果不同:Zod 3 的 z.number().int() 放行,错误的 ID 一路传下去;Zod 4 的 z.number().int() 只接受安全范围内的整数,报 Too big: expected int to be <9007199254740991。两种结果都说明数字类型装不下这个 ID,应让后端把它输出成字符串,schema 改为 z.string().regex(/^\d+$/)。

remark 样本里是 null,生成 z.null(),只接受 null。按接口文档改成 z.string().nullable()。

生成后怎么改

生成结果问题改为(Zod 4)
email: z.string()任意字符串都能通过z.email()(Zod 3:z.string().email())
数量: z.number().int()只有一定是整数时才对,10.5 会报 Invalid input: expected int, received number价格类字段用 z.number(),再加 .min(0)
remark: z.null()只有 null 能通过z.string().nullable()
status: z.string()任意字符串都能通过z.enum(["active", "inactive"])
样本里出现过的字段一律必填,即使接口有时不返回加 .optional()

失败就应该停止运行的地方(如启动时读配置)用 .parse(),它会抛出 ZodError;接口响应和用户输入用 .safeParse(),它返回 { success: false, error },由你自己处理错误。

限制

  • 类型只来自一份样本。 空数组生成 z.array(z.unknown()),空对象生成 z.record(z.string(), z.unknown())。
  • null 生成 z.null()。 不会自动加 .nullable()。在对象数组里,某个键在第一项是 null、第二项是字符串时,生成 z.union([z.null(), z.string()])。
  • 混合数组生成 union。 [{"a": 1}, 2] 这样的数组,不论在根上还是在对象内部,都生成 z.array(z.union([z.number().int(), z.object({ a: z.number().int() })]))。同一数组里的对象合并成一个 z.object,所以 union 里只有一个对象成员。
  • 同一个键既有整数又有小数时生成 union。 z.union([z.number(), z.number().int()]) 可以直接改成 z.number()。
  • 大整数。 输入用 JSON.parse 读取,大于 9007199254740991 的整数在生成 schema 之前就已经变了。
  • 没有字符串格式与范围。 邮箱、URL、日期、UUID 都是 z.string()。
  • 嵌套极深时可能超出浏览器的调用栈。 这时状态栏显示错误,之前的 schema 被清空,「复制」按钮停用。
  • 输入必须是合法 JSON。 无效时输出被清空、「复制」按钮停用,状态栏给出出错的行、列和可能的原因,行列按你输入的原文计算。中文输入法带进来的全角冒号会被指出来:{"订单号":"A-1001"} 显示 JSON 格式错误:第 1 行第 7 列,全角字符 :;JSON 的标点和空格必须是半角。

FAQ

什么是 Zod?

Zod 是一个 TypeScript 优先的 schema 声明和验证库,让你定义数据结构并在运行时进行验证。广泛应用于 API 响应验证、表单验证和配置解析。

生成器如何推断类型?

生成器检查每个 JSON 值:字符串 → z.string(),布尔 → z.boolean(),整数 → z.number().int(),小数 → z.number(),null → z.null(),数组 → z.array(),对象 → z.object()。对于对象数组,只在部分元素中出现的键会加 .optional(),不同元素里类型不同的键会生成 z.union。

什么是严格模式?

勾选「严格模式(不允许多余字段)」后,每个 z.object() 后都会追加 .strict(),嵌套对象也一样。Zod 会拒绝包含 schema 中未定义字段的输入对象。不勾选时,多余字段会从解析结果里被悄悄去掉(Zod 默认行为)。

生成的代码能用于 Zod 3 和 Zod 4 吗?

能。生成器只用 z.object、z.array、z.union、z.record、z.string、z.number().int()、z.boolean、z.null、z.unknown、.optional() 和 .strict(),两个版本都有。本页示例在 TypeScript 严格模式下分别对 Zod 3 和 Zod 4 API(zod/v4)编译通过。有一处差别:Zod 4 的 z.number().int() 还会拒绝超出安全整数范围(大于 9007199254740991)的整数。

生成的 schema 可以直接用于生产吗?

生成的 schema 适合当初稿,用到生产前按业务补上约束,例如给字符串和数字加 .min()/.max(),把可能为 null 的字段改成 .nullable().optional(),或把嵌套的 schema 拆成单独命名的常量。

我的 JSON 数据会发送到服务器吗?

不会。页面在浏览器里根据你的 JSON 生成 schema,不把 JSON 发送到任何地方,也不保存到浏览器存储。页面的统计只在你改完输入、焦点离开输入框后,或点击「生成 Zod Schema」「示例」时记录一次使用事件(工具名和动作 generate),不包含 JSON 或生成的代码。