一、什么是 JSONSchemaJSONSchema 是 JSON 数据的「规则说明书 校验器」我们做接口自动化时接口返回 JSON 格式数据经常要校验返回字段有没有缺失比如少了 code、data字段数据类型是否正确code 是字符串、id 是数字不能返回布尔 / 空字符串长度、数字范围、数组元素格式是否合规总结JSONSchema作用提前定义 JSON 规范用代码校验返回数据来确定数据是否符合约定格式广泛用于接口自动化测试、前后端联调参数校验。1.1 安装依赖固定版本避免报错# 统一版本4.23.0防止新版本API变动 pip install jsonschema4.23.0安装成功后即可在 Python 代码导入校验函数。二、JSONSchema 核心关键字JSONSchema 本身是一个 JSON 字典结构通过固定关键字约束数据下面逐个拆解高频关键字2.1 type限定字段数据类型type 支持 7 种原生 JSON 类型对应关系type 取值含义示例数据string字符串SUCCESS、123integer纯整数10、99不能带小数number数字 (整数 浮点)20、3.14boolean布尔true/falseobjectJSON 对象{} 包裹{name:张三}arrayJSON 数组[] 包裹[1,2,3]null空值null示例代码基础对象类型校验from jsonschema.validators import validate # 1. 定义校验规则schema规则说明书 schema { type: object, # 根节点整体必须是对象{} properties: { # 定义对象里面所有字段的规则 username: {type: string}, # username必须是字符串 age: {type: integer} # age必须是整数 } } # 2. 待校验的JSON数据接口返回数据 right_data {username: 小明, age: 18} wrong_data {username: 123, age: 十八} # 类型全错 # 3. 执行校验符合规则无报错不符合直接抛异常 validate(instanceright_data, schemaschema) # validate(instancewrong_data, schemaschema) # 打开此行会触发校验失败报错json转JSONSchema太麻烦使⽤现有⼯具⾃动转换json转jsonschema工具注意⼯具不是万能的结果可能存在错误。工具遇到安全问题无法访问需要无视警告继续访问2.2 required必填字段约束required是列表格式填写字段名代表这些字段必须存在缺字段直接校验失败。schema { type: object, required: [code, errMsg, data], # code、errMsg、data三个字段缺一不可 properties: { code: {type: string}, errMsg: {type: string}, data: {type: [array, null]} # data可以是数组或者null空值 } } # 缺了data字段校验报错 err_json {code: SUCCESS, errMsg: } # validate(instanceerr_json, schemaschema)2.3 properties对象字段规则配置properties用来逐个定义对象内每个字段的校验规则只约束类型不代表字段必填必填要配合 required。2.4 数字约束minimum/maximum数值范围针对integer/number类型限定数字最大、最小值minimum大于等于该值exclusiveMinimum严格大于不能等于maximum小于等于该值exclusiveMaximum严格小于schema { type: object, properties: { age: { type: integer, minimum: 0, # 年龄≥0 maximum: 120 # 年龄≤120 } } }2.5 字符串约束pattern 正则匹配pattern通过正则表达式约束字符串格式手机号、邮箱、账号格式校验必备schema { type: object, properties: { phone: { type: string, pattern: ^1[3-9]\\d{9}$ # 国内11位手机号正则 } } }2.6 数组约束items/minItems/maxItems/uniqueItems数组array专属关键字items约束数组里每一个元素的格式minItems/maxItems数组最少 / 最多有几个元素uniqueItems: true数组内元素不能重复schema { type: object, properties: { tag_list: { type: array, minItems: 1, # 数组最少1个元素 maxItems:5, # 最多5个元素 uniqueItems:True,# 元素不能重复 items: {type:string} # 数组里每个元素必须是字符串 } } }2.7 对象进阶additionalProperties 禁止多余字段默认 JSON 对象可以随便加额外字段additionalProperties:false 表示不允许出现 properties 没定义的字段严格接口返回校验schema { type: object, additionalProperties: False, # 不能出现name、age以外的字段 properties: { name: {type:string}, age: {type:integer} } } # 多了sex字段校验失败 extra_data {name:小红,age:20,sex:女} # validate(instanceextra_data,schemaschema)2.8 对象进阶min/maxProperties 限制 JSON 键值对数量minProperties限制 JSON 对象最少拥有的键值对属性数量实际属性数 设定值 → 校验失败maxProperties限制 JSON 对象最多拥有的键值对属性数量实际属性数 设定值 → 校验失败作用于type:object类型与required必填字段是两套规则required管控必须存在哪些 keymin/maxProperties管控key 总个数范围from jsonschema import validate # 1、JSON Schema规则单个博客对象属性数量必须在7~9个之间 blog_schema { type: object, minProperties: 7, # 最少7个字段 maxProperties: 9, # 最多9个字段 properties: { id: {type: number}, title: {type: string}, content: {type: string}, userId: {type: number}, deleteFlag: {type: number}, createTime: {type: string}, updateTime: {type: string}, loginUser: {type: boolean} } } # 样例1正常数据一共8个字段7≤8≤9校验通过 normal_data { id: 5, title: 自动化测试创建, content: ##在这里写下一篇博客, userId: 4, deleteFlag: 0, createTime: 2026-05-23 23:35, updateTime: 2026-05-23T15:35:01.00000:00, loginUser: False } # 样例2字段只有5个 minProperties7校验报错 less_data { id: 5, title: 自动化测试创建, content: ##在这里写下一篇博客, userId: 4, deleteFlag: 0 } # 执行校验 validate(instancenormal_data, schemablog_schema) print(✅ 正常数据校验通过) # validate(instanceless_data, schemablog_schema) #放开此行会抛出属性数量不足异常三、实战案例接口返回 JSON 完整校验博客列表接口3.1 原始接口返回 JSON 结构{ code: SUCCESS, errMsg: , data: [ { id: 1, title: Python入门, content: 学习JSONSchema, userId: 1001, deleteFlag: 0, createTime: 2025-01-01, updateTime: 2025-01-02, loginUser: false } ] }3.2 手写对应 JSONSchema 规则 完整可运行 Python 代码import requests from jsonschema.validators import validate # 1. 定义整套接口返回的校验规则schema blog_schema { type: object, # 整个返回体是对象 required: [code, errMsg, data], # 三个字段必须存在 additionalProperties: False, # 不能多出其他字段 properties: { code: {type: string}, # 状态码字符串 errMsg: {type: string}, # 错误提示字符串 data: { type: array, # data是数组 items: { # 数组里每一项是博客对象 type: object, required: [id,title,content,userId,deleteFlag,createTime,updateTime,loginUser], additionalProperties:False, properties: { id: {type: number}, title: {type: string}, content: {type: string}, userId: {type: number}, deleteFlag: {type: number}, createTime: {type: string}, updateTime: {type: string}, loginUser: {type: boolean} } } } } } # 2. 调用接口获取真实返回数据 url http://8.137.19.140:9090/blog/getList headers { user_token_header: eyJhbciOiJIUzI1NiJ9.eyJpZCI6MSwxNzkwNDc1NTk5NjE0OWFuY2hl } res requests.get(urlurl, headersheaders) resp_json res.json() # 3. 执行校验 try: validate(instanceresp_json, schemablog_schema) print(✅ JSON格式完全符合规范校验通过) except Exception as e: print(f❌ 校验失败错误详情{e.message})四、懒人技巧JSON 自动转 JSONSchema 工具手动写 schema 繁琐推荐在线自动生成工具https://tooltt.com/json2schema/粘贴接口返回的 JSON 数据一键生成基础 schema重要提醒工具生成结果需要二次修改手动补充 required 必填、数值范围、正则等约束不能直接拿来用。五、自动化测试落地小技巧用例分层把每个接口的 schema 单独存为字典 / JSON 文件测试用例直接读取方便统一维护异常捕获try-except 捕获 validate 异常测试报告输出详细错误信息哪个字段类型错误、缺哪个必填项版本锁定安装固定jsonschema4.23.0避免库升级后 API 改动导致旧代码报错六、常见踩坑总结小白必看integer 和 number 区别integer 只能整数number 支持整数 小数不要混用布尔值小写JSON 布尔是true/false小写不是 Python 的 True/FalseJSON 数据规范required 字段写错名字字段名大小写敏感errmsg和errMsg是两个不同字段空值 null字段允许为空写type:[string,null]代表字符串或 null 都合法
9：JSONSchema
一、什么是 JSONSchemaJSONSchema 是 JSON 数据的「规则说明书 校验器」我们做接口自动化时接口返回 JSON 格式数据经常要校验返回字段有没有缺失比如少了 code、data字段数据类型是否正确code 是字符串、id 是数字不能返回布尔 / 空字符串长度、数字范围、数组元素格式是否合规总结JSONSchema作用提前定义 JSON 规范用代码校验返回数据来确定数据是否符合约定格式广泛用于接口自动化测试、前后端联调参数校验。1.1 安装依赖固定版本避免报错# 统一版本4.23.0防止新版本API变动 pip install jsonschema4.23.0安装成功后即可在 Python 代码导入校验函数。二、JSONSchema 核心关键字JSONSchema 本身是一个 JSON 字典结构通过固定关键字约束数据下面逐个拆解高频关键字2.1 type限定字段数据类型type 支持 7 种原生 JSON 类型对应关系type 取值含义示例数据string字符串SUCCESS、123integer纯整数10、99不能带小数number数字 (整数 浮点)20、3.14boolean布尔true/falseobjectJSON 对象{} 包裹{name:张三}arrayJSON 数组[] 包裹[1,2,3]null空值null示例代码基础对象类型校验from jsonschema.validators import validate # 1. 定义校验规则schema规则说明书 schema { type: object, # 根节点整体必须是对象{} properties: { # 定义对象里面所有字段的规则 username: {type: string}, # username必须是字符串 age: {type: integer} # age必须是整数 } } # 2. 待校验的JSON数据接口返回数据 right_data {username: 小明, age: 18} wrong_data {username: 123, age: 十八} # 类型全错 # 3. 执行校验符合规则无报错不符合直接抛异常 validate(instanceright_data, schemaschema) # validate(instancewrong_data, schemaschema) # 打开此行会触发校验失败报错json转JSONSchema太麻烦使⽤现有⼯具⾃动转换json转jsonschema工具注意⼯具不是万能的结果可能存在错误。工具遇到安全问题无法访问需要无视警告继续访问2.2 required必填字段约束required是列表格式填写字段名代表这些字段必须存在缺字段直接校验失败。schema { type: object, required: [code, errMsg, data], # code、errMsg、data三个字段缺一不可 properties: { code: {type: string}, errMsg: {type: string}, data: {type: [array, null]} # data可以是数组或者null空值 } } # 缺了data字段校验报错 err_json {code: SUCCESS, errMsg: } # validate(instanceerr_json, schemaschema)2.3 properties对象字段规则配置properties用来逐个定义对象内每个字段的校验规则只约束类型不代表字段必填必填要配合 required。2.4 数字约束minimum/maximum数值范围针对integer/number类型限定数字最大、最小值minimum大于等于该值exclusiveMinimum严格大于不能等于maximum小于等于该值exclusiveMaximum严格小于schema { type: object, properties: { age: { type: integer, minimum: 0, # 年龄≥0 maximum: 120 # 年龄≤120 } } }2.5 字符串约束pattern 正则匹配pattern通过正则表达式约束字符串格式手机号、邮箱、账号格式校验必备schema { type: object, properties: { phone: { type: string, pattern: ^1[3-9]\\d{9}$ # 国内11位手机号正则 } } }2.6 数组约束items/minItems/maxItems/uniqueItems数组array专属关键字items约束数组里每一个元素的格式minItems/maxItems数组最少 / 最多有几个元素uniqueItems: true数组内元素不能重复schema { type: object, properties: { tag_list: { type: array, minItems: 1, # 数组最少1个元素 maxItems:5, # 最多5个元素 uniqueItems:True,# 元素不能重复 items: {type:string} # 数组里每个元素必须是字符串 } } }2.7 对象进阶additionalProperties 禁止多余字段默认 JSON 对象可以随便加额外字段additionalProperties:false 表示不允许出现 properties 没定义的字段严格接口返回校验schema { type: object, additionalProperties: False, # 不能出现name、age以外的字段 properties: { name: {type:string}, age: {type:integer} } } # 多了sex字段校验失败 extra_data {name:小红,age:20,sex:女} # validate(instanceextra_data,schemaschema)2.8 对象进阶min/maxProperties 限制 JSON 键值对数量minProperties限制 JSON 对象最少拥有的键值对属性数量实际属性数 设定值 → 校验失败maxProperties限制 JSON 对象最多拥有的键值对属性数量实际属性数 设定值 → 校验失败作用于type:object类型与required必填字段是两套规则required管控必须存在哪些 keymin/maxProperties管控key 总个数范围from jsonschema import validate # 1、JSON Schema规则单个博客对象属性数量必须在7~9个之间 blog_schema { type: object, minProperties: 7, # 最少7个字段 maxProperties: 9, # 最多9个字段 properties: { id: {type: number}, title: {type: string}, content: {type: string}, userId: {type: number}, deleteFlag: {type: number}, createTime: {type: string}, updateTime: {type: string}, loginUser: {type: boolean} } } # 样例1正常数据一共8个字段7≤8≤9校验通过 normal_data { id: 5, title: 自动化测试创建, content: ##在这里写下一篇博客, userId: 4, deleteFlag: 0, createTime: 2026-05-23 23:35, updateTime: 2026-05-23T15:35:01.00000:00, loginUser: False } # 样例2字段只有5个 minProperties7校验报错 less_data { id: 5, title: 自动化测试创建, content: ##在这里写下一篇博客, userId: 4, deleteFlag: 0 } # 执行校验 validate(instancenormal_data, schemablog_schema) print(✅ 正常数据校验通过) # validate(instanceless_data, schemablog_schema) #放开此行会抛出属性数量不足异常三、实战案例接口返回 JSON 完整校验博客列表接口3.1 原始接口返回 JSON 结构{ code: SUCCESS, errMsg: , data: [ { id: 1, title: Python入门, content: 学习JSONSchema, userId: 1001, deleteFlag: 0, createTime: 2025-01-01, updateTime: 2025-01-02, loginUser: false } ] }3.2 手写对应 JSONSchema 规则 完整可运行 Python 代码import requests from jsonschema.validators import validate # 1. 定义整套接口返回的校验规则schema blog_schema { type: object, # 整个返回体是对象 required: [code, errMsg, data], # 三个字段必须存在 additionalProperties: False, # 不能多出其他字段 properties: { code: {type: string}, # 状态码字符串 errMsg: {type: string}, # 错误提示字符串 data: { type: array, # data是数组 items: { # 数组里每一项是博客对象 type: object, required: [id,title,content,userId,deleteFlag,createTime,updateTime,loginUser], additionalProperties:False, properties: { id: {type: number}, title: {type: string}, content: {type: string}, userId: {type: number}, deleteFlag: {type: number}, createTime: {type: string}, updateTime: {type: string}, loginUser: {type: boolean} } } } } } # 2. 调用接口获取真实返回数据 url http://8.137.19.140:9090/blog/getList headers { user_token_header: eyJhbciOiJIUzI1NiJ9.eyJpZCI6MSwxNzkwNDc1NTk5NjE0OWFuY2hl } res requests.get(urlurl, headersheaders) resp_json res.json() # 3. 执行校验 try: validate(instanceresp_json, schemablog_schema) print(✅ JSON格式完全符合规范校验通过) except Exception as e: print(f❌ 校验失败错误详情{e.message})四、懒人技巧JSON 自动转 JSONSchema 工具手动写 schema 繁琐推荐在线自动生成工具https://tooltt.com/json2schema/粘贴接口返回的 JSON 数据一键生成基础 schema重要提醒工具生成结果需要二次修改手动补充 required 必填、数值范围、正则等约束不能直接拿来用。五、自动化测试落地小技巧用例分层把每个接口的 schema 单独存为字典 / JSON 文件测试用例直接读取方便统一维护异常捕获try-except 捕获 validate 异常测试报告输出详细错误信息哪个字段类型错误、缺哪个必填项版本锁定安装固定jsonschema4.23.0避免库升级后 API 改动导致旧代码报错六、常见踩坑总结小白必看integer 和 number 区别integer 只能整数number 支持整数 小数不要混用布尔值小写JSON 布尔是true/false小写不是 Python 的 True/FalseJSON 数据规范required 字段写错名字字段名大小写敏感errmsg和errMsg是两个不同字段空值 null字段允许为空写type:[string,null]代表字符串或 null 都合法
