什么是 JSON Schema 验证？

JSON Schema 验证是检查 JSON 文档是否符合 JSON Schema 中定义的一组结构和值约束的过程。Schema 本身是一个 JSON 文档，描述数据的预期结构：哪些属性是必填的、它们的类型要求、数字的允许范围、字符串模式、数组长度等。JSON Schema 规范由 json-schema.org 维护，并以 IETF 草案的形式发布，Draft 7 和 Draft 2020-12 是目前应用最广泛的版本。

普通 JSON 验证只检查语法（括号是否匹配？字符串是否加引号？），而 Schema 验证则更进一步。它回答如下问题：这个 API 的响应是否始终包含整数类型的 "id" 字段？"status" 字段是否属于三个允许值之一？嵌套对象的结构是否正确？这类结构验证能捕获语法检查完全漏掉的错误——因为语法合法的 JSON 对于你的应用来说仍可能是语义错误的。

JSON Schema 广泛用于 OpenAPI/Swagger 定义、配置文件验证、表单验证、数据库文档约束以及自动化测试。Ajv（JavaScript）、jsonschema（Python）和 check-jsonschema（CLI）等工具实现了该规范，使你可以通过编程方式验证数据。这个在线验证器让你无需安装任何库，只需粘贴 Schema 和数据文档，即可即时检查是否符合规范。

为什么使用在线 JSON Schema 验证器？

手动编写 Schema 并调试验证错误既耗时又繁琐。在线 JSON Schema 验证器能即时反馈数据是否符合 Schema，并通过清晰的错误信息精确指出失败的属性。

⚡

即时验证反馈

粘贴 Schema 和数据，实时查看验证结果。每个错误都会显示 JSON 路径和具体失败的约束，让你无需翻阅验证库输出即可定位并修复问题。

🔒

隐私优先，纯浏览器处理

你的 JSON 数据永远不会离开浏览器。所有验证均在本地 JavaScript 中运行，无服务器、无日志、无数据留存。对于包含内部 API 描述或专有字段名的 Schema 同样安全。

🎯

支持草案版本的验证

验证器支持 Draft 7 的 Schema 关键字，包括 type、required、properties、enum、pattern、minimum/maximum、items、anyOf、oneOf、allOf 和 additionalProperties。在将 Schema 接入构建流水线或测试套件之前，可在此处先行测试。

📋

无需注册或安装

打开页面，粘贴 JSON，即可验证。无需 npm install、pip 包或 Docker 镜像。在无法安装开发工具的机器上需要快速检查 Schema 时尤为实用。

JSON Schema 验证的使用场景

API 契约测试

根据 OpenAPI 规范中定义的 Schema 验证 API 响应。在上线前捕获破坏性变更，例如字段从整数类型变为字符串类型。

配置文件校验

在提交之前，检查 CI/CD 流水线、Kubernetes 清单或应用配置的 JSON 配置文件是否符合预期的 Schema，防止因缺失或拼写错误的键导致部署失败。

DevOps 流水线门控

将 Schema 验证作为 CI 步骤，拒绝违反契约的 payload。适用于 Terraform 变量文件、GitHub Actions 输入，或任何自动化系统消费的结构化 JSON。

质量保障与测试数据审查

验证测试夹具和模拟数据文件是否符合应用程序所期望的 Schema。测试数据不匹配是误报测试结果的常见根源。

数据管道入口验证

在数据管道的入口处验证传入的 JSON 记录。Schema 验证在数据到达数据仓库之前过滤掉格式异常的事件，降低下游清洗成本。

学习 JSON Schema 语法

交互式地探索 Schema 关键字。编写一个 Schema，粘贴测试数据，观察哪些约束通过或失败。比每次都编写脚本并从终端运行要高效得多。

JSON Schema 关键字参考

JSON Schema 由各类关键字构成，每个关键字对被验证的数据施加一项约束。下表列出了 Draft 7 及后续版本中最常用的关键字。同一 Schema 对象中可以组合使用多个关键字。

