在接口自动化测试中，我们不仅要关注接口是否返回成功，更要保证返回数据的结构、字段类型、字段值、必填项都符合预期。

JSON Schema 就是专门用来校验 JSON 数据格式的规范，也是 pytest 接口自动化中非常重要的一环。

一、JSON Schema 是什么？

JSON Schema 是一个用于定义和校验 JSON 数据的 Web 规范。简单说：它能帮你检查 JSON 是否符合你要求的格式。

例如：

• code 字段必须是字符串
• age 必须是数字
• data 必须是数组
• name 是必填字段

如果返回格式不对，自动化用例直接报错，确保数据一致性。

二、安装 JSON Schema 库+介绍validate()

pip install jsonschema==4.23.0

建议固定版本，避免兼容性问题。

validate()是 jsonschema 库提供的校验方法，作用只有一个：把真实返回的 JSON 数据 和 你定义的规则（Schema）进行对比，如果不符合就直接报错。

它的格式固定：

validate(真实JSON数据, 校验规则Schema)

它执行后如果✅ 正确：什么都不输出，用例通过，如果❌ 错误：直接报错，告诉你哪里错，

例如：

• code 应该是字符串，结果返回数字
• data 应该是数组，结果返回对象
• 缺少必填字段
• 格式不匹配

三、JSON与JSON Schema对比示例

JSON 数据：

{
"code": "SUCCESS",
"errMsg": "",
"data": false
}

JSON Schema 格式：

{
  "type": "object",
  "required": [],
  "properties": {
    "code": {
      "type": "string"
    },
    "errMsg": {
      "type": "string"
    },
    "data": {
      "type": "boolean"
    }
  }
}

可以看到，Schema 定义了：

• 整体是对象
• 每个字段的类型
• 哪些字段必填
• 嵌套结构规则

手动json转JSON Schema太麻烦了，我们使用现有工具自动转换：https://tooltt.com/json2schema/ 、 https://www.jashtool.com/json/to-schema

注意：工具不是万能的，结果可能存在错误，要对自动生成的结果进行二次检查

在代码中我们就可以利用validate来校验json是否正确：
 

def test_01():
    json_data = {
        "code": "SUCCESS",
        "errMsg": "",
        "data": False
    }
    json_schema = {
        "type": "object",
        "required": [],
        "properties": {
            "code": {
                "type": "string"
            },
            "errMsg": {
                "type": "string"
            },
            "data": {
                "type": "boolean"
            }
        }
    }
    #通过json schema中的模块来校验
    validate(json_data, json_schema)

四、JSON Schema 核心关键字

1. 数据类型 type

可以验证 JSON 数据中每个属性的数据类型是否符合预期。常用的数据类型包括：

• string 字符串类型，用于文本数据。
• number 数字类型，用于表示浮点数。
• integer 整数类型，用于表示整数。
• boolean 布尔类型，值为true或false.
• object 对象类型，用于嵌套的JSON对象。
• array 数组类型，用于列表或集合。
• null 空值类型。

示例：

#数据类型
def test_03():
    json = {
        "name": "zhangsan",
        "age": 20,
        "height":169.5,
        "female":False,
        "hobby":{
            "aaa":"aaa",
            "bbb":"bbb"
        }
    }
    json_schema = {
        "type":"object",
        "properties":{
            "name":{
                "type":"string"
            },
            "age":{
                "type":"integer"
            },
            "height":{
                "type":"number"
            },
            "female":{
                "type":"boolean"
            },
            "hobby":{
                "type":"object",
                "properties":{
                    "aaa": {
                        "type": "string"
                    },
                    "bbb": {
                        "type": "string"
                    }
                }
            }
        }
    }
    validate(json, json_schema)


#数据类型
def test_o4():
    json = {
        "data":[
            {
                "name":"zhangsan",
                "age":20
            },
            {
                "name":"lisi",
                "age":30
            }
        ],
        "addr":None
    }

    json_schema = {
      "type": "object",
      "properties": {
        "data": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "age": {
                "type": "integer"
              }
            }
          }
        },
        "addr":{
            "type":"null"
        }
      }
    }
    validate(json, json_schema)

这段代码涵盖了string 字符串、integer 整数、number 数字（小数）、boolean 布尔值、object 对象、array列表、null 空值 None，
同时还有 对象嵌套写法 和 数组嵌套对象写法

---

2. 数值范围

• minimum 最小值  和 maximum 最大值，包含等于
• exclusiveMinimum 和 exclusiveMaximum ：指定数值必须严格大于或小于某个值（不包
  含等于）

