JSON Schema 完整指南 - 从入门到精通

引言#

JSON Schema 是一种基于 JSON 的格式，用于描述和验证 JSON 数据的结构。本完整指南将带您从入门到精通，全面掌握 JSON Schema 的语法、类型系统、验证规则和最佳实践。

目录#

JSON Schema 基础
类型系统
验证关键字
组合关键字
格式规范
实战示例

JSON Schema 基础 {#basics}#

什么是 JSON Schema？#

JSON Schema 是一种描述 JSON 数据结构的规范，用于：

验证：确保数据符合预期结构
文档：自动生成数据字典
测试：自动化数据验证测试
IDE 支持：智能提示和自动补全

Schema 基本结构#

1
{
2
  "$schema": "http://json-schema.org/draft-07/schema#",
3
  "title": "用户信息",
4
  "description": "描述用户的基本信息",
5
  "type": "object",
6
  "properties": {
7
    "id": {
8
      "type": "integer",
9
      "description": "用户 ID"
10
    },
11
    "name": {
12
      "type": "string",
13
      "description": "用户姓名"
14
    },
15
    "email": {
16
      "type": "string",
17
      "format": "email",
18
      "description": "用户邮箱"
19
    }
20
  },
21
  "required": ["id", "name", "email"]
22
}

元数据关键字#

1
{
2
  "$schema": "http://json-schema.org/draft-07/schema#",
3
  "$id": "https://example.com/user.schema.json",
4
  "title": "用户 Schema",
5
  "description": "描述用户数据结构",
6
  "default": {},
7
  "examples": [
8
    {
9
      "id": 1,
10
      "name": "John",
11
      "email": "john@example.com"
12
    }
13
  ],
14
  "readOnly": true,
15
  "writeOnly": false
16
}

$ref 引用#

1
{
2
  "$schema": "http://json-schema.org/draft-07/schema#",
3
  "definitions": {
4
    "address": {
5
      "type": "object",
6
      "properties": {
7
        "street": { "type": "string" },
8
        "city": { "type": "string" },
9
        "zip": { "type": "string" }
10
      }
11
    }
12
  },
13
  "type": "object",
14
  "properties": {
15
    "billing": { "$ref": "#/definitions/address" },
16
    "shipping": { "$ref": "#/definitions/address" }
17
  }
18
}

类型系统 {#types}#

基本类型#

1
{
2
  "stringType": { "type": "string" },
3
  "numberType": { "type": "number" },
4
  "integerType": { "type": "integer" },
5
  "booleanType": { "type": "boolean" },
6
  "arrayType": { "type": "array" },
7
  "objectType": { "type": "object" },
8
  "nullType": { "type": "null" }
9
}

多类型#

1
{
2
  "stringOrNumber": {
3
    "type": ["string", "number"]
4
  },
5
  "nullable": {
6
    "type": ["string", "null"]
7
  }
8
}

String 类型详解#

1
{
2
  "string": {
3
    "type": "string",
4
    "minLength": 1,
5
    "maxLength": 100,
6
    "pattern": "^[a-zA-Z]+$",
7
    "format": "email"
8
  }
9
}

常用 format 值：

email: 邮箱地址
uri: URL 地址
date: 日期 (YYYY-MM-DD)
date-time: 日期时间 (ISO 8601)
time: 时间
ipv4: IPv4 地址
ipv6: IPv6 地址
hostname: 主机名
uuid: UUID
uri-reference: URI 引用

Number 类型详解#

1
{
2
  "number": {
3
    "type": "number",
4
    "minimum": 0,
5
    "maximum": 100,
6
    "exclusiveMinimum": 0,
7
    "exclusiveMaximum": 100,
8
    "multipleOf": 5
9
  },
10
  "integer": {
11
    "type": "integer",
12
    "minimum": 1,
13
    "maximum": 10
14
  }
15
}

Array 类型详解#

1
{
2
  "array": {
3
    "type": "array",
4
    "items": {
5
      "type": "string"
6
    },
7
    "minItems": 1,
8
    "maxItems": 10,
9
    "uniqueItems": true,
10
    "contains": {
11
      "type": "string",
12
      "minLength": 1
13
    }
14
  },
15
  "tuple": {
16
    "type": "array",
17
    "items": [
18
      { "type": "string" },
19
      { "type": "number" },
20
      { "type": "boolean" }
21
    ],
22
    "additionalItems": false
23
  }
24
}

Object 类型详解#

1
{
2
  "object": {
3
    "type": "object",
4
    "properties": {
5
      "name": { "type": "string" },
6
      "age": { "type": "integer" },
7
      "email": { "type": "string", "format": "email" }
8
    },
9
    "required": ["name", "age"],
10
    "additionalProperties": false,
11
    "minProperties": 2,
12
    "maxProperties": 5,
13
    "propertyNames": {
14
      "type": "string",
15
      "pattern": "^[a-z]+$"
16
    }
17
  }
18
}

验证关键字 {#validation}#

数值验证#

1
{
2
  "age": {
3
    "type": "integer",
4
    "minimum": 0,
5
    "maximum": 150,
6
    "exclusiveMinimum": 0,
7
    "exclusiveMaximum": 150,
8
    "multipleOf": 1
9
  },
10
  "price": {
11
    "type": "number",
12
    "minimum": 0,
13
    "maximum": 9999.99,
14
    "multipleOf": 0.01
15
  }
16
}

字符串验证#

1
{
2
  "username": {
3
    "type": "string",
4
    "minLength": 3,
5
    "maxLength": 20,
6
    "pattern": "^[a-zA-Z0-9_]+$"
7
  },
8
  "description": {
9
    "type": "string",
10
    "minLength": 10,
11
    "maxLength": 500
12
  },
13
  "email": {
14
    "type": "string",
15
    "format": "email"
16
  }
17
}

数组验证#

1
{
2
  "tags": {
3
    "type": "array",
4
    "minItems": 1,
5
    "maxItems": 10,
6
    "uniqueItems": true,
7
    "items": {
8
      "type": "string",
9
      "minLength": 1
10
    },
11
    "contains": {
12
      "enum": ["important"]
13
    }
14
  }
15
}

对象验证#

1
{
2
  "user": {
3
    "type": "object",
4
    "properties": {
5
      "id": { "type": "integer" },
6
      "name": { "type": "string" },
7
      "email": { "type": "string", "format": "email" }
8
    },
9
    "required": ["id", "name", "email"],
10
    "additionalProperties": false,
11
    "minProperties": 3,
12
    "maxProperties": 10
13
  }
14
}

Enum 验证#

1
{
2
  "status": {
3
    "type": "string",
4
    "enum": ["active", "inactive", "pending"]
5
  },
6
  "priority": {
7
    "type": "integer",
8
    "enum": [1, 2, 3, 4, 5]
9
  },
10
  "role": {
11
    "type": "string",
12
    "enum": ["user", "admin", "moderator"]
13
  }
14
}

Const 验证（Draft-06+）#

1
{
2
  "version": {
3
    "const": "1.0.0"
4
  },
5
  "type": {
6
    "const": "premium"
7
  }
8
}

组合关键字 {#composition}#

allOf（与）#

1
{
2
  "allOf": [
3
    {
4
      "type": "object",
5
      "properties": {
6
        "name": { "type": "string" }
7
      }
8
    },
9
    {
10
      "type": "object",
11
      "properties": {
12
        "age": { "type": "integer" }
13
      },
14
      "required": ["age"]
15
    }
16
  ]
17
}
18
// 结果：必须同时包含 name 和 age，且 age 必填

anyOf（或）#

1
{
2
  "anyOf": [
3
    {
4
      "type": "object",
5
      "properties": {
6
        "email": { "type": "string", "format": "email" }
7
      }
8
    },
9
    {
10
      "type": "object",
11
      "properties": {
12
        "phone": { "type": "string", "pattern": "^\\+?[0-9]+$" }
13
      }
14
    }
15
  ]
16
}
17
// 结果：可以是 email 对象或 phone 对象

oneOf（异或）#

1
{
2
  "oneOf": [
3
    {
4
      "type": "object",
5
      "properties": {
6
        "credit_card": { "type": "string" }
7
      }
8
    },
9
    {
10
      "type": "object",
11
      "properties": {
12
        "paypal": { "type": "string", "format": "email" }
13
      }
14
    }
15
  ]
16
}
17
// 结果：只能是信用卡或 PayPal，不能同时

not（非）#

1
{
2
  "not": {
3
    "type": "object",
4
    "properties": {
5
      "status": { "const": "deleted" }
6
    }
7
  }
8
}
9
// 结果：不能是 status 为 deleted 的对象

if/then/else（条件）#

1
{
2
  "type": "object",
3
  "properties": {
4
    "country": { "type": "string" },
5
    "postal_code": { "type": "string" }
6
  },
7
  "if": {
8
    "properties": {
9
      "country": { "const": "US" }
10
    }
11
  },
12
  "then": {
13
    "properties": {
14
      "postal_code": { "pattern": "^\\d{5}$" }
15
    }
16
  },
17
  "else": {
18
    "properties": {
19
      "postal_code": { "pattern": "^[A-Z0-9]+$" }
20
    }
21
  }
22
}
23
// 结果：美国邮编 5 位数字，其他国家字母数字组合

格式规范 {#formats}#

内置格式#

1
{
2
  "formats": {
3
    "email": { "type": "string", "format": "email" },
4
    "uri": { "type": "string", "format": "uri" },
5
    "date": { "type": "string", "format": "date" },
6
    "date-time": { "type": "string", "format": "date-time" },
7
    "time": { "type": "string", "format": "time" },
8
    "ipv4": { "type": "string", "format": "ipv4" },
9
    "ipv6": { "type": "string", "format": "ipv6" },
10
    "hostname": { "type": "string", "format": "hostname" },
11
    "uuid": { "type": "string", "format": "uuid" },
12
    "uri-reference": { "type": "string", "format": "uri-reference" },
13
    "iri": { "type": "string", "format": "iri" },
14
    "iri-reference": { "type": "string", "format": "iri-reference" },
15
    "regex": { "type": "string", "format": "regex" },
16
    "json-pointer": { "type": "string", "format": "json-pointer" },
17
    "relative-json-pointer": { "type": "string", "format": "relative-json-pointer" }
18
  }
19
}

自定义格式#

1
{
2
  "phone": {
3
    "type": "string",
4
    "pattern": "^\\+?[0-9\\-\\s]+$",
5
    "description": "Phone number in international format"
6
  },
7
  "color": {
8
    "type": "string",
9
    "pattern": "^#[0-9A-Fa-f]{6}$",
10
    "description": "Hex color code"
11
  }
12
}

实战示例 {#examples}#

示例 1：用户 Schema#

1
{
2
  "$schema": "http://json-schema.org/draft-07/schema#",
3
  "title": "用户",
4
  "description": "描述用户账户信息",
5
  "type": "object",
6
  "properties": {
7
    "id": {
8
      "type": "integer",
9
      "description": "用户唯一标识",
10
      "minimum": 1
11
    },
12
    "username": {
13
      "type": "string",
14
      "description": "用户名",
15
      "minLength": 3,
16
      "maxLength": 20,
17
      "pattern": "^[a-zA-Z0-9_]+$"
18
    },
19
    "email": {
20
      "type": "string",
21
      "format": "email",
22
      "description": "用户邮箱"
23
    },
24
    "profile": {
25
      "type": "object",
26
      "properties": {
27
        "firstName": { "type": "string" },
28
        "lastName": { "type": "string" },
29
        "age": { "type": "integer", "minimum": 0 },
30
        "bio": { "type": "string", "maxLength": 500 }
31
      },
32
      "required": ["firstName", "lastName"]
33
    },
34
    "roles": {
35
      "type": "array",
36
      "items": {
37
        "type": "string",
38
        "enum": ["user", "admin", "moderator"]
39
      },
40
      "uniqueItems": true,
41
      "minItems": 1
42
    },
43
    "createdAt": {
44
      "type": "string",
45
      "format": "date-time"
46
    },
47
    "isActive": {
48
      "type": "boolean",
49
      "default": true
50
    }
51
  },
52
  "required": ["id", "username", "email", "createdAt"],
53
  "additionalProperties": false
54
}

示例 2：API 响应 Schema#

1
{
2
  "$schema": "http://json-schema.org/draft-07/schema#",
3
  "title": "API 响应",
4
  "type": "object",
5
  "properties": {
6
    "status": {
7
      "type": "string",
8
      "enum": ["success", "error"]
9
    },
10
    "data": {
11
      "oneOf": [
12
        {
13
          "type": "object",
14
          "properties": {
15
            "items": {
16
              "type": "array",
17
              "items": { "$ref": "#/definitions/item" }
18
            },
19
            "total": { "type": "integer" },
20
            "page": { "type": "integer" }
21
          }
22
        },
23
        {
24
          "type": "object",
25
          "properties": {
26
            "message": { "type": "string" },
27
            "code": { "type": "string" }
28
          }
29
        }
30
      ]
31
    },
32
    "timestamp": {
33
      "type": "string",
34
      "format": "date-time"
35
    }
36
  },
37
  "required": ["status", "data", "timestamp"],
38
  "definitions": {
39
    "item": {
40
      "type": "object",
41
      "properties": {
42
        "id": { "type": "integer" },
43
        "name": { "type": "string" },
44
        "price": { "type": "number", "minimum": 0 }
45
      },
46
      "required": ["id", "name", "price"]
47
    }
48
  }
49
}

示例 3：配置文件 Schema#

1
{
2
  "$schema": "http://json-schema.org/draft-07/schema#",
3
  "title": "应用配置",
4
  "type": "object",
5
  "properties": {
6
    "database": {
7
      "type": "object",
8
      "properties": {
9
        "host": { "type": "string", "format": "hostname" },
10
        "port": { "type": "integer", "minimum": 1, "maximum": 65535 },
11
        "name": { "type": "string", "minLength": 1 },
12
        "user": { "type": "string" },
13
        "password": { "type": "string" },
14
        "ssl": { "type": "boolean", "default": false }
15
      },
16
      "required": ["host", "port", "name", "user", "password"]
17
    },
18
    "server": {
19
      "type": "object",
20
      "properties": {
21
        "host": { "type": "string", "default": "0.0.0.0" },
22
        "port": { "type": "integer", "default": 3000 },
23
        "workers": { "type": "integer", "minimum": 1, "default": 4 }
24
      },
25
      "required": ["port"]
26
    },
27
    "features": {
28
      "type": "object",
29
      "properties": {
30
        "enableCache": { "type": "boolean", "default": true },
31
        "enableLogs": { "type": "boolean", "default": true },
32
        "maxConnections": { "type": "integer", "default": 100 }
33
      }
34
    },
35
    "logging": {
36
      "type": "object",
37
      "properties": {
38
        "level": {
39
          "type": "string",
40
          "enum": ["debug", "info", "warn", "error"],
41
          "default": "info"
42
        },
43
        "file": { "type": "string" },
44
        "maxSize": { "type": "string", "pattern": "^\\d+[KMGT]B$" }
45
      }
46
    }
47
  },
48
  "required": ["database", "server"]
49
}

总结#

本指南涵盖了 JSON Schema 的核心内容：

基础：元数据、$ref 引用
类型：string、number、integer、boolean、array、object、null
验证：数值、字符串、数组、对象、enum、const
组合：allOf、anyOf、oneOf、not、if/then/else
格式：内置格式和自定义格式
实战：用户、API 响应、配置文件

掌握这些知识，您可以设计和验证任何 JSON 数据结构！

相关资源：

JSON Schema Generator 工具 - 在线生成 Schema
JSON Schema 最佳实践 - 设计技巧
JSON Schema 常见问题 - 故障排除
JSON Schema 实战示例 - 实际案例