TapCub 正式上线:统计、分析、客服一个平台免费用

免费工具 JSON Schema 生成与校验

把几条真实数据贴进来,比如埋点上报的事件、接口返回的 JSON,自动生成描述它们的 JSON Schema(Draft 2020-12):字段类型、必填项、可为空的字段、嵌套对象和数组、日期时间和邮箱格式。再切到校验,一眼看出哪条数据的哪个字段不符合约定。

  • 多条样本合并推断
  • 错误带 JSON Pointer 路径
  • 本地处理

生成 Schema,再拿它校验数据

示例是统计 SDK 上报的三条「支付成功」事件。换成你自己的 JSON,Schema 会随输入更新。

生成工具

生成:一条或多条样本,每条一行(JSON Lines 也行)。校验:要检查的数据,多条会逐条校验。

已根据 3 条样本生成 Schema。

样本数

3

从输入框读到的 JSON 条数。

属性数

14

Schema 描述的字段数,含嵌套字段。

检查结果

  • 通过3 条样本全部通过生成的 Schema。
JSON Schema(Draft 2020-12)
{
  "$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"
  ]
}
全部在你的浏览器里计算。这里输入的任何内容都不会上传,TapCub 也不会保存。

版本 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. 1

    贴真实样本

    从浏览器网络面板、日志或接口工具里复制几条数据,每条一行。把特殊情况也放进来:优惠券为 null、缺可选字段、空列表。

  2. 2

    检查并收紧

    复制或下载 schema.json,在规则明确的地方补上 minimum、pattern、enum 和 additionalProperties: false。

  3. 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 校验库一致
校验器支持的 JSON Schema 2020-12 关键字
作用于关键字
任意值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 个属性。

示例事件的字段和生成的 Schema
字段样本里的值生成结果原因
time3 个带时区的时间string、date-time、必填三个值都是 RFC 3339 时间
properties.amount199、49.5、120number、必填有一个带小数
properties.couponnull、"双11满减"、缺失["string", "null"]出现过 null;有一条没有,所以不必填
properties.email只在第 3 条string、email另外两条没有,是可选字段
items[].qty1、2、3integer、必填全是整数
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 也要写对。

常见问题

JSON Schema 生成常见问题

还有其他问题?

直接和 TapCub 团队聊聊——工作日通常几小时内回复。

怎么根据 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 会被上传吗?

不会。生成和校验都在你的浏览器里完成,页面也没有分享链接,样本不会出现在网址里。不过往任何在线工具里贴数据前,建议先去掉令牌和个人信息。

更新记录

更新记录

这个工具的新功能、修复和数据更新,最新的在前。

  1. · v1.0

    首次上线首次上线。

缺功能或发现错误?告诉我们,常被提到的会排进下次更新。 全部工具更新

看清数据,找到增长。

每一次点击,都有数据依据。装好一行代码,1 分钟看到第一批数据。

无需信用卡 · 统计与客服都有免费版 · 统计无 Cookie