#最大最小值
def test_05():
    json = {
        "name":"aa",
        "age":100
    }
    json_schema = {
      "type": "object",
      "required": [],
      "properties": {
        "name": {
          "type": "string"
        },
        "age": {
          "type": "integer",
            "minimum":0,
            "maximum":100
            # "exclusiveMaximum":100
        }
      }
    }
    validate(instance = json, schema = json_schema)

---

3. 字符串校验（正则 pattern）

pattern ：使用正则表达式来验证字符串是否符合特定的模式。

我们校验字符串常用的有：

\s匹配空字符，\S匹配非空字符,  \S+匹配多个字符， {n}匹配什么n次——> a{2}匹配a2次，

{n,}至少匹配n次，{n,m}至少匹配n次，最多匹配m次。

在 JSON Schema 中使用正则表达式 pattern 时，若表达式包含 \（如 \S、\d、\w），必须在字符串前加 r，否则 Python 会将 \ 识别为转义字符，导致 SyntaxWarning: invalid escape sequence 警告。

如图：

# 字符串特殊校验
def test_06():
    json = {
        "name": "zhangsan",
        "age": 100
    }
    json_schema = {
      "type": "object",
      "required": [],
      "properties": {
        "name": {
          "type": "string",
            # "pattern": r"\S{9}"
            "pattern":r"\S{1,20}"
        },
        "age": {
          "type": "number"
        }
      }
    }
    validate(instance=json, schema=json_schema)

---

4. 数组约束

• minItems 和 maxItems ：指定数组的最小和最大长度。
• uniqueItems ：确保数组中的元素是唯一的。
• items ：定义数组中每个元素的类型和约束

#数组约束
def test_07():
    json = {
        "data":[1,2,3,4,5],
        "str":"hello"
    }
    json_schema = {
      "type": "object",
      "required": [],
      "properties": {
        "data": {
          "type": "array",
            #针对数组添加最大和最小长度限制
            "minItems":1,
            "maxItems":5,
            #要求数组中元素唯一
            "uniqueItems": True,
            #items是数组中的元素
          "items": {
            "type": "number"
          }
        },
        "str": {
          "type": "string"
        }
      }
    }
    validate(json, json_schema)

---

5. 对象约束、必需属性

• minProperties 和 maxProperties ：指定对象的最小和最大属性数量
• additionalProperties 控制是否允许对象中存在未在 properties 中定义的额外属性，默认为True。
• jsonSchema中约束了字段，但是在json返回值里未返回该字段，测试结果还是会是正确的。——>有可能出现，json没有返回数据，但是用例跑通过了的错误场景。这时，通过 required 关键字，JSON Schema 可以指定哪些属性是必需的。如果 JSON 实例中缺少这些必需属性，验证将失败。

#json Schema对象约束
def test_08():
    json = {
        "code": 200,
        "errMsg": None,
        "data": [
            {
                "id": 4,
                "title": "张三日记",
                "content": "2026-4-15张三，我是张三。那个叫李四的，你休想修改我的博客。##在这里写下一篇博客",
                "userId": 1,
                "deleteFlag": 0,
                "updateTime": "2026-04-15 08:14",
                "loginUser": False,
                # "isAdmin": False,
                "aaa":1,
                "bbb":2,
                "ccc":3
            }
        ]
    }
    json_schema = {
      "type": "object",
        #添加必须属性
      "required": ["code","errMsg","data"],
        # 为False，只能有properties里限制的这些项，不能有额外的字段
        "additionalProperties": True,
        # 最小的属性数量
        "minProperties": 3,
        # 最大的属性数量
        "maxProperties": 3,
      "properties": {
        "code": {
          "type": "number"
        },
        "errMsg": {
          "type": "null"
        },
        "data": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["id","title","content"],
            # #只能有properties里限制的这些项，不能有额外的字段
            # "additionalProperties": False,
              #注意配置中引号里不要有空格
              #最小的属性数量
              "minProperties": 7,
              #最大的属性数量
              "maxProperties": 10,
            "properties": {
              "id": {
                "type": "number"
              },
              "title": {
                "type": "string"
              },
              "content": {
                "type": "string"
              },
              "userId": {
                "type": "number"
              },
              "deleteFlag": {
                "type": "number"
              },
              "updateTime": {
                "type": "string"
              },
              "loginUser":{
                  "type": "boolean"
              }
            }
          }
        }
      }
    }
    validate(instance= json, schema=json_schema)

---

6. 依赖关系 dependentRequired

dependentRequired 可以定义属性之间的依赖关系。例如，如果username属性存在，则必须存在age属性。

---

五、总结

JSON Schema 是接口自动化测试的格式保障：

• 校验字段类型
• 校验必填字段
• 校验数组、对象结构
• 校验数值、字符串规则
• 校验字段依赖关系

在 pytest 项目中，JSON Schema 可以让接口用例更稳定、更严谨，避免因数据结构变化导致的隐藏问题。