JSON Schema 实用示例：校验常用写法

一分钟理解 JSON Schema

JSON Schema 用来描述 JSON 数据的允许结构与规则。语法校验回答「是不是合法 JSON」；Schema 校验回答「是否符合我们的数据契约」。

下文示例对齐 Draft 2020-12（见 $schema）。请与你使用的校验器支持的草案版本保持一致。

若需复习 JSON 基础，可先读 什么是 JSON？。

最小的 object 示例

Schema — 必填 name（字符串）与 age（整数），tags 可选：

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/schemas/person.min.json",
  "title": "Person",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "name": { "type": "string", "minLength": 1 },
    "age": { "type": "integer", "minimum": 0 },
    "tags": {
      "type": "array",
      "items": { "type": "string" }
    }
  },
  "required": ["name", "age"]
}

合法实例

{ "name": "Asha", "age": 30, "tags": ["beta"] }

不合法实例（缺少 age，且 additionalProperties: false 禁止未知字段 extra）

{ "name": "Asha", "extra": true }

字符串：长度、pattern、format

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "handle": { "type": "string", "pattern": "^[a-z0-9_]{3,20}$" },
    "contact": { "type": "string", "format": "email" },
    "createdAt": { "type": "string", "format": "date-time" }
  },
  "required": ["handle"]
}

提示： 在核心规范里 format 常作为注解；Ajv 等需插件才会按格式校验。未开启时把 format 当作文档约定更安全。

数值：范围与倍数

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "qty": { "type": "integer", "minimum": 1, "maximum": 99 },
    "price": { "type": "number", "minimum": 0, "multipleOf": 0.01 }
  },
  "required": ["qty", "price"]
}

整数用 integer，需要小数时用 number。

enum 与 const

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "role": { "type": "string", "enum": ["admin", "editor", "viewer"] },
    "version": { "const": 1 }
  },
  "required": ["role", "version"]
}

数组：items、长度、唯一性

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "ids": {
      "type": "array",
      "items": { "type": "string", "pattern": "^[A-Z]{3}-[0-9]{4}$" },
      "minItems": 1,
      "maxItems": 10,
      "uniqueItems": true
    }
  },
  "required": ["ids"]
}

anyOf、oneOf、allOf

anyOf — 至少满足一个分支（适合「字符串 或 数字」）：

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "value": {
      "anyOf": [
        { "type": "string", "minLength": 1 },
        { "type": "number" }
      ]
    }
  },
  "required": ["value"]
}

oneOf — 恰好一个分支（注意分支条件不要重叠）。allOf — 合并所有子 schema 的约束。

用 $defs 与 $ref 复用

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$defs": {
    "Email": { "type": "string", "format": "email" }
  },
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "owner": { "$ref": "#/$defs/Email" },
    "billing": { "$ref": "#/$defs/Email" }
  },
  "required": ["owner"]
}

additionalProperties 与 API 契约

在根对象上使用 additionalProperties: false 有助于捕获字段拼写错误。对外 API 通常与明确的 properties、required 一起使用。

常见误区

• • $ref 片段写错或草案不一致会导致无法解析。

• • null 不会自动允许；需要时用 { "type": ["string", "null"] } 等写法。

• • oneOf 分支重叠会出现「匹配多于一个分支」错误。

• • integer 与 number 混用导致小数无法通过整数校验。

在 JSON Work 中实践

• • 将 schema 与数据粘贴到 JSON 校验器，在浏览器本地查看校验结果。

• • 有样例 JSON、想生成初稿 schema 时，可使用 JSON 转 Schema。

生产环境常用 Ajv（JavaScript）或 jsonschema（Python）等；务必核对库对所声明 $schema 草案的支持情况。