很多人第一次接触 JSON Schema，是在接口已经出问题之后：前端收到一个本来应该是数字的字符串，测试发现某个字段偶尔缺失，或者后端改了嵌套结构，却没有人能说清这是不是破坏性变更。JSON Schema 在线工具能把一份真实样例转换成可阅读、可校验的结构约定，再继续生成 Mock 数据、代码类型和可视化结果。它不是把 JSON 换一种格式那么简单，而是帮团队把“我们约定接口长这样”说得更具体。

JSON Schema 到底解决什么问题

JSON 样例回答的是“这一次返回了什么”，JSON Schema 更接近“这类数据允许长什么样”。样例里有一个 price 字段，只能说明当前数据里出现了它；Schema 则可以进一步表达它是数字、是否必填、是否允许为空、字符串应该符合什么格式，以及对象内部可以有哪些属性。两者都重要，但用途不同：样例适合阅读和演示，Schema 适合校验和沟通。

这也是为什么我不建议把 Schema 只当成代码生成的中间文件。它更像接口协作里的共同语言。前端可以据此生成类型或 Mock，后端可以据此检查响应，测试可以据此准备边界数据，产品或技术文档也能更容易看出字段层级。工具把这些动作放在同一个页面里，适合先用一份脱敏样例把结构搭出来，再回到业务里补齐真正的约束。

  • 生成：从 JSON 样例快速得到 Schema 草稿，减少手写括号和层级的成本。
  • 校验：检查一份数据是否符合字段类型、必填项和结构约束。
  • Mock：没有后端接口时，先根据 Schema 生成可供前端联调的示例数据。
  • 交付：把结构转换为 TypeScript 等代码，或用可视化方式帮助别人快速理解。
先记住一个边界
从样例生成的 Schema 只是起点，不等于完整接口契约。样例没有出现的字段，可能是可选字段，也可能只是这次没有覆盖；真正的必填规则、枚举全集和业务条件，仍需要接口负责人确认。

一份样例应该怎样变成可用 Schema

直接把生产响应粘贴进去当然很快，但不一定稳。真实响应经常混有 Token、手机号、订单号、内部 URL，甚至把日志前缀一起复制了进来。更好的习惯是先整理输入，再生成草稿，最后用实际场景验证。这个流程看起来多了几步，却能避免把脏数据、偶然字段和敏感信息一起写进团队材料。

  1. 1
    先准备一份脱敏且合法的 JSON
    从接口响应中移除访问令牌、Cookie、真实个人信息和内部地址。若输入还不是合法 JSON，可先用 JSON 在线校验工具定位语法错误，再用 JSON 格式化工具整理结构。
  2. 2
    观察数据里稳定和偶然的字段
    把字段分成“每次都应该有”“只有部分场景出现”和“调试时才出现”三类。生成工具能从样例推断结构，但它不知道 traceId 是必填业务字段还是一次请求的临时信息。
  3. 3
    用 JSON 转 Schema 得到第一版
    打开 JSON Schema 工具的 JSON 转 Schema 面板，先接受自动生成的层级和基础类型，再逐项检查数组、对象、空值和必填字段是否符合预期。
  4. 4
    补上业务约束和字段说明
    把仅靠样例看不出的规则补进去，例如金额不能为负、状态只能取某几个值、邮箱要符合格式、数组至少包含一项。描述字段含义时，尽量写“它影响什么”，不要只重复字段名。
  5. 5
    用正常、边界和错误数据各校验一次
    一份只通过正常样例的 Schema 还不够。准备一份完整数据、一份缺少字段的数据和一份类型错误的数据，确认校验结果能把问题指出来，而不是因为约束过松全部放行。

最容易写错的五类约束

Schema 真正有价值的地方，不在于字段树看起来多完整，而在于它能否把团队已经达成的判断写出来。下面几类约束最值得人工复核，因为自动生成通常只能根据当前样例猜测，猜得越“自信”，越容易让人忘记它其实只是猜测。

1. 必填和可选不是一回事

某个字段在样例里出现，并不代表所有请求都必须带它。比如订单的 coupon 可能只在使用优惠券时返回，用户没有优惠券时字段可能缺失，也可能返回 null。你需要先确认接口约定，再决定它进入 required、允许 null，还是两者都不满足。不要因为“当前样例里有”就把所有字段都锁死。

2. null、空字符串和缺失各有含义

