不期速成 日拱一卒
2021-04-25

JSONSchema常用关键字语法手册

我们在实际开发过程中，在开发对外开放接口或者公共模块方法，通常会对入参进行校验，当入参为JSON (Dict)类型数据时，可能需要写几十行代码来校验其数据格式是否符合正确，使得代码冗余度高，可读性差。

有一种更优雅的方式可以实现JSON数据的校验----JSONSchema，其是基于JSON格式、用于定义JSON数据结构以及数据校验规则，JSON Schema同时还提供anyOf、allOf、oneOf、not、const组合规则，便于我们组合出更加严格的校验规则，满足于复杂JSON入参的校验。

各种主流的编程语言基本都提供了对JSONSchema的第三方库支持，比如Python就有jsonschema，可以通过pip install jsonschema安装。

# 快速了解

我们以Python的jsonschema库为例进行一个简单的示例，让你快速了解JSONSchema是怎么应用的。

from jsonschema import validate

# 定义一个JSON数据的JSONSchema
student_schema = {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "student information",
    "description": "some information about test",
    "type": "object",
    "properties": {
        "id": {
            "title": "id",
            "description": "Students' id",
            "type": "integer"
        },        
        "name": {
            "title": "name",
            "description": "Students' name",
            "const": "Tony"
        },
        "score": {
            "description": "Students' scores",
            "type": "number",
            "maximum": 100,
        },
        
        "hobby": {
            "description": "Students' hobby",
            "type": "array"
        }
    },
    "required": [
        "name", "score", "hobby"
    ]
}

# 测试的JSON数据
test_data = {
    "name": "Tony",
    "score": "99",
    "hobby": ["basketball", "football"]
}

validate(instance=test_data, schema=student_schema)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

输出信息如下：

image-20210425140654434

上述代码示例中，表示对 test_data 依据 student_schema 数据结构以及数据校验规则定义进行验证，其中约束了test_data 必须满足以下要求：

  • test_data 中必须包含 "name", "grade", "hobby" 一级属性/字段(key)。
  • test_data 中若有id 一级属性/字段(key)，则其数据类型必须是整数。
  • test_data 中若有name 一级属性/字段(key)，则其数据值必须等于Tony。
  • test_data 中若有grade 一级属性/字段(key)，则其数据类型必须是整数或浮点数,且最大值不超过100。
  • test_data 中若有hobby 一级属性/字段(key)，则其数据类型必须是列表。

# JSON Schema 常用关键字汇总

关键字 描述
$schema 说明该JSON Schema文件遵循的规范和使用的版本，非必须。
id 说明该JSON schema的唯一id标识，方便后续引用，非必须。
title 说明该JSON Schema 的标题，非必须。
description 说明该JSON Schema 的描述信息，非必须。
type 说明待校验元素的类型（例如，最外层的type表示待校验的是一个JSON对象（object），内层type分别表示待校验的元素类型，即：整数（integer），字符串（string），数字（number），布尔值（boolean）、对象（object）、数组（array）、null）。
properties 说明待校验的JSON对象中，可能有哪些属性/字段（key），以及当对应属性/字段（key）存在时，其value的限制条件。
required 说明待校验的JSON对象中，必须存在的属性/字段（key）该关键字的值是一个数组，非必须。
minimum 用于约束取值范围，表示取值范围应该大于或等于minimum，非必须。
exclusiveMinimum 用于约束取值范围，表示取值范围只能大于minimum，非必须。
maximum 用于约束取值范围，表示取值范围应该小于或等于maximum，非必须。
exclusiveMaximum 用于约束取值范围，表示取值范围只能小于maximum，非必须。
multipleOf 用于约束取值，表示取值必须能够被multipleOf所指定的值整除，非必须。
maxLength 用于约束字符串类型数据的最大长度，非必须。
minLength 用于约束字符串类型数据的最小长度，非必须。
dependencies 用于约束属性/字段（key）的依赖关系。例如，“dependencies”:{ “gender”:[“age”] } 。表示：gender是依赖于age存在的，age字段不存在但存在gender字段是会报错的，非必须。
pattern 使用正则表达式约束字符串类型数据，非必须。
multipleOf 用于约束number类型数据的倍数。例如：{ “type”: “number”, “multipleOf”: 2 }，即 number 类型数据必须是2的倍数，非必须。
not 用于约束取值取反。例如：{ “not”: { “type”: “integer” } }，即非整数，非必须。
oneof 用于约束取值满足下列限制的其中一个，例如：{“oneOf”: [{ “type”: “number”, “multipleOf”: 2 },{ “type”: “number”, “multipleOf”: 3 }]} ，表示 number类型的数值 要么是2的倍数，要么是3的倍数，非必须。
allof 用于约束取值都要满足下列限制，例如：{“allOf”: [{ “type”: “number”, “multipleOf”: 2},{ “type”: “number”, “multipleOf”: 3 }]}，表示 number类型的数值 既是2的倍数，又是3的倍数，非必须。
uniqueItems 用于约束数组里面的元素是否唯一，布尔值，非必须。
minProperties 用于约束object里面的最小字段个数，非必须。
maxProperties 用于约束object里面的最大字段个数，非必须。
maxItems 用于约束数组里面的元素最大个数，非必须。
minItems 用于约束数组里面的元素最小个数，非必须。
minLength 用于约束字符串类型数据的最小长度，非必须。
maxLength 用于约束字符串类型数据的最大长度，非必须。