关键字	用途	示例
type	Restricts the data type	"type": "string"
properties	Defines expected object keys and their schemas	"properties": { "name": { "type": "string" } }
required	Lists mandatory properties	"required": ["id", "name"]
items	Schema for array elements	"items": { "type": "number" }
enum	Restricts value to a fixed set	"enum": ["active", "inactive"]
pattern	Regex constraint on strings	"pattern": "^[A-Z]{2}\\d{4}$"
minimum / maximum	Numeric range bounds	"minimum": 0, "maximum": 100
minLength / maxLength	String length bounds	"minLength": 1, "maxLength": 255
$ref	Reuses another schema by URI	"$ref": "#/$defs/address"
additionalProperties	Controls extra keys in objects	"additionalProperties": false
anyOf / oneOf / allOf	Combines multiple schemas logically	"anyOf": [{ "type": "string" }, { "type": "null" }]
if / then / else	Conditional schema application	"if": { "properties": { "type": { "const": "email" } } }

JSON Schema 草案对比：Draft 7 vs 2019-09 vs 2020-12

JSON Schema 经历了多个草案版本。Draft 7（2018 年发布）在工具链中拥有最广泛的支持。Draft 2019-09 引入了 $defs（替代 definitions）、unevaluatedProperties 和 $recursiveRef。Draft 2020-12（最新稳定版）将 $recursiveRef 替换为 $dynamicRef，并引入了 prefixItems 用于元组验证。选择草案版本时，请确认你的验证库是否支持。Ajv 支持全部三个草案；Python 的 jsonschema 库自 4.0 版起支持至 2020-12。

特性	Draft 7	Draft 2019-09	Draft 2020-12
$schema URI	draft-07/schema#	2019-09/schema	2020-12/schema
if / then / else	Yes	Yes	Yes
$defs (definitions)	definitions	$defs	$defs
$ref alongside keys	No (sibling ignored)	Yes	Yes
$dynamicRef	No	No ($recursiveRef)	Yes
prefixItems	No (use items array)	No (use items array)	Yes
unevaluatedProperties	No	Yes	Yes
$vocabulary	No	Yes	Yes

代码示例

以下示例演示如何通过编程方式用各语言主流库对 JSON 进行 Schema 验证。

JavaScript (Ajv)

import Ajv from 'ajv';

const ajv = new Ajv();

const schema = {
  type: 'object',
  properties: {
    name: { type: 'string', minLength: 1 },
    age: { type: 'integer', minimum: 0 },
    email: { type: 'string', format: 'email' }
  },
  required: ['name', 'email'],
  additionalProperties: false
};

const data = { name: 'Alice', age: 30, email: 'alice@example.com' };

const validate = ajv.compile(schema);
const valid = validate(data);
console.log(valid);          // → true
console.log(validate.errors); // → null

// Invalid data — missing required "email"
validate({ name: 'Bob', age: 25 });
console.log(validate.errors);
// → [{ instancePath: '', keyword: 'required', params: { missingProperty: 'email' } }]

Python (jsonschema)

from jsonschema import validate, ValidationError

schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string", "minLength": 1},
        "age": {"type": "integer", "minimum": 0},
        "tags": {
            "type": "array",
            "items": {"type": "string"},
            "uniqueItems": True
        }
    },
    "required": ["name"]
}

# Valid data
validate(instance={"name": "Alice", "age": 30, "tags": ["admin"]}, schema=schema)
# → No exception raised

# Invalid data — wrong type for "age"
try:
    validate(instance={"name": "Alice", "age": "thirty"}, schema=schema)
except ValidationError as e:
    print(e.message)
    # → 'thirty' is not of type 'integer'
    print(e.json_path)
    # → $.age

Go (santhosh-tekuri/jsonschema)

package main

import (
    "fmt"
    "strings"
    "github.com/santhosh-tekuri/jsonschema/v5"
)

