Python 使用Schema 实现接口或方法的JSON格式参数的高效、优雅校验

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

本文将介绍一种相对高效简洁且规范的Json 格式入参校验方法 —— JSON Schema，其是基于JSON格式、用于定义JSON数据结构以及数据校验规则，JSON Schema同时还提供anyOf、allOf、oneOf、not、const组合规则，便于我们组合出更加严格的校验规则，满足于复杂JSON入参的校验。

下面，我们将介绍使用 Python jsonschema 模块，借助 JSON Schema的数据结构以及数据校验规则定义，对接口或者公共模块方法入参进行校验，实现数据校验逻辑与业务逻辑的解耦。

安装

pip install jsonschema

JSON Schema 常用关键字细分

我们先通过下面一个简单的JSON Schema示例，初步了解一下 JSON Schema：

from jsonschema import validate, draft7_format_checker
from jsonschema.exceptions import SchemaError, ValidationError

# Json schema：
student_schema = {
    "$schema": "https://json-schema.org/draft/2020-12/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"
        },
        "grade": {
            "description": "Students' scores",
            "type": "number",
            "maximum": 100,
        },
        
        "hobby": {
            "description": "Students' hobby",
            "type": "array"
        }
    },
    "required": [
        "name", "grade", "hobby"
    ]
}

# json 数据
test_data = {
    "name": "Tony",
    "grade": 99,
    "hobby": ["basketball", "football"]
}

# 验证
try:
    validate(instance=json_data, schema=student_schema, format_checker=draft7_format_checker)
except ValidationError as e:
    print("Json数据验证不通过，异常字段：{} 异常信息：{}".format(" ".join([i for i in e.path]), e.message))
else:
    print("验证通过")

上述代码示例中，表示对 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)，则其数据类型必须是列表。

$schema 关键字

$schema 关键字用于指定JSON 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为不同类型，涉及到的关键字用法。

当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
        },
        "grade": {
            "type": "number",
            # 设定 maximum 为100, 则传入值必须小于等于 100
            "maximum": 100,
            # 设定 maximum 为True ,则传入值必须小于100
            "exclusiveMinimum": True
        }
    }

required 关键字

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

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

"required": [
    "name", 
    "grade", 
    "hobby"
    ]

minProperties、maxProperties 关键字

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

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

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

propertyNames 关键字

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

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

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

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"
        }
}

additionalProperties 关键字

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

{"additionalProperties": False }

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

"additionalProperties":{
    "type": "array"
}

dependencies 关键字

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

"dependencies": {
        "name": ["id"],
}

可以理解为：

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

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

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

完整示例

# Json schema：
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"
        },
        "grade": {
            "type": "number",
            # 设定 maximum 为100, 则传入值必须小于等于100
            "maximum": 100,
            # 设定 maximum 为True, 则传入值必须小于100
            "exclusiveMinimum": True
        },
        "hobby": {
            "description": "Students' hobby",
            "type": "array"
        }
    },
    "required": [
        "name", "grade", "hobby"
    ],
    "maxProperties": 10,
    "patternProperties": {
            "^id": {
                "type": "integer"
            }
    },
    "additionalProperties":{
        "type": "array"
    },
    "dependencies": {
            "name": ["id"],
    }
}

当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 
   }
}

若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"
        }
    ]
}

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

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

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

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

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

additionalItems 关键字

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

{
    "type": "array",
    "items": [
        {
            "type": "string",
            "minLength": 5
        },
        {
            "type": "number",
            "minimum": 5
        },
        {
            "type": "string"
        }
    ],
    "additionalItems": False
}

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

["basketball", 5, "ball", 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
    }
}

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

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

minItems、maxItems 关键字

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

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

"minItems": 10,
"maxItems": 2

uniqueItems 关键字

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

"uniqueItems": true

完整示例

{
    "type": "array",
    "items": [
        {
            "type": "string",
            "minLength": 5
        },
        {
            "type": "number",
            "minimum": 5
        },
        {
            "type": "string"
        }
    ],
    "additionalItems": {
        "type": "number",
        "minLength": 10
    },
    "minItems": 2,
    "maxItems": 10,
    "uniqueItems": true
}

当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
}

maximum 关键字

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

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

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

{
    "type": "integer",
    "maximum ": 5
}

exclusiveMaximum 关键字

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

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

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

minimum、exclusiveMinimum 关键字

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

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

{
    "type": "number",
    #  设定 maximum 为10 则传入值必须大于等于10
    #  "minimum": 10,
    #  设定 exclusiveMaximum为10,则传入值是大于10
    "exclusiveMinimum ": 10
}

完整示例