# JSONSchema语法详解

$schema 关键字

$schema 关键字用于指定JSON Schema版本信息，该属性的值必须使用官方提供的版本。

通常推荐使用最新的语法版本：http://json-schema.org/draft-07/schema#

title 与 description 关键字

title 与 description关键字是用来描述对应的待校验 JSON元素的标题和详细描述信息，可以用于最外层对整个JSON对象进行描述，也可以对其中包含的元素进行描述。

type 关键字

该关键字用于限定待校验JSON元素所对应的数据类型，例如，示例中最外层的type关键字值为object，即表示待校验JSON数据为一个JSON对象，而name下的type关键字值为string，即表示待校验JSON对象中的name数据类型为string。

假如实际传入JSON 的name类型不为string，将抛出 jsonschema.exceptions.ValidationError 异常。

type 常见类型对应Python 中的数据类型

type 取值 对应Python中的数据类型
object Object/dict
array list
integer int
number float / int
null None
boolean boolean
string string

下面，我们会结合当type为不同类型，涉及到的关键字用法。

# 当type 取值为object（JSON）

当type 取值为object（JSON）时，涉及到如下关键字：

  • properties
  • required
  • minProperties、maxProperties
  • propertyNames
  • dependencies
  • patternProperties
  • additionalProperties

# properties 关键字

用于说明待校验的JSON对象中，可能有哪些一级属性/字段（key），以及当对应属性/字段（key）存在时，其value的限制条件。

如下示例，表示当待校验的JSON中存在grade属性/字段时，grade的值必须为number类型，最大值不超过100。

"properties": {
        "id": {
            "description": "Students' id",
            "type": "integer",
            # 设定 minimum 为0 则传入值必须大于等于0
            "minimum": 0
        },
        "score": {
            "type": "number",
            # 设定 maximum 为100, 则传入值必须小于等于 100
            "maximum": 100,
            # 设定 maximum 为True ,则传入值必须小于100
            "exclusiveMinimum": True
        }
    }
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# required 关键字

说明待校验的JSON对象中，必须存在的一级属性/字段（key），该关键字的值是一个数组，数组中的元素必须是字符串，而且必须是唯一的。

如下示例，表示待校验的JSON中的属性/字段（key）必须包含"name", "score", "hobby"。

"required": [
    "name", 
    "score", 
    "hobby"
    ]
1
2
3
4
5

# minProperties、maxProperties 关键字

用于限制待校验JSON对象中一级属性/字段（key）的数量限制，minProperties、maxProperties的值都是非负整数。

如下示例，表示限制待校验的JSON对象的一级属性/字段（key）的最大个数为3，最小个数为1。

# 限制一个JSON对象的一级属性/字段（key）的最小个数为1    
"minProperties": 1,
    
# 限制一个JSON对象的一级属性/字段（key）的最大个数为3    
"maxProperties": 3
1
2
3
4
5

# propertyNames 关键字

该关键字的值是一个JSON Schema，约束一级属性/字段（key）的名字，需满足正则匹配。

如下示例，表示限制待校验的JSON对象的一级属性/字段（key）的名字需要满足"^[a-z_]" 正则校验。

