JSON 转 JSON Schema

JSON Schema 是什么

JSON Schema 用 JSON 描述 JSON 数据的结构：每个字段是什么类型、哪些字段必须有、嵌套对象长什么样。Ajv 这类校验器拿它检查数据，接口校验、代码生成和文档都会用到。这个工具从一份样本 JSON 反推出 draft-07 的 Schema，省去从零手写的工作。

理解输出结果

生成的 Schema 始终包含指向 draft-07 的 $schema 字段。 对象属性根据 JSON 的键名推断，required 数组列出所有非 null 键。 数组的 items 根据实际元素推断类型。

生成后的优化建议

生成的 Schema 只是起点，常见的优化包括：为字段添加 description 说明、 用 minLength 或 pattern 收紧字符串约束、 将可选字段从 required 中移除， 以及为枚举类字段添加 enum 限制。

示例

输入：

{
  "orderId": 1001,
  "total": 59.9,
  "coupon": null,
  "items": [{ "sku": "A1", "qty": 2 }],
  "tags": []
}

输出：

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "orderId": { "type": "integer" },
    "total": { "type": "number" },
    "coupon": { "type": "null" },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "sku": { "type": "string" },
          "qty": { "type": "integer" }
        },
        "required": ["sku", "qty"]
      }
    },
    "tags": { "type": "array", "items": {} }
  },
  "required": ["orderId", "total", "items", "tags"]
}

• 整数生成 integer，小数生成 number。如果 qty 可能是 1.5，改成 number。
• 样本里 coupon 是 null，所以类型为 null，且不进 required。如果它也可能是字符串，把类型改成 ["string", "null"]。
• 空数组生成 "items": {}，任何元素都能通过。

示例：高德地图地理编码返回

高德地图 Web 服务 API 的地理编码接口返回 JSON。文档在返回结果说明的「提示」里写明：部分返回值存在时以字符串类型返回，不存在时以数组类型返回。下面按文档字段写了两条结果（坐标等值为示意），第二条没有街道和门牌：

{
  "status": "1",
  "count": "2",
  "info": "OK",
  "geocodes": [
    { "district": "朝阳区", "street": "阜通东大街", "number": "6号", "location": "116.483038,39.990633", "level": "门牌号" },
    { "district": "朝阳区", "street": [], "number": [], "location": "116.480881,39.989410", "level": "兴趣点" }
  ]
}

生成：

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "status": { "type": "string" },
    "count": { "type": "string" },
    "info": { "type": "string" },
    "geocodes": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "district": { "type": "string" },
          "street": { "type": ["string", "array"], "items": {} },
          "number": { "type": ["string", "array"], "items": {} },
          "location": { "type": "string" },
          "level": { "type": "string" }
        },
        "required": ["district", "street", "number", "location", "level"]
      }
    }
  },
  "required": ["status", "count", "info", "geocodes"]
}

• status 和 count 在样本里是字符串，所以类型是 string。写成数字 1 的数据会被拒绝。文档说 status 只有 0 和 1 两个值，需要限定时自己加 "enum": ["0", "1"]。
• street、number 一条是字符串、一条是 []，合并后类型是 ["string", "array"]，带 "items": {}，两种写法都能通过。如果样本里只有带门牌的那一条，生成的 Schema 会要求 street 是字符串，遇到 [] 就校验失败。所以样本要同时包含有值和没值的记录。
• 坐标 location 是 "经度,纬度" 一个字符串，工具不会拆开，也不会检查格式；需要时加 pattern。

用 Ajv 校验

Ajv 8 默认的 Ajv 类支持 draft-07。format 关键字需要 ajv-formats，不装的话 compile() 会抛出 unknown format "email"：

import Ajv from 'ajv';
import addFormats from 'ajv-formats';

const ajv = new Ajv();
addFormats(ajv);

const validate = ajv.compile({
  type: 'object',
  properties: {
    email: { type: 'string', format: 'email' },
    coupon: { type: ['string', 'null'] },
  },
  required: ['email'],
  additionalProperties: false,
});

validate({ email: 'a@example.com', extra: 1 }); // false: must NOT have additional properties

生成器不会加 format、minimum、maxLength、pattern、enum 或 additionalProperties: false，按数据必须满足的规则自己补上。

限制

• 数组元素会合并。 对 [{"id": 1, "name": "Alice"}, {"id": 2, "email": "b@example.com"}]，items 列出 id、name、email，只有每个元素都有的 id 是必填。同一数组里的整数和小数合并为 "number"。生成的 schema 一定能通过它的样本；GenSON 也是这样合并样本的。
• 必填项来自样本。 单个对象里所有非 null 的键都进 required。数据里可选、但样本里出现了的字段，需要自己从 required 删掉。
• 混合类型生成类型列表。 [1, "x", {"a": 1}] 这样的数组生成 "type": ["integer", "string", "object"]，旁边带对象的 properties 和 required，这两个关键字只作用于对象元素。
• 只输出 draft-07。 要用 2020-12，改 $schema 并使用 Ajv 的 Ajv2020 类。