JSON Schema 校验

开发工具

正在载入

正在加载工具

工具代码会在打开时按需载入，请稍候。

本工具的全部运算都发生在你的浏览器中，输入内容不会发送到任何服务器。

关于这个工具

本工具仅支持所选 JSON Schema 规范的有限子集，会明确拒绝不支持的功能。明确选择 Draft 7、2019-09 或 2020-12，按对应规范校验 JSON 文档。独立的浏览器工作线程在本地完成解析、编译和校验，包含启动在内最多运行两秒。结果会区分文档未通过、schema 不可用、功能不支持和未完成的运行。诊断报告包含文档路径、schema 路径和关键字，不含原始值或异常文本；但属性名仍可能泄露敏感信息。

常见用途

集成 schema 前，检查 API 示例数据的必填属性、类型和数组约束。
不下载远程 schema、不进行服务器校验，直接比较规范版本之间的行为。
检查路径中的属性名不含隐私后，分享简明的诊断报告。

使用方法

1.选择 schema 使用的规范版本。若包含 $schema，必须与选择一致。示例菜单可载入完整的 schema 与文档，并自动切换到相应版本。
2.在第一个编辑框粘贴严格 JSON 格式的 schema 对象或布尔值，在文档框输入任意 JSON 值，再点击开始校验。编辑任一输入、切换版本、载入示例或清空时，会取消旧运行并清除旧结果。
3.先查看结果状态。文档未通过时，逐项检查关键字、文档的 JSON Pointer 和 schema 路径。required 错误定位到应包含该属性的对象，不导出缺失属性的原始值。检查路径后再复制或下载诊断 JSON。超时、取消与安全限制均不代表文档已经通过或未通过校验。

可执行的 schema 与文档示例

有效对象

{
  "draft": "draft7",
  "schema": {
    "type": "object",
    "properties": {
      "name": {
        "type": "string"
      },
      "age": {
        "type": "integer",
        "minimum": 0
      }
    },
    "required": [
      "name"
    ],
    "additionalProperties": false
  },
  "instance": {
    "name": "Avery",
    "age": 28
  }
}

{
  "status": "valid",
  "keywords": []
}

name 存在，两个值的类型均符合要求。additionalProperties: false 会拒绝多余属性。示例中的输入 JSON 描述三个界面字段，应分别填入 schema 和 instance。

缺少必填属性

{
  "draft": "draft7",
  "schema": {
    "type": "object",
    "properties": {
      "name": {
        "type": "string"
      },
      "age": {
        "type": "integer",
        "minimum": 0
      }
    },
    "required": [
      "name"
    ],
    "additionalProperties": false
  },
  "instance": {
    "age": 28
  }
}

{
  "status": "invalid",
  "keywords": [
    "required"
  ]
}

age 可选，但 name 必填。文档在 required 处失败，路径指向包含对象，其 JSON Pointer 为空字符串。

字符串不是整数

{
  "draft": "draft7",
  "schema": {
    "type": "object",
    "properties": {
      "name": {
        "type": "string"
      },
      "age": {
        "type": "integer",
        "minimum": 0
      }
    },
    "required": [
      "name"
    ],
    "additionalProperties": false
  },
  "instance": {
    "name": "Avery",
    "age": "28"
  }
}

{
  "status": "invalid",
  "keywords": [
    "type"
  ]
}

age 的值是 JSON 字符串，因此在 /age 的 type 处失败。不会自动将其转换为数字。

数组元素重复

{
  "draft": "2019-09",
  "schema": {
    "type": "array",
    "items": {
      "type": "integer"
    },
    "minItems": 2,
    "uniqueItems": true
  },
  "instance": [
    1,
    1
  ]
}

{
  "status": "invalid",
  "keywords": [
    "uniqueItems"
  ]
}

两个元素均为整数，数量也符合要求，但 uniqueItems 不允许重复。诊断关键字为 uniqueItems。

本地 $defs 引用

{
  "draft": "2020-12",
  "schema": {
    "$defs": {
      "positive": {
        "type": "integer",
        "minimum": 1
      }
    },
    "type": "object",
    "properties": {
      "count": {
        "$ref": "#/$defs/positive"
      }
    },
    "required": [
      "count"
    ]
  },
  "instance": {
    "count": 3
  }
}

{
  "status": "valid",
  "keywords": []
}

count 引用当前 schema 内的 #/$defs/positive，其值满足 integer 和 minimum。不需要网络查询。

Draft 7 忽略 $ref 同级断言

{
  "draft": "draft7",
  "schema": {
    "$ref": "#/definitions/value",
    "definitions": {
      "value": {
        "type": "string"
      }
    },
    "minLength": 3
  },
  "instance": "ok"
}

{
  "status": "valid",
  "keywords": []
}

Draft 7 使用引用中的字符串 schema，忽略 $ref 旁的 minLength。因此两个字符的文档通过。下一例使用完全相同的 schema 和数据。

2020-12 执行 $ref 同级断言

{
  "draft": "2020-12",
  "schema": {
    "$ref": "#/definitions/value",
    "definitions": {
      "value": {
        "type": "string"
      }
    },
    "minLength": 3
  },
  "instance": "ok"
}

{
  "status": "invalid",
  "keywords": [
    "minLength"
  ]
}

2020-12 还会执行 $ref 同级的 minLength，因此相同的两个字符在 minLength 处失败。保留 definitions 是为了两个版本使用同一份 schema 和本地引用。

常见校验误区

