JSON Schema 基础

JSON Schema 是一套描述 JSON 文档规则的词汇表：有哪些字段、类型是什么、取值有何约束。团队用它校验 API 载荷、配置文件与生成数据。

最小示例

下列 schema 描述一个对象：必填字符串 name，可选数字 age：

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "integer", "minimum": 0 }
  },
  "required": ["name"],
  "additionalProperties": false
}

合法实例：

{ "name": "Ada", "age": 30 }

不合法：缺少 name、类型错误，或在 additionalProperties: false 时出现未知字段。

核心关键字

关键字	作用
type	string、number、integer、boolean、array、object、null
properties	对象各字段的结构
required	必填属性名
items	数组元素 schema
enum	允许的枚举值
minLength / maxLength	字符串长度边界

为何需要 schema

• 前后端之间的 契约
• 部署前在 CI 中 自动校验
• 可机器读取的 文档
• OpenAPI 常为请求体引用或内嵌 JSON Schema

校验流程

1. 编写或生成期望载荷的 schema。
2. 用校验库或工具检查 incoming JSON。
3. 遇到真实边界情况时同步演进 schema——它与代码一样需要维护。

Schema 不能替代前面学过的 JSON 语法——它建立在「JSON 已可解析」之上，描述 允许的结构。