{
    "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

minLength 关键字

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

"minLength": 2

pattern 关键字

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

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

当type取值为任一类型

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

enum

const

allOf、anyOf、oneOf

not

enum 关键字

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

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

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

const 关键字

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

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

{"const": "Jon"}

allOf 关键字

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

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

{
  "anyOf": [
    { "type": "string", "maxLength": 5 },
    { "type": "number", "minimum": 0 }
  ]
}

anyOf 关键字

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

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

{
  "allOf": [
    { "type": "string" },
    { "maxLength": 5 }
  ]
}

oneOf 关键字

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

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

{
 "type": "number",
 "oneOf": [
  { "multipleOf": 5},
  { "multipleOf": 3}
 ]
}

not 关键字

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

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

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

type 关键字为一个数组

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

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

JSON Schema 常用关键字汇总

from jsonschema import validate, draft7_format_checker
from jsonschema.exceptions import SchemaError, ValidationError

student_schema = {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "title": "student information",
    "description": "some information about test",
    "type": "object",
    "properties": {
        "id": {
            "title": "id",
            "description": "Students' id",
            "type": "integer",
            "minimum": 1
        },
        "name": {
            "title": "name",
            "description": "Students' name",
            "minLength": 3,
            "maxLength": 30
        },
        "school":{
            "title": "school",
            "description": "Students' school",
            "const": "Hexi Foreign Language Senior High School"
        },
        "grade": {
            "description": "Students' scores",
            "type": "number",
            "minimum":0,
            "maximum":100,
            "multipleOf": 0.5,
        },
        "phone": {
            "title": "phone",
            "description": "Students' phone",
            "type": "string",
            "pattern": "^1[3|4|5|7|8|9][0-9]{9}$"
        },
        "hobby": {
            "description": "Students' hobby",
            "type": "array",
            "items": [
                {
                    "type": "string",
                    "minLength": 5
                },
                {
                    "type": "number",
                    "minimum": 5
                }
            ],
            "additionalItems":
            {
                "type": "string",
                "miniLength": 2
            },
        },
        "remark": {
            "description": "Students' remark",
            "type": "object",
            "properties": {
                "father_name": {
                    "type": "string"
                },
                "mother_name": {
                    "type": "string"
                }
            }
        }
    },
    "required": [
        "name", "grade"
    ],

    "minProperties": 7,
    "maxProperties": 10,
    "patternProperties": {
             "^id": {
                 "type": "integer"
             }
     },
    "dependencies": {
            "name": ["id"],
    },
    "additionalProperties":{
        "type": "array"
    }
}


json_data = {
    "id": 1,
    "name": "Tom",
    "school": "Hexi Foreign Language Senior High School",
    "grade": 96.5,
    "phone": "19825001234",
    "remark": {"father_name":"Tony", "mother_name":"Mary"},
    "subject": ["math", "chinese"]
}


try:
    validate(instance=json_data, schema=student_schema, format_checker=draft7_format_checker)
except ValidationError as e:
    print("Json数据验证不通过，异常字段：{} 异常信息：{}".format(" ".join([i for i in e.path]), e.message))
else:
    print("验证通过")

下面是测试资料，对于做【软件测试】的朋友来说应该是最全面最完整的备战仓库，这个仓库也陪伴我走过了最艰难的路程，希望也能帮助到你！

最后： 可以在公众号：伤心的辣条 ！ 免费领取一份216页软件测试工程师面试宝典文档资料。以及相对应的视频学习教程免费分享！，其中包括了有基础知识、Linux必备、Shell、互联网程序原理、Mysql数据库、抓包工具专题、接口测试工具、测试进阶-Python编程、Web自动化测试、APP自动化测试、接口自动化测试、测试高级持续集成、测试架构开发测试框架、性能测试、安全测试等。

学习不要孤军奋战，最好是能抱团取暖，相互成就一起成长，群众效应的效果是非常强大的，大家一起学习，一起打卡，会更有学习动力，也更能坚持下去。你可以加入我们的测试技术交流扣扣群：914172719（里面有各种软件测试资源和技术讨论）

喜欢软件测试的小伙伴们，如果我的博客对你有帮助、如果你喜欢我的博客内容，请 “点赞” “评论” “收藏” 一键三连哦！

---

好文推荐

转行面试，跳槽面试，软件测试人员都必须知道的这几种面试技巧！

面试经：一线城市搬砖！又面软件测试岗，5000就知足了…

面试官：工作三年，还来面初级测试？恐怕你的软件测试工程师的头衔要加双引号…

什么样的人适合从事软件测试工作？

那个准点下班的人，比我先升职了…

测试岗反复跳槽，跳着跳着就跳没了…

---

1. a-z_ ↩︎