func main() {
    schemaJSON := `{
        "type": "object",
        "properties": {
            "id": { "type": "integer" },
            "status": { "enum": ["active", "inactive"] }
        },
        "required": ["id", "status"]
    }`

    compiler := jsonschema.NewCompiler()
    compiler.AddResource("schema.json", strings.NewReader(schemaJSON))
    schema, _ := compiler.Compile("schema.json")

    // Valid data
    data := map[string]interface{}{"id": 1, "status": "active"}
    err := schema.Validate(data)
    fmt.Println(err) // → <nil>

    // Invalid — missing "status"
    bad := map[string]interface{}{"id": 2}
    err = schema.Validate(bad)
    fmt.Println(err) // → validation failed: missing properties: 'status'
}

CLI (check-jsonschema)

# Install via pip
pip install check-jsonschema

# Validate a file against a schema
check-jsonschema --schemafile schema.json data.json
# → ok -- validation done

# Validate against a remote schema (e.g., GitHub Actions workflow)
check-jsonschema --builtin-schema vendor.github-workflows my-workflow.yml

# Validate multiple files at once
check-jsonschema --schemafile schema.json file1.json file2.json file3.json

常见问题

JSON 验证和 JSON Schema 验证有什么区别？

JSON 验证检查字符串是否具有合法的 JSON 语法：括号是否正确嵌套、键是否加引号、是否存在多余逗号。JSON Schema 验证更进一步，检查解析后的 JSON 数据是否符合结构契约：类型是否正确、必填字段是否存在、值是否在允许范围内。Schema 验证的前提是 JSON 本身合法，但语法合法的 JSON 仍可能不通过 Schema 验证。

应该使用哪个 JSON Schema 草案版本？

Draft 7 是最安全的默认选择。它在各语言中的库支持最为广泛，涵盖了大多数项目所需的关键字：type、properties、required、enum、pattern、anyOf、oneOf、allOf 和 $ref。如果需要 prefixItems 用于元组验证、$dynamicRef 用于可扩展 Schema，或 unevaluatedProperties 用于严格对象结构，则可使用 Draft 2020-12。升级前请查阅验证库文档，确认其支持的草案版本。

$ref 在 JSON Schema 中如何工作？

$ref 关键字允许通过 URI 引用另一个 Schema，而无需重复定义。例如 "$ref": "#/$defs/address" 指向同一文档 $defs 节中定义的 Schema；也可以使用 "$ref": "https://example.com/schemas/address.json" 引用外部文件。在 Draft 7 中，$ref 会替换同一对象中的所有同级关键字；在 Draft 2019-09 及之后的版本中，同级关键字与 $ref 并行生效。

anyOf、oneOf 和 allOf 有什么区别？

allOf 要求数据匹配数组中的每一个子 Schema。anyOf 要求至少匹配一个子 Schema。oneOf 要求恰好匹配一个子 Schema，若匹配零个或多个则验证失败。对于可为空的字段，常见写法是 anyOf 配合类型和 null：{"anyOf": [{"type": "string"}, {"type": "null"}]}。当子 Schema 互斥时（如标记联合类型）使用 oneOf。

JSON Schema 能验证嵌套对象和数组吗？

可以。使用 properties 关键字为嵌套对象的键定义 Schema，使用 items 关键字定义数组中每个元素必须满足的 Schema，两者可以任意深度嵌套。对于每个位置具有不同 Schema 的数组（元组），在 Draft 2020-12 中使用 prefixItems，在 Draft 7 中使用数组形式的 items。

我粘贴到此工具的数据会发送到服务器吗？

不会。验证器完全在你的浏览器中使用 JavaScript 运行。你的 JSON 数据和 Schema 不会传输到任何服务器。你可以在使用工具时打开浏览器的网络检查器自行验证。

如何在 CI/CD 流水线中验证 JSON Schema？

可使用 CLI 验证器，如 check-jsonschema（Python/pip）或 ajv-cli（Node.js/npm）。两者都接受 Schema 文件和一个或多个数据文件作为参数。将验证命令添加为 CI 配置中的一个步骤。验证失败时进程以非零退出码结束，从而阻断流水线。对于 GitHub Actions，也可以直接使用 check-jsonschema action。

JSON Schema 验证器