"propertyNames": {  
    "pattern": "^[a-z_]" 
}
1
2
3

# patternProperties 关键字

patternProperties关键字的值是一个JSON对象，该JSON对象的每一个一级key都是一个正则表达式，value都是一个JSON Schema。

只有当待校验JSON对象中的一级属性/字段（key），通过与之匹配的patternProperties中的一级正则表达式，对应的JSON Schema的校验，才算校验通过。

如下示例，待校验JSON对象中，所有以i开头的一级属性/字段（key）的value都必须是integer，所有以g开头的一级属性/字段（key）的value都必须是number。

"patternProperties": {
        "^i": {
            "type": "integer"
        },
        "^g": {
            "type": "number"
        }
}
1
2
3
4
5
6
7
8

# additionalProperties 关键字

当additionalProperties关键字的值为布尔值时，表示待校验JSON对象中只能出现schema定义的属性/字段，不允许出现额外属性/字段。

{"additionalProperties": False }
1

当additionalProperties关键字的值为JSON Schema时，表示待校验JSON对象中存在，既没有在properties中被定义，又没有在patternProperties中被定义的属性/字段（key）时，其必须通过additionalProperties的校验。

"additionalProperties":{
    "type": "array"
}
1
2
3

# dependencies 关键字

该关键字的值是一个JSON Schema，表示待校验JSON对象中属性/字段（key）的依赖关系，如下：

"dependencies": {
        "name": ["id"],
}
1
2
3

可以理解为：

  • 验证通过：不存在id也不存在name
  • 验证不通过：不存在id且存在name
  • 验证通过：存在id且不存在name

# 完整示例