在数据处理中，这三种状态经常被混成一团：字段不存在，字段存在但值为 null，字段存在且值是空字符串。对展示型字段来说，它们可能都意味着“没有内容”；对筛选、计费和权限字段来说，含义可能完全不同。Schema 不能替你做业务决策，但可以把决定后的差异写清楚，让校验及时暴露不一致。

3. 数字和数字字符串不能凭感觉处理

19.9 和 "19.9" 对人眼很像，对程序却是不同类型。数量、金额、排序权重和时间戳是否应该是 number，要结合接口消费者和序列化规则确认。尤其不要为了让一份混乱数据通过，就把所有字段都放宽成 string；短期少一个错误，长期却会让类型问题一路传到业务逻辑里。

4. 数组是重复对象，还是固定选项集合

items 可能是任意长度的订单列表，也可能是必须包含 2 个元素的坐标。对数组而言，元素类型、最小长度、最大长度和元素内部结构都可能有意义。工具能帮助你看出数组层级，但最小数量和业务顺序通常要由人补上。若要限制数组元素只能取固定选项，还应明确使用枚举，而不是仅凭一个样例推断。

5. 格式约束不是“长得像”就算

日期、邮箱、手机号、URL、UUID 等字符串，常常需要 format 或更明确的模式约束。但格式也不能滥用：一个内部编号未必是 UUID，一个只用于展示的日期也未必需要完整的时间格式。先确认消费者真正依赖的格式，再写约束，避免把前端暂时的展示习惯误写成接口规则。

免费工具、代码生成和真实交付怎么配合

JSON Schema 页面本身更像一个小型工作台，而不是只有一个“转换”按钮。JSON 转 Schema 适合从样例起步；Schema 转 Mock 适合后端还没准备好时让前端先动起来；校验面板适合检查响应是否遵守约定；代码生成适合把结构带回项目；可视化面板则适合在评审或交接时快速浏览层级。

能力免费版Pro
接口刚有一份响应样例只复制样例给别人先转成 Schema 草稿，再补业务约束
前端等待后端接口手写几份临时 JSON由 Schema 生成 Mock，保持结构一致
上线前检查响应凭肉眼看字段用正常、缺失、类型错误样例分别校验
把结构带进代码库手写类型，容易漏嵌套层级生成类型草稿后由开发者复核
评审复杂嵌套数据在长 JSON 中上下滚动用可视化结构先定位讨论范围

这里的“更稳做法”不代表每次都要把所有面板走一遍。接口很小的时候，生成 Schema 再校验一次就够；数据结构复杂、参与人多、版本要长期维护时，Mock、代码生成和可视化才更有价值。工具的意义是减少重复劳动，不是把简单事情强行流程化。

实操案例

一次会员接口改版怎样落地

后端准备把会员接口中的 level 从字符串改成对象，并新增权益列表。前端担心类型变化，测试需要边界数据，产品只关心不同等级展示哪些权益。
  1. 1.选取旧版和新版各一份脱敏样例，先在 JSON Schema 工具中分别生成结构草稿。
  2. 2.人工确认 level 的类型变化、权益列表是否可为空，以及没有权益时是空数组还是字段缺失。
  3. 3.从新版 Schema 生成 Mock 数据，让前端先覆盖基础会员、过期会员和权益为空的状态。
  4. 4.把正常响应、缺少 level 和错误类型的数据分别送入校验，记录哪些情况应该被拒绝。
  5. 5.再用 JSON Diff 工具对比新旧样例，把真正的结构变化写进变更说明。
得到什么：团队讨论的对象不再是一大段“新版 JSON”，而是具体到字段类型、必填状态、空值处理和兼容风险的约定。产品、开发和测试可以从同一份结构出发，但各自关注不同部分。

为什么生成的 Schema 不能直接当最终契约

自动生成的最大优点是快，最大的风险也是快。它能根据现有数据整理出对象、数组和基础类型，却无法从一份样例中知道未来所有合法状态。比如样例中只出现了 paid，不代表状态枚举只有这一项；样例里没有 cancelledAt，也不代表取消订单永远不需要这个字段。

所以，生成之后一定要有一轮“反向提问”：哪些字段是业务必需的？哪些只在某个状态下出现？空数组和缺失字段是否等价？金额精度怎么处理？时间使用 UTC 还是本地时区？数组顺序是否有意义？如果这些问题还没有答案，Schema 应该标记为草稿，而不是悄悄进入生产校验。

不要把校验工具当成接口治理的替代品
Schema 能发现结构不符合约定，却不能判断权限是否正确、金额计算是否合理、用户是否有资格看到某个字段，也不能替代 OpenAPI、接口测试、代码评审和发布流程。它是一层清晰的结构护栏，不是全部业务规则。

