免费工具 JSON Schema 生成与校验
把几条真实数据贴进来,比如埋点上报的事件、接口返回的 JSON,自动生成描述它们的 JSON Schema(Draft 2020-12):字段类型、必填项、可为空的字段、嵌套对象和数组、日期时间和邮箱格式。再切到校验,一眼看出哪条数据的哪个字段不符合约定。
- 多条样本合并推断
- 错误带 JSON Pointer 路径
- 本地处理
生成 Schema,再拿它校验数据
示例是统计 SDK 上报的三条「支付成功」事件。换成你自己的 JSON,Schema 会随输入更新。
生成:一条或多条样本,每条一行(JSON Lines 也行)。校验:要检查的数据,多条会逐条校验。
JSON Schema。$ref 支持同一文档内的引用(#/$defs/…),不会去下载远程地址。
样本数
3
从输入框读到的 JSON 条数。
属性数
14
Schema 描述的字段数,含嵌套字段。
错误数
—
所有数据加起来的校验错误。
检查结果
- 通过3 条样本全部通过生成的 Schema。
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"event": {
"type": "string"
},
"time": {
"type": "string",
"format": "date-time"
},
"user_id": {
"type": "string"
},
"properties": {
"type": "object",
"properties": {
"order_id": {
"type": "string"
},
"amount": {
"type": "number"
},
"currency": {
"type": "string"
},
"coupon": {
"type": [
"string",
"null"
]
},
"channel": {
"type": "string"
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"sku": {
"type": "string"
},
"qty": {
"type": "integer"
},
"price": {
"type": "number"
}
},
"required": [
"sku",
"qty",
"price"
]
}
},
"email": {
"type": "string",
"format": "email"
}
},
"required": [
"order_id",
"amount",
"currency",
"channel",
"items"
]
}
},
"required": [
"event",
"time",
"user_id",
"properties"
]
}校验错误
路径是数据里的 JSON Pointer;Schema 路径指向没通过的那条规则。
版本 v1.0更新于 更新记录
Schema 是怎么推断出来的
生成器只知道样本里有什么。下面是它把「看到的」变成「规则」的方法。
类型
只出现整数时是 integer,整数和小数都有时是 number。示例里 amount 是 199、49.5、120,所以是 number;qty 全是整数,保持 integer。
必填
每条样本都有的字段才算必填。email 只在第三条里出现,所以写进了 properties 但不是必填。只给一条样本时所有字段都会变成必填,多给几条才准。
可为空
出现过 null 的字段写成类型数组,比如 ["string", "null"],这是 Draft 2020-12 表示「可为空」的写法。
格式和枚举
所有值都符合时才加 format,比如 time 里的 RFC 3339 时间。枚举默认关闭:三条样本通常不足以知道所有允许的取值;打开后 channel 会变成 ["小程序", "App"]。
把结果当初稿。最低金额、ID 规则、允许的币种这些只有你知道的约束,用作接口约定之前要自己补上。
从样本到可校验的约定
生成、收紧、再校验。
-
1
贴真实样本
从浏览器网络面板、日志或接口工具里复制几条数据,每条一行。把特殊情况也放进来:优惠券为 null、缺可选字段、空列表。
-
2
检查并收紧
复制或下载
schema.json,在规则明确的地方补上minimum、pattern、enum和additionalProperties: false。 -
3
校验数据
点用这个 Schema 校验,粘贴要检查的数据,看每个错误的路径。同一个 Schema 也能用在 Ajv、Python jsonschema 等支持 2020-12 的校验库里。
校验器检查哪些规则
校验器是为这个页面写的,覆盖大多数 Schema 会用到的关键字,并通过了官方 JSON-Schema-Test-Suite 里对应的用例。
- 远程
$ref、$dynamicRef、unevaluatedProperties/unevaluatedItems不计算,遇到时会提示是哪些 - 「格式」打开时检查
format(2020-12 默认只把它当注解);email、uri 用实用的规则,不是完整的 RFC 语法 pattern用 JavaScript 正则(带u标志),和多数浏览器、Node 校验库一致
| 作用于 | 关键字 |
|---|---|
| 任意值 | type、enum、const、allOf、anyOf、oneOf、not、if / then / else、同文档内的 $ref 和 $defs、$anchor |
| 对象 | properties、patternProperties、additionalProperties、required、propertyNames、minProperties、maxProperties、dependentRequired、dependentSchemas |
| 数组 | items、prefixItems、contains、minContains、maxContains、minItems、maxItems、uniqueItems |
| 数字 | minimum、maximum、exclusiveMinimum、exclusiveMaximum、multipleOf |
| 字符串 | minLength、maxLength(按字符数,一个汉字算 1)、pattern、format:date-time、date、time、email、uri、uuid、ipv4、ipv6、hostname |
三条支付事件,生成一个 Schema
生成器对示例事件每个字段的判断和原因。整个 Schema 描述了 14 个属性。
| 字段 | 样本里的值 | 生成结果 | 原因 |
|---|---|---|---|
time | 3 个带时区的时间 | string、date-time、必填 | 三个值都是 RFC 3339 时间 |
properties.amount | 199、49.5、120 | number、必填 | 有一个带小数 |
properties.coupon | null、"双11满减"、缺失 | ["string", "null"] | 出现过 null;有一条没有,所以不必填 |
properties.email | 只在第 3 条 | string、email | 另外两条没有,是可选字段 |
items[].qty | 1、2、3 | integer、必填 | 全是整数 |
properties.channel | 小程序、App、小程序 | string(打开枚举时为 ["小程序", "App"]) | 取值有重复 |
按钮里的「不合格的事件」违反了一个手工收紧过的 Schema 的 7 条规则:时间没有时区、用户 ID 少了 u_ 前缀、缺订单号、金额为负、币种小写、数量带小数、多了一个 source 字段。
自动生成的 Schema 容易错在哪
从样本推断出来的 Schema,好坏取决于样本。
样本太少
只有一条样本时,可选字段看起来都是必填,可为空的字段看起来都不会为空。把边界情况也喂进去。
数字被当成字符串
一个端上报 "amount": "199",另一个上报 199,就会得到类型数组。应该统一上报方,而不是两种都放行。
太早锁死
additionalProperties: false 会拒绝所有新字段。埋点事件经常加属性,只在结构确实固定的地方用。
混用版本
Draft-07 的元组写成 "items": [ … ],公共定义放 definitions;2020-12 要用 prefixItems 和 $defs,$schema 也要写对。
事件数据入库就校验
网站代码、App 和小程序 SDK、服务端 API 上报到 TapCub 的事件都以 JSON 携带属性。每条事件到达时都会检查,类型不对、缺属性不会悄悄带歪报表。
怎么根据 JSON 生成 JSON Schema?
把一条或多条 JSON 贴进输入框,每条一行,Schema 会随输入生成:类型、嵌套对象、数组元素、必填字段和格式。可以复制,也可以下载 schema.json。
生成的是哪个版本的 JSON Schema?
Draft 2020-12,开头写着 "$schema": "https://json-schema.org/draft/2020-12/schema"。生成结果只用了在 Draft-07、2019-09 里含义相同的关键字(type、properties、required、items、format、enum),多数校验库都能直接用。
必填字段是怎么判断的?
每条样本里都出现的字段才是必填。所以要多给几条样本:只有一条时,所有字段看起来都是必填。
怎么用 Schema 校验 JSON?
把模式切到「校验」,粘贴 Schema 和要检查的 JSON。每个错误都会给出数据里的路径(JSON Pointer,如 /properties/items/0/qty)、问题和没通过的 Schema 规则。
为什么同一个 Schema,别的校验器通过、这里不通过(或反过来)?
多半是 format:2020-12 默认只把它当注解,要校验器显式开启才检查。关掉「格式」就和不检查格式的校验器一致。另外看看提示里有没有本工具不计算的关键字,比如远程 $ref、unevaluatedProperties。
能用来校验埋点数据吗?
可以。每个事件一个 Schema,就是一份紧凑的埋点约定:金额被当成字符串上报、缺订单号、属性名拼错,都能在进报表之前发现。
我的 JSON 会被上传吗?
不会。生成和校验都在你的浏览器里完成,页面也没有分享链接,样本不会出现在网址里。不过往任何在线工具里贴数据前,建议先去掉令牌和个人信息。