JSON Schema 基于 JSON 语法，用于描述 JSON 数据的结构，可用于数据校验、接口文档和测试数据生成等。

JSON 由对象（object）、数组（array）、数字（number）、字符串（string）、布尔值（boolean）和 null 组成。JSON Schema 对这些类型都做了规定。

以下内容基于 Draft 4 规范。

公共属性

常用

  • type：定义数据类型；
  • enum：定义可选值列表；
  • default：定义默认值，不强制校验器实现。

元数据

  • title：标题（可选）;
  • description：描述（可选）;
  • $schema：声明这是一个 schema，值一般为 http://json-schema.org/schema#，也可以为一个指向官网草案版本的链接，例如：http://json-schema.org/draft-06/schema#。

组合验证

  • anyOf：满足列表中任意一个 schema 即通过；
  • allOf：必须同时满足列表中所有 schema；
  • oneOf：仅满足列表中一个 schema 才通过；
  • not：不满足内部 schema 才通过。

验证示例

空 schema

空对象可匹配任意数据：

{}

字符串

{"type": "string"}

可选属性：

  • minLength、maxLength：长度范围；
  • pattern：正则表达式，建议使用 ^...$ 全匹配；
  • format：约定的格式（如 email、uri），实现可选。

数字

number 代表浮点数，integer 代表整数。

{"type": "integer"}

{"type": "number"}

常用属性：

  • multipleOf：必须是该值的倍数；
  • minimum / maximum：范围边界；
  • exclusiveMinimum / exclusiveMaximum：是否排除边界值（Draft 4 中布尔值）。

对象

{
  "type": "object",
  "properties": {
    "name": {"type": "string"},
    "age": {"type": "integer"},
    "gender": {"type": "string", "enum": ["male", "female"]}
  }
}

**默认情况下，object 中不传某个属性或者多传某个属性都能够验证通过。**因此上述 Schema 对 {} 也能验证通过。

附加参数：

  • properties 定义属性
  • additionalProperties
    • True：允许附加属性
    • False：不允许附加属性
    • object：规定附加属性验证，例如 "additionalProperties": { "type": "string" } 规定附加属性必须是字符串。
  • required 一个元素唯一的非空列表（Draft 6 允许为空），规定必传参数；
  • minProperties
  • maxProperties
  • dependencies
    • 属性依赖，例如 "dependencies": {"credit_card": ["billing_address"]}表示，拥有 credit_card 属性时必须拥有 billing_address 属性；
    • Schema 依赖，能够定义依赖变量的类型等，相当于内嵌 schema。
  • patternProperties 使用正则定义的属性列表。可以与 additionalProperties 配合使用，additionalProperties 只定义不希望被正则匹配的属性。

示例：

{
  "type": "object",
  "properties": {
    "credit_card": {
      "type": "number"
    },
    "name": {
      "type": "string"
    }
  },
  "dependencies": {
    "credit_card": {
      "properties": {
        "billing_address": {
          "type": "string"
        }
      },
      "required": [
        "billing_address"
      ]
    }
  },
  "required": [
    "name"
  ]
}

一个 patternProperties 的例子：

{
  "additionalProperties": false,
  "patternProperties": {
    "^I_": {"type": "integer"},
    "^S_": {"type": "string"}
  },
  "type": "object"
}

数组

{"type": "array"}

常用属性：

  • items：
    • 列表验证（单个 schema）：应用于所有元素；
    • 元组验证（数组 schema）：按索引匹配；
  • additionalItems：元组验证时控制多余元素；
  • minItems、maxItems：长度限制；
  • uniqueItems：元素是否唯一。

布尔值与 null

{"type": "boolean"}

仅接受 true、false；

{"type": "null"}

仅接受 null。

复杂结构

重用 schema

使用 $ref 引用已有定义，避免重复书写：

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "definitions": {
    "address": {
      "type": "object",
      "properties": {
        "street_address": {"type": "string"},
        "city": {"type": "string"},
        "state": {"type": "string"}
      },
      "required": ["street_address", "city", "state"]
    }
  },
  "type": "object",
  "properties": {
    "billing_address": {"$ref": "#/definitions/address"},
    "shipping_address": {"$ref": "#/definitions/address"}
  }
}

$ref 取值可以是：

  • 同一 JSON Schema 文件中的定义，以 # 开头；
  • 相对路径 URI，例如 definitions.json#/address；
  • 绝对路径 URI；

递归模式

可以引用自身实现递归，但需避免循环引用导致的无限解析：

{
  "$schema": "http://json-schema.org/draft-06/schema#",
  "definitions": {
    "person": {
      "type": "object",
      "properties": {
        "name": {"type": "string"},
        "children": {
          "type": "array",
          "items": {"$ref": "#/definitions/person"},
          "default": []
        }
      }
    }
  },
  "type": "object",
  "properties": {
    "person": {"$ref": "#/definitions/person"}
  }
}

参考链接