为声明 Draft 7 的 schema 选择 2020-12，或误以为工具会自动检测版本。
以为 properties 会要求属性必须存在；必须使用 required 指定必填。
以为字符串 "28" 可以满足 type: integer；本工具不会转换输入类型。
使用外部 $ref URL 或未知扩展关键字，却认为它们已经得到检查。
将 format 注解当成格式断言，或将超时视为通过。
未检查属性名就分享仅含路径的诊断报告。

限制与说明

支持 Draft 7、2019-09 和 2020-12，$schema 声明必须与所选版本一致。仅接受以 # 开头且可在当前 schema 内解析的片段引用，绝不获取外部 schema。不支持未知或自定义关键字、自定义规范、$vocabulary、$async 及 OpenAPI nullable。受引擎限制，schema 映射中的 __proto__ 条目也会被拒绝；文档中的键仍按普通输入数据处理。不支持嵌套的 $id 资源，允许根节点的 $id。由于本地引擎无法可靠处理全部组合行为，明确不支持 unevaluatedItems 和 unevaluatedProperties。同样不支持 $dynamicRef、$dynamicAnchor、$recursiveRef 和 $recursiveAnchor；仍支持普通本地 $ref 的递归引用。由于引擎解析存在歧义，引用片段中不支持百分号编码的斜杠（%2F）。属性名中的斜杠请使用 JSON Pointer 转义 ~1。 dependencies 或 dependentRequired 数组不得包含空字符串属性名；required 数组允许。
format 在本工具中仅作注解：format: "email" 不会拒绝错误的邮件地址字符串。不会转换类型、填入默认值或删除多余属性。通过仅表示满足所选规范与本地检查范围，并不验证应用业务规则，也不保证与其他校验器配置一致。
每份输入最多 200,000 个 UTF-8 字节、64 层嵌套及 20,000 个 JSON 值；正则模式最多 512 个字符。编译与校验位于独立工作线程，包含启动在内最多 2,000 毫秒。复杂 schema、递归引用或高开销正则可能触发限制或超时，不能据此推断通过。两秒限制通过浏览器计时器执行，后台标签页的调度可能延迟终止。工作线程隔离界面执行，但并非内存沙箱。另有限制：最多 512 个 schema 对象，每个直接 schema 子项列表最多 512 项。保守预计工作量为文档 JSON 值数量乘以 schema 对象数量，最多 200,000。错误并非穷尽列表：仅报告各个已评估分支的首个失败，修正后可能出现其他错误。每次运行还限制为最多 50,000 个加权校验工作单元，计入直接 schema 子项数量与当前文档集合宽度，以限制重复或指数增长的引用运算。
解析阶段拒绝解码后重复的对象键、不安全整数、非有限数溢出，以及非零值下溢为零。其他小数仍采用 JavaScript IEEE-754 数值，可能发生舍入；本工具不提供任意精度 JSON 运算。需要精确保存的大型标识符应使用字符串并配套相应 schema。
最多返回 100 条诊断，每个路径最多 2,048 个字符。截断提示表示部分细节已省略。报告仅输出路径和关键字，不输出原始值、校验器参数或原始解析异常。路径可能包含可识别个人的属性名，报告并非匿名数据。输入仅在已加载页面中处理，不上传、不持久保存。取消、重新运行、更改输入或离开工具均会终止工作线程。剪贴板副本和下载文件不再受页面控制。这是带有明确边界的本地实现，不宣称覆盖不受限制的全部 JSON Schema 行为。

常见问题

为什么相同 schema 在不同规范版本下结果不同？

关键字语义会演进。Draft 7 忽略 $ref 同级的断言，而 2019-09 和 2020-12 会执行它们。成对示例使用相同的 $ref 与 minLength 及字符串 "ok"：Draft 7 通过，2020-12 在 minLength 处失败。元组语法也不同：旧版本使用 items 数组，2020-12 使用 prefixItems。

format: email 或 date-time 会检查字符串格式吗？

不会。本工具在所有可选版本中都将 format 视为注解。即使字符串不是有效的邮件地址或日期时间，也可能通过。若生产环境启用了格式断言，其结果可能不同，应在该环境另行测试。

文档无效与 schema 无效有什么区别？

文档无效表示已经执行检查，且至少一条断言未通过。schema 无效表示无法解析、未通过元 schema 检查或无法编译。不支持、超时、取消和达到限制是单独的结果，都不能证明文档是否符合其原本的 schema。 unevaluatedItems 和 unevaluatedProperties 不受支持。内置引擎在部分注解交互中可能产生错误结果，因此本工具会明确拒绝它们。需要这两个关键字时，请改用已验证支持相应功能的校验器。三种版本选择对应本工具的有限校验范围，并不代表不受限制的完整词汇支持。同样不支持 $dynamicRef、$dynamicAnchor、$recursiveRef 和 $recursiveAnchor；仍支持普通本地 $ref 的递归引用。本工具仅支持所选规范的有限子集。最多 512 个 schema 对象，每个直接子项列表最多 512 项，文档值数量乘以 schema 对象数量不得超过 200,000。诊断显示各个已评估分支的首个失败，并非所有违规项。每次运行还限制为最多 50,000 个加权校验工作单元，计入直接 schema 子项数量与当前文档集合宽度，以限制重复或指数增长的引用运算。

导出的诊断可以不检查就公开吗？

不可以。报告省略原始值和异常文本，但属性名可能包含姓名、标识符或秘密。分享前应检查文档路径与 schema 路径。空的文档路径表示根节点，JSON Pointer 将 / 转义为 ~1，将 ~ 转义为 ~0。由于引擎解析存在歧义，引用片段中不支持百分号编码的斜杠（%2F）。属性名中的斜杠请使用 JSON Pointer 转义 ~1。引用校验器返回的路径可能相对于被引用的 schema 目标，而非最初的根节点。