JSON Schema 入门介绍

JSON Schema

JSON Schema is a vocabulary that allows you to annotate and validate JSON documents.

JSON Schema 定义了一套语法规则来描述 JSON 元数据,这些元数据通过关键字来定义 JSON 数据需要满足的规范,如:成员、结构、类型、约束等。

格式

JSON Schema 需要遵循 JSON 规范,格式如下示例。

1
2
3
4
5
6
7
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "http://example.com/product.schema.json",
"title": "Product",
"description": "A product in the catalog",
"type": "object"
}

JSON Scheme 主要包含以下几个字段:

字段名描述
$schema声明当前 Schema 依据的标准规范
$id当前 Schema 唯一标识,与其它 Schema 进行区分
title标题
description描述
type描述属性的类型
properties声明包含的属性
required声明必须的属性

类型

Schema 通过 Type 关键字来定义数据的基本类型,所支持的类型包括:objectnumberstringarraybooleannull

1
2
3
{ "type": "number" }

{ "type": "number" | "string" }

约束

Schema 在定义数据的类型的同时,也可以同时定义类型的约束,不同类型可以定义不同的约束。

  • String

    • 限制最小、最大的长度

      1
      2
      3
      4
      5
      {
      "type": "string",
      "minLength": 2,
      "maxLength": 3
      }
    • 正则校验

      1
      2
      3
      4
      {
      "type": "string",
      "pattern": "^(\\([0-9]{3}\\))?[0-9]{3}-[0-9]{4}$"
      }
    • 格式校验

      1
      2
      3
      4
      {
      "type": "string",
      "format": "email"
      }
      1
      2
      3
      4
      5
      6
      7
      8
      "format": "email" // 邮箱

      "format": "date-time" // 2018-11-13T20:20:39+00:00
      "format": "date" // 2018-11-13
      "format": "time" // 20:20:39+00:00

      "format": "ipv4"
      "format": "ipv6"
  • Number

    • 倍数

      约束数值必须为 X 的倍数

      1
      2
      3
      4
      {
      "type" : "number",
      "multipleOf" : 10 // 10 的倍数
      }
    • 限制范围

      • x ≥ minimum
      • x > exclusiveMinimum
      • x ≤ maximum
      • x < < exclusiveMaximum
      1
      2
      3
      4
      5
      6
      // 限制 [0, 100) 之间
      {
      "type": "number",
      "minimum": 0,
      "exclusiveMaximum": 100
      }
  • object

    • 包含的属性

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      {
      "type": "object",
      "properties": {
      "number": { "type": "number" },
      "street_name": { "type": "string" },
      "street_type": {
      "type": "string",
      "enum": ["Street", "Avenue", "Boulevard"]
      }
      }
      }
    • 是否允许额外的属性

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      {
      "type": "object",
      "properties": {
      "number": { "type": "number" },
      "street_name": { "type": "string" },
      "street_type": {
      "type": "string",
      "enum": ["Street", "Avenue", "Boulevard"]
      }
      }
      "additionalProperties": false
      }
      1
      2
      3
      {
      "additionalProperties": { "type": "string" } // 只需要额外的 string 类型的属性
      }
    • 必须的属性

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      {
      "type": "object",
      "properties": {
      "number": { "type": "number" },
      "street_name": { "type": "string" },
      "street_type": {
      "type": "string",
      "enum": ["Street", "Avenue", "Boulevard"]
      }
      },
      "required": ["name", "email"]
      }
    • 属性名称限制

      1
      2
      3
      4
      5
      6
      {
      "type": "object",
      "propertyNames": {
      "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
      }
      }
    • 属性数量限制

      1
      2
      3
      4
      5
      {
      "type": "object",
      "minProperties": 2,
      "maxProperties": 3
      }
  • array

    • 数组元素类型限制

      1
      2
      3
      4
      5
      6
      {
      "type": "array",
      "items": {
      "type": "number" // ["number", "string"]
      }
      }
      1
      2
      3
      4
      5
      6
      {
      "type": "array",
      "contains": {
      "type": "number"
      }
      }
      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      19
      20
      // 逐项校验类型
      {
      "type": "array",
      "items": [
      {
      "type": "number"
      },
      {
      "type": "string"
      },
      {
      "type": "string",
      "enum": ["Street", "Avenue", "Boulevard"]
      },
      {
      "type": "string",
      "enum": ["NW", "NE", "SW", "SE"]
      }
      ]
      }
    • 是否允许额外的元素

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      19
      20
      {
      "type": "array",
      "items": [
      {
      "type": "number"
      },
      {
      "type": "string"
      },
      {
      "type": "string",
      "enum": ["Street", "Avenue", "Boulevard"]
      },
      {
      "type": "string",
      "enum": ["NW", "NE", "SW", "SE"]
      }
      ],
      "additionalItems": false
      }
      1
      2
      3
      {
      "additionalItems": { "type": "string" }
      }
    • 数组长度限制

      1
      2
      3
      4
      5
      {
      "type": "array",
      "minItems": 2,
      "maxItems": 3
      }
    • 是否允许重复项

      1
      2
      3
      4
      {
      "type": "array",
      "uniqueItems": true
      }
  • 组合限制

    • allof:所有条件都要满足

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      19
      20
      21
      22
      {
      "definitions": {
      "address": {
      "type": "object",
      "properties": {
      "street_address": { "type": "string" },
      "city": { "type": "string" },
      "state": { "type": "string" }
      },
      "required": ["street_address", "city", "state"]
      }
      },

      "allOf": [
      { "$ref": "#/definitions/address" },
      { "properties":
      {
      "type": { "enum": [ "residential", "business" ] }
      }
      }
      ]
      }
    • anyof:满足其中一项或多项

      1
      2
      3
      4
      5
      6
      {
      "anyOf": [
      { "type": "string" },
      { "type": "number" }
      ]
      }
    • oneof:只满足其中一项

      1
      2
      3
      4
      5
      6
      {
      "oneOf": [
      { "type": "number", "multipleOf": 5 },
      { "type": "number", "multipleOf": 3 }
      ]
      }
    • not :一项都不满足

      1
      { "not": { "type": "string" } }

参考