student_schema = {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "title": "student information",
    "description": "some information about test",
    "type": "object",
    "properties": {
        "id": {
            "description": "Students' id",
            "type": "integer",
            # 设定 minimum 为0 则传入值必须大于 0
            "minimum": 0
        },
        "name": {
            "title": "name",
            "description": "Students' name",
            "type": "string"
        },
        "score": {
            "type": "number",
            # 设定 maximum 为100, 则传入值必须小于等于100
            "maximum": 100,
            # 设定 maximum 为True, 则传入值必须小于100
            "exclusiveMinimum": True
        },
        "hobby": {
            "description": "Students' hobby",
            "type": "array"
        }
    },
    "required": [
        "name", "score", "hobby"
    ],
    "maxProperties": 10,
    "patternProperties": {
            "^id": {
                "type": "integer"
            }
    },
    "additionalProperties":{
        "type": "array"
    },
    "dependencies": {
            "name": ["id"],
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

# 当type 取值为array（list）

当type 取值为object（array）时，涉及到如下关键字：

  • items
  • additionalItems
  • minItems
  • maxItems
  • uniqueItems
  • contains

# items 关键字

该关键字的值是一个有效的JSON Schema或者一组有效的JSON Schema。items用于规定在数组中对应索引位置上应该满足的校验逻辑，只有待校验JSON数组中的所有元素均通过校验，整个数组才算通过校验。

如下示例，表示待校验JSON数组的元素都是string类型，且最小可接受长度是10。

{
   "type": "array",
   "items": {
     "type": "string",
     "minLength": 10 
   }
}
1
2
3
4
5
6
7

若items 中定义的数量和待校验JSON数组中元素的数量不一致时，则采用 “取小原则” 。即：

  • 若items定义的JSON Schema数量大于待校验JSON数组元素数量，则只校验待校验JSON数组的元素是否符合items中对应索引位置的规则约束。
  • 若items定义的JSON Schema数量小于待校验JSON数组元素数量，则只待校验JSON数据对应元素索引能够在items中JSON Schema中取到值的元素是否符合规则约束。

这种场景比较绕，这里举个例子，items的值如下：

{
    "type": "array",
    "items": [
        {
            "type": "string",
            "minLength": 5
        },
        {
            "type": "number",
            "minimum": 5
        },
        {
            "type": "string"
        }
    ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

上面的JSON Schema指出了待校验JSON数组中对应索引位置元素应该满足的条件，即待校验数组的第一个元素是string类型，且最小长度大于5；数组的第二个元素是number类型，最小值大于5；数组的第三个元素是string 类型。

如下示例，下面这两个JSON数组验证不通过。

["python", 6]
["python", 6, "test", 9527]
1
2

如下示例，下面这两个JSON数组验证不通过。

["py", 5]
["python", 3, "test", 9527]
1
2

# additionalItems 关键字

当additionalItems 关键字的值取值为布尔值时，如为False 时，表示不允许存在额外元素。

{
    "type": "array",
    "items": [
        {
            "type": "string",
            "minLength": 5
        },
        {
            "type": "number",
            "minimum": 5
        },
        {
            "type": "string"
        }
    ],
    "additionalItems": False
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

如下示例，该JSON数组验证不通过。

["basketball", 5, "ball", 1]
1

当additionalItems关键字的值为一组有效的JSON Schema的时候，表示超出items中JSON Schema总数量之外的待校验JSON数组中的剩余的元素应该满足的校验逻辑。

当items的值为一组有效的JOSN Schema的时候，一般和additionalItems关键字组合使用，items用于规定对应位置上应该满足的校验逻辑，而additionalItems用于规定超出items校验范围的所有剩余元素应该满足的条件。

如下示例，表示待校验JSON数组第一个元素是string类型，且可接受的最小长度为5个字符，第二个元素是number类型，且可接受的最小值为5，数组的第三个元素是string类型，剩余的其他元素是number类型，且可接受的最小值为10。

{
    "type": "array",
    "items": [
        {
            "type": "string",
            "minLength": 5
        },
        {
            "type": "number",
            "minimum": 5
        },
        {
            "type": "string"
        }
    ],
    "additionalItems": {
        "type": "number",
        "minimum": 10
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

如下示例，下面 JSON数组则不能通过校验。

["python", 3, "test", 9527, "schema"]
1

# minItems、maxItems 关键字

minItems、maxItems 关键字的值都是非负整数。指定了待校验JSON数组中元素的属性限制，minItems指定了待校验JSON数组可以接受的最少元素个数，而maxItems指定了待校验JSON数组可以接受的最多元素个数。

如下示例，表示限制一个JSON数组的元素的最大个数不超过10，最小个数不低于2，则JSON Schema如下：

"minItems": 10,
"maxItems": 2
1
2

# uniqueItems 关键字

uniqueItems 关键字的值是一个布尔值，当该关键字的值为true时，表示待校验JSON数组中的所有元素都具有唯一性

"uniqueItems": true
1

# 完整示例

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

# 当type 取值为integer 或number

当type 取值为integer 或number 时，涉及到如下关键字：

  • multipleOf
  • maximum、exclusiveMaximum
  • minimum、exclusiveMinimum

其中integer 对应Python 中的int 类型，而number 对应Python 中的int 或float 类型。

# multipleOf 关键字

multipleOf 关键字的值是一个大于0的number，即可以是大于0的整数，也可以是大于0的浮点数，表示只有待校验的值能够被该关键字的值整除。

如下示例，表示待校验的值需被2整除。

{
    "type": "integer",
    "multipleOf": 2
}
1
2
3
4

# maximum 关键字

maximum 关键字的值是一个number，即可以是整数，也可以是浮点数。

maximum 关键字规定了待校验元素可以通过校验的最大值，即传入的值必须小于等于maximum 。

如下示例，表示待校验的值需小于等于5。

{
    "type": "integer",
    "maximum ": 5
}
1
2
3
4

# exclusiveMaximum 关键字

exclusiveMaximum 关键字的值是一个number。exclusiveMaximum 关键字和maximum 一样，规定了待校验元素可以通过校验的最大值，不同的是待校验元素不能等于exclusiveMaximum 指定的值。

如下示例，表示待校验元素需小于100。

{
    "type": "number",
    #  设定 exclusiveMaximum为100, 则传入值是小于100
    "exclusiveMaximum": 100
}
1
2
3
4
5

# minimum、exclusiveMinimum 关键字

minimum、exclusiveMinimum 关键字的用法和含义与maximum、exclusiveMaximum 相似。唯一的区别在于，一个约束了待校验元素的最小值，一个约束了待校验元素的最大值。

如下示例，表示待校验元素需大于100。

{
    "type": "number",
    #  设定 maximum 为10 则传入值必须大于等于10
    #  "minimum": 10,
    #  设定 exclusiveMaximum为10,则传入值是大于10
    "exclusiveMinimum ": 10
}
1
2
3
4
5
6
7

# 完整示例

{ "type": "number", "multipleOf": 2.0, "exclusiveMaximum": 12.5, "exclusiveMinimum": 2.5 }

# 当type 取值为string

当type 取值为string 时，将涉及到下列关键字：

  • maxLength
  • minLength
  • pattern
  • format

# maxLength 关键字

maxLength 关键字的值是一个非负整数。该关键字规定了待校验JSON元素可以通过校验的最大长度，即待校验JSON元素的最大长度必须小于或者等于该关键字的值。

"maxLength": 5
1

# minLength 关键字

minLength关键字的值是一个非负整数。该关键字规定了待校验JSON元素可以通过校验的最小长度，即待校验JSON元素的最小长度必须大于或者等于该关键字的值。

"minLength": 2
1

# pattern 关键字

pattern关键字的值是一个正则表达式。只有待校验JSON元素符合该关键字指定的正则表达式，才算通过校验。

 "pattern": "^[A-Z]+$"
1

# 当type取值为任一类型

当type 取值为任意类型时，都可能涉及到下列关键字：：

  • enum
  • const
  • allOf、anyOf、oneOf
  • not

# enum 关键字

enum 关键字的值是一个数组，该数组至少要有一个元素，且数组内的每一个元素都是唯一的。

如下示例，表示待校验的JSON元素与enum关键字数组中的某一个元素相同，则校验通过，enum关键字数组中的元素值可以是任何值，包括null。例如：

{
    "type": "number",
    "enum": [2, 3, null, "hello"]
}
1
2
3
4

# const 关键字

const 关键字的值可以是任何值，包括null。如果待校验的JSON元素的值与const关键字指定的值相同，则通过校验。

如下示例，表示只有待校验JSON元素等于const关键字的值 Jon 时，则校验通过。

{"const": "Jon"}
1

# allOf 关键字

allOf 关键字的值是一个非空数组，数组里面的每个元素都必须是一个有效的JSON Schema。

如下示例，表示只有待校验JSON元素通过allOf关键字数组中所有的JSON Schema校验，则校验通过。

{
  "allOf": [
    {"type": "string"},
    {"maxLength": 5}
  ]
}
1
2
3
4
5
6

# anyOf 关键字

anyOf 关键字的值是一个非空数组，数组里面的每个元素都必须是一个有效的JSON Schema。

如下示例，表示待校验JSON元素能够通过anyOf关键字数组中的任何一个JSON Schema校验，则校验通过。

{
  "anyOf": [
    {"type": "string", "maxLength": 5},
    {"type": "number", "minimum": 0}
  ]
}
1
2
3
4
5
6

# oneOf 关键字

oneOf 关键字的值是一个非空数组，数组里面的每个元素都必须是一个有效的JSON Schema。

如下示例，表示待校验JSON元素能且只能通过oneOf关键字数组中的某一个JSON Schema校验，则校验通过。若不通过任何一个校验或通过两个及以上的校验，则校验不通过。

{
 "type": "number",
 "oneOf": [
  { "multipleOf": 5},
  { "multipleOf": 3}
 ]
}
1
2
3
4
5
6
7

# not 关键字

not 关键字的值是一个 JSON Schema。

如下示例，表示只有待校验JSON元素不能通过not 关键字指定的JSON Schema校验的时候，则校验通过。

{
  "not": {
    "type": "string"
  }
}
1
2
3
4
5

# 当type 关键字为一个数组

这里需要特别注意的是，type 关键字的值除了可以是string，也可以是一个数组。

如果type 关键字的值是一个数组，则数组中的元素都必须是string，且其取值被限定为null、boolean、object、array、number、string、integer，只要带校验JSON元素是其中的一种，则校验通过。

# 鸣谢

姜越整理文档资料

#JSON
上次更新: 7/26/2026, 3:17:15 PM
RobotFramework字符转译之坑
根据JSON Schema生成JSON样例数据

← 根据JSON Schema生成JSON样例数据→

最近更新
01
测试覆盖度量全景图
 11-30
02
Prism测试覆盖度量
 11-30
03
AITDBClient使用文档
 11-15
更多文章>
Theme by Vdoing | Copyright © 2021-2026 toddlerya | MIT License