Schema 版本怎么维护，才不会越写越乱

当 Schema 开始参与联调和发布，就需要像代码一样考虑版本。新增一个可选字段通常比删除字段安全；把 number 改成 string、把对象改成数组、把可选字段变成必填，都可能让旧消费者出问题。判断兼容性时，不要只看 JSON 文件“还能不能打开”，要看现有客户端是否仍能读取、生成的类型是否仍能编译、校验规则是否会突然拒绝旧数据。

  • 文件名或目录写清接口名称、版本和更新时间，不要用一堆 final-new-v3。
  • 每次修改记录字段变更、兼容影响和需要同步的消费者。
  • 把正常样例、最小样例和失败样例一起保存，避免只测“最漂亮”的输入。
  • 生成的 TypeScript 类型、Mock 和文档都当作派生物，源头仍应是经过确认的 Schema。
  • 发布前使用 JSON Diff或代码评审检查结构变化，尤其关注 required、type、enum、数组和 null。

交给团队前的检查清单

  • 输入样例已经脱敏，并且通过 JSON 语法校验。
  • 每个字段的类型、必填状态、null 处理和业务含义都有人确认。
  • 数字没有被误写成数字字符串，日期和 URL 等格式约束有真实依据。
  • 数组的元素结构、是否允许为空、长度范围和顺序含义已经说明。
  • 至少准备了一份正常数据、一份缺失字段数据和一份类型错误数据。
  • Mock 数据只用于开发和测试，不冒充真实业务结果。
  • 生成的代码类型和 Schema 都经过项目负责人复核，没有直接盲目提交。
  • 版本变更已说明兼容性，相关前端、后端和测试用例都有后续动作。

和这些工具一起用

如果你手里的 JSON 还不合法，先用 JSON 在线校验工具找出最前面的语法错误；需要读懂或整理输入时，用 JSON 格式化工具处理缩进和结构。接口升级前后，可以用 JSON Diff 在线比对工具确认字段变化。现在就要开始的话，打开 JSON Schema 在线生成与校验工具，粘贴一份不含敏感信息的样例，从草稿开始，不必等到文档“完美”才动手。

常见问题

JSON Schema 和普通 JSON 有什么区别？

普通 JSON 描述一份具体数据，JSON Schema 描述数据允许具有什么结构和约束。前者适合传输、展示和举例，后者适合校验、生成 Mock、生成代码类型和维护接口约定。实际工作中通常需要样例与 Schema 配合，而不是二选一。

JSON Schema 怎么从一份样例生成？

先准备一份合法且脱敏的 JSON，在 JSON Schema 工具中选择 JSON 转 Schema，得到对象、数组和基础类型的草稿。生成后还要人工确认 required、null、enum、格式和数组长度，因为单个样例无法证明全部业务规则。

自动生成的 JSON Schema 可以直接用于生产吗？

不建议直接使用。自动生成结果通常只反映当前样例，可能漏掉可选字段、状态分支、枚举全集和边界条件。上线前应补齐业务约束，并用正常、缺失字段和类型错误数据分别校验，再由接口负责人复核。

JSON Schema 可以生成 Mock 数据吗？

可以。根据 Schema 生成 Mock 数据适合前后端并行开发、页面占位和测试准备，但 Mock 只能模拟结构和部分约束，不能代表真实接口的权限、分页、金额计算或业务状态。正式联调时仍需接入真实响应验证。

JSON Schema 校验能发现哪些错误？

它适合发现字段缺失、类型不匹配、数组元素结构错误、枚举值不允许以及格式或长度不符合约束等结构问题。它不能判断权限、业务计算、字段之间的复杂条件，也不能替代接口自动化测试和代码评审。

JSON Schema 和 OpenAPI 是一回事吗？

不是。JSON Schema 主要描述 JSON 数据结构和校验规则，OpenAPI 还会描述接口路径、HTTP 方法、参数、响应和认证等 API 文档信息。两者可以配合：OpenAPI 的请求体和响应体经常使用 Schema 表达，但 Schema 本身不包含完整接口调用说明。

字段缺失、null 和空字符串应该怎么区分？

先根据业务含义决定三者是否等价，再写入 Schema。缺失表示没有这个字段，null 表示字段存在但当前没有值，空字符串则是一个具体字符串值。对筛选、计费、状态和权限字段，通常不能只凭界面显示效果把它们混为一谈。