API 发货到足够多,知道一个项目需要 JSON 模式的确切时刻,它从来都不是在开始的时候,它已经是三周了,当第二个团队开始消耗你的端点时,有人发送了一个格式错误的请求体,以及一个 null slips into a field 每个人都假设始终是一个字符串突然你需要一份合同- 一份文件,上面写着,以机器可以强制执行的形式,"这是一种有效有效负载的样子。"那份文件是一个JSON模式,从已经返回真实数据的端点手写一个是后台工作中比较繁琐的工作之一。
TL;博士: 将 JSON 样品粘贴到其中 JSON 模式生成器、选秀-07或2020-12,并且它推断出一个模式-类型,
required字段、合并的数组项和字符串格式,例如date-time並uuid。它完全在你的浏览器中运行,所以携带令牌和个人数据的有效负载永远不会离开页面。将输出视为强有力的初稿,然后用只有你知道的限制来收紧它。
Toolz。dev 构建这个工具,因为我一直用手做同样的事情:打开一个响应体,眯着眼睛看它,然后把它的形状逐个从句转录成一个模式子句,它是重复的,而重复转录就是错误隐藏的地方,这个指南解释了生成器做什么,推理在哪里可靠,它需要你的判断,以及生成的模式如何适合真正的验证工作流程。
什么是 JSON 模式?为什么要从数据生成一个?
JSON Schema 是描述 JSON 结构的词汇,维护为 一个本身就很合适的规范 而不是作为约定。模式本身就是一个 JSON 文档,它声明每个字段的预期类型、需要哪些字段、嵌套对象和数组采用什么形状,以及 - 具有诸如以下关键字 pattern、 enum、 minimum、和 format -实际上允许什么值几乎每种语言的验证者都会读取一个模式,告诉你给定的文档是否符合,它是JSON世界与一个跨越服务边界的类型系统最接近的东西。
Sample生成schema,而不是从头开始写,原因在于schema大部分是机械的,走有效载荷,记录"这是一个字符串,这是一个整数,这个对象有这些键"正是机器应该做的那种工作是什么 不是 机械是语义层:知道这一点 status 可能只是四根弦之一,那 age 不能是负面的,那个 email must match一个真实的地址模式,generation处理机械脚手架,这样你就可以把注意力花在重要的约束上,你从一个已经符合现实的文档开始,加上规则,而不是从一个空白的文件开始,希望你记住每一个字段。
Trust维度也是有的,当你手打模式的时候,你编码的就是你 信 endpoint 返回。信念漂移从现实 - 一个字段得到添加,一个整数变为无效,返回单个对象的端点开始返回数组。从实际响应生成的模式锚定到您捕获服务当天真正发送的那个锚点在调试为什么验证在分期中通过并在生产中失败时非常值得。
生成器如何推断模式
Engine解析你的JSON,递归走值,为结构的每个部分发出一个模式节点,规则故意保守,因为过于宽松的模式是没有用的,过于严格的模式拒绝有效数据。
对于标量,它有所区别 integer 从 number - 42 变成 integer、 4.2 变成 number - 因为这种区别对于验证者和任何阅读模式的人来说都是有意义的。布尔值和 null map到他们自己的类型。字符串变成 type: string(format detection) 打开, 引擎会根据一组众所周知的模式检查值, 并对其进行标记: date-time、 date、 time、 email、 uri、 uuid、和 ipv4。
对于对象,它记录每个键,推断每个值的模式,并且 - if required inference 是启用的 - 标记一个键时需要出现在每个对象在该位置。对于单个对象, 表示所有键;有趣的情况是数组。
数(arrays of objects),生成器做了一些比天真的行走更有用的事情,而不是为每个元素或一个扩大的元素发出单独的模式 anyOf 它具有近乎相同的形状,将数组中的所有对象合并为一个 items schema,描述单个元素。每个元素中都需要一个密钥;仅某些元素中存在的密钥是可选的。这反映了真实的 API 集合的行为方式:大多数记录携带一个分页列表 avatarUrl 但也有少数没有。合并后的模式捕获"这些字段总是出现,这些字段有时会出现"在一个可读的定义中。您可以在内置示例中看到这一点,其中 members 数组有两个对象 - 一个具有 active 字段和一个没有 - 以及生成的项目模式标记 id 並 role 需要但离开 active 可选。
对于混合标量阵列,发动机将元件类型折叠成单个 type 阵 - ["integer", "string", "boolean"] -而不是冗长的并集,当宾语和非宾语形状真正混合在一个数组中时,它会回落到 anyOf,这是"这些替代方案之一的正确json模式构造。"
JSON 模式生成器的使用方法
步骤 1:粘贴代表性样品
API 响应、固定装置、配置文件或 Webhook 体中掉落,为了准确性,你能做的最重要的一件事就是粘贴 a 代表 sample。real response 中有几条记录,就把它们全部包含在一个数组里面- 生成器会将它们合并并正确推断可选性。一个记录样本告诉引擎它看到的每个字段总是存在的,这往往是错误的。先加载内置样本,看看嵌套对象、对象数组和格式化字符串是如何处理的,然后再粘贴自己的。
2步:选择方言
Pick Draft-07,以获得跨验证库的最宽兼容性,或2020-12,以获得当前规范。该工具写入正确的 $schema root上的标识符,因此您的验证器应用了正确的规则对于该生成器生成的对象和数组形状,两种方言的结构输出相同;可见的差异是标识符如果您不确定您的工具支持哪些,draft-07是安全默认值 - 它具有任何版本中最广泛的库支持。
3步:设置你的选项
添加a title 如果您想要模式自文档。决定是否发射 required -大部分时间你想要它,但在早期探索中你可能更喜欢一个更宽松的模式保持格式检测,除非你看到误报。并打开严格模式(additionalProperties: false) 当模式保护您完全控制的东西时,例如配置文件或请求正文,并且您希望拒绝而不是忽略意外的密钥。
4步:生成、审核、导出
按生成,然后批判性地读取输出。检查一下 required matched your intention,那个整数对数出来的正确,任何检测到的格式都是正确的而不是巧合的,当它看起来正确的时候,复制模式或者下载为a .json 文件准备放入验证器或存储库。
一个有效的例子
从假设中考虑这个反应 /projects 端点:
{
"id": "5b2a1f6e-8c3d-4a1b-9f7e-2c1d3e4f5a6b",
"name": "Toolz",
"createdAt": "2026-01-14T09:30:00Z",
"score": 4.8,
"members": [
{ "id": 1, "role": "owner", "active": true },
{ "id": 2, "role": "editor" }
]
}
生成器生成一个模式 id 是一个字符串 format: "uuid"、 createdAt 是一个字符串 format: "date-time"、 score 是a number (不是整数, 因为小数), 和 members 是一个数组,其 items 模式需要 id 並 role 但不是 active.最后一个细节是回报:从两个示例成员中,它正确地推断出 active 是可选的,在很大的有效载荷上手工进行这种推理,正是生成器所移除的那种细心、无聊的工作。
推理在哪里结束,你的判断从哪里开始
我想直接了解极限,因为直接交给生产的生成模式是一个错误。推理看到类型和结构;它看不到意图。
它无法知道这一点 role 是枚举 owner、 editor、和 viewer - 从样本中它只知道 role 是字符串,它不能知道这一点 score 0到5不等,那 name has maximum length,或者说一个恰好看起来像 UUID 的代码实际上是一个不透明的标识符,应该保持一个普通的字符串。它推断 required from 存在,因此在您校正之前,需要标记恰好出现在样本中的可选字段。并且它根据您给出的数据起作用:如果您的样本从未包含 a null 对于可空字段,模式将不知道该字段可以是空的。
正确的心理模型是脚手架。生成器准确地构建框架 - 每个字段、其类型、嵌套、数组形状、基于存在的所需列表。然后添加语义约束:枚举、模式、数字边界以及引擎无法从一个值看到的任何格式。这比从无到有更快、更不容易出错,因为繁琐的结构转录已经完成并且正确。
07年选秀对阵2020-12:你应该选择哪一个?
| 考虑 | 07草案 | 2020-12 |
|---|---|---|
| 图书馆支持 | 最广泛;几乎到处都得到支持 | 成长;检查您的验证器 |
| 状态 | 部署广泛、稳定 | 当前规格 |
$schema 价值 |
http://json-schema.org/draft-07/schema# |
https://json-schema.org/draft/2020-12/schema |
| 数组项目关键字 | items 为单项模式 |
items / prefixItems 分割为元组 |
| 最好的时间 | 最大兼容性很重要 | 您想要最新的规格功能 |
对于该工具生成的模式 - 对象、所需列表、单个项目形状的数组 - 两种方言表达相同的结构。实际决策取决于您的验证库支持的内容。如果您将模式接线到已建立的堆栈中,请匹配验证器文档的版本。如果您开始时新鲜且没有约束,Draft-07 仍然是其无与伦比的生态系统支持的务实选择。
常见用例
记录现有 API。 当您继承一个没有模式的端点时,从真实响应生成一个端点可以在几秒钟内为您提供准确的起始文档。然后将其细化为已发布的合同。这自然地与为您的客户端代码生成类型配对 - 同一个样本可以提供 json 打字稿 具(因此您的服务器合同和客户端类型来自相同的真理来源)。
验证请求机构。 对于您控制的请求正文,从有效示例生成架构,打开严格模式以拒绝意外密钥,并添加端点强制执行的枚举和边界。现在,格式错误的请求在边缘失败,存在明显的验证错误,而不是在处理程序深处造成混乱的故障。
配置文件验证。 JSON配置读取的应用程序从模式中受益匪浅。从已知的良好配置中生成一个,将其收紧,并在启动时进行验证,因此配置密钥中的错字会大声失效,而不是默默禁用功能。
测试和固定装置。 模式兼作测试资产。在 CI 中验证您的夹具,以便在产生误导性绿色测试之前捕获形状偏差的夹具。
服务之间的合同测试。 当两个服务就有效负载达成一致时,共享模式就是合同。从真实消息生成它并对其进行细化,为两个团队提供了一个可以独立验证的文档。
隐私:为什么这会在您的浏览器中运行
API样本是开发人员处理的一些最敏感的文本,它们通常包含访问令牌,会话标识符,电子邮件地址,内部记录ID,偶尔还有个人数据,这些数据永远不应该粘贴到随机的Web表单中,这正是为什么JSON架构生成器在客户端的所有解析,推断和序列化发生在浏览器中的JavaScript中,没有任何东西上传,记录或存储在服务器上,您可以在生成时打开网络选项卡来验证这一点,或者通过断开与互联网的连接 - 该工具仍然有效。我关心这一点,因为我不会使用将我的有效负载发送给其他人的工具's服务器,我也不会要求您同样的原则贯穿整个toolz。dev,这是我在the中详细提出的论点 在线工具中的数据隐私 写入。
它如何适合更广泛的 JSON 工具包
模式是更大的 JSON 工作流程中的一个工件。在生成模式之前,它有助于拥有干净、有效的输入 - json格式化程序 will格式化和验证有效负载,这样你就不会将格式错误的文本输入生成器,在你有了模式之后,你经常想要应用程序代码的类型,这就是在哪里 json 打字稿 进来。如果您的管道在格式之间移动,则 JSON 到 YAML converter 处理许多 config 和 CI 系统所期望的转换。我写过这些部件如何在 中连接 JSON 工具的终极指南并且关于在中组装更广泛的套件 web开发人员工具包 overview。comned工具包的要点是,单个样本可以流过几个工具 - 模式,类型,格式转换 - 从未离开浏览器。
常问问题
如何从JSON生成JSON模式？
JSON粘贴到编辑器中,选择Draft-07或2020-12,然后按生成工具推断每个字段的类型,提取所需的键,并输出一个模式,您可以直接复制到验证器中,没有上传任何内容 - 推理完全在浏览器中运行。
07和2020-12有什么区别？
JSON Schema规范的两个版本,Draft-07跨库支持最广,是安全的默认值,2020-12是当前版本,改变了数组和子模式的表达方式,除此之外,对于对象和数组形状,该工具产生的结构是相同的;主要的可见差异是 $schema 标识符。
该工具如何决定需要哪些字段？
当一个键出现在生成器看到的每个对象中时，它被标记为必需。 对于单个对象，表示每个键；对于对象数组，它表示所有元素中存在的键。 仅在某些记录中显示的键被排除在外，反映了 API 的 API 是如何省略可选字段的。 您可以完全关闭必需的现场检测。
对象数组会发生什么？
这些对象合并为一个 items schema描述单个元素,并且属性被键入为它的数组。每个元素中存在的键都成为必需的;仅某些元素中存在的键保持可选。这使得schema保持可读性,而不是产生大的 anyOf 的近乎相同的形状。
它检测到哪些字符串格式？
它认识到 date-time、 date、 time、 email、 uri、 uuid、和 ipv4 字符串并添加匹配项 format keyword。detection 是从单个样本中尽最大努力,所以要查看结果 - 一个恰好看起来像 UUID 的代码将被标记为一个,如果您喜欢纯字符串类型,您可以禁用格式检测。
我可以从单个样本中生成模式吗？
是的,但一个样本只显示一种可能的形状。在您的样本中作为数字的字段可能为 null 或其他地方的字符串,并且需要标记恰好存在的可选字段。样本越具有代表性 - 理想情况下是几个真实记录 - 推断的类型和所需列表就越准确。
生成的模式是否已准备好进行生产验证？
把它当作一个强有力的起点,而不是一个成品文档,推理准确地捕获类型、结构和所需字段,但语义约束-枚举、字符串模式、数字最小值和最大值,从一个值看不到的格式-仍然需要手工生成,去掉繁琐的脚手架,这样你就可以专注于那些规则。
我的json是否上传到服务器？
No。整个推理引擎在你的浏览器中以JavaScript运行。没有传输,记录或存储任何内容。您可以通过在生成时查看您的网络选项卡,或者通过断开与互联网的连接来确认这一点 - 该工具仍然有效。
