利用 JSON Schema 校验 JSON 数据

作者：马铁强  职位：QA Lead

背景介绍

首先介绍一下JSON Schema ，它是用于验证 JSON 数据结构的强大工具，JSON Schema是以一个JSON串来描述的JSON数据规范，可以用JSON Schema检验一个给定的JSON串是否满足约定的数据规范。目前工作中的http接口的输入输出多数都是JSON格式的数据，校验数据格式是否满足约定是必不可少的，无论是业务代码中对输入数据进行校验，还是测试用例中对接口输出数据做校验，都可以通过JSON Schema完成。下面通过几个例子看看JSON Schema到底是个啥。

1、例子1：最简单的JSON Schema就是没有限制

虽然我们使用JSON Schema 的目的是对JSON格式的数据做种种限制和校验，但空对象是完全有效的模式，可以接受任何有效的JSON。

下面这些都是有效的数据

2、例子2：JSON Schema的限制条件

为JSON Schema加几个限制条件，看看下面这个JSON Schema是如何约定JSON数据的

• type关键字表示JSON 限定类型是object，每个属性的type表示这个属性的数据类型

• properties关键字指定这个object有三个属性number,street_name,street_type,

• enum关键字表示这个street_type的数据只能是"Street", "Avenue", "Boulevard"这三个值

• required 表示number,street_name是必须有的属性，默认情况下，由properties关键字定义的属性不是必需的。

2.1 可以校验通过的数据

2.2 不能校验通过的数据

缺少必须属性

street_type使用的值“super-speed”不是在JSON Schema中约定的枚举值

3、关键字介绍

JSON Schema通过关键字描述对JSON数据的限制条件，下面再介绍几个关键字进一步了解JSON Schema 的功能。

3.1 用来定义基本功能的关键字

$schema: 这个关键字是JSON Schema的方言标识符，用于声明schema使用的是哪个draft版本。

{ "$schema": "http://json-schema.org/draft-07/schema#" }

$id: 声明一个模式资源标识

{ "$id":"http://yourdomain.com/schemas/youschema.json"}

type: 声明数据类型，可选的内容包括：

3.2 用于string类型验证的关键字

可以用下面这些关键字去限制string类型的数据

• minLength，字符串最小长度，非负数

• maxLength，字符串最大长度，非负数

• pattern，正则表达式

3.3 用于Number类型验证的关键字

• maximum: 限定最大值小于等于给定的值

• minimum: 限定最小值大于等于给定的值

• exclusiveMaximum: 限定最大值小于给定的值

• exclusiveMinimum: 限定最小值大于给定的值

• multipleOf: 限制数据为给定数字的倍数。

下面例子约定值是10的倍数都可以校验通过。

3.4 用于Array类型验证的关键字

• minContains: 限定最少匹配contains的次数

• maxContains: 限定最多匹配contains的次数

验证失败的数据

["apple", "orange", 2]
["apple", "orange", 2, 4, 8, 16]

验证通过的数据

["apple", "orange", 2, 4]
["apple", "orange", 2, 4, 8]number还可以使用multipleOf关键字将数字限制为给定数字的倍数。它可以被设置为任何正数。

3.5 用于Object类型验证的关键字

• minProperties: 限定最小属性个数

• maxProperties: 限定最大属性个数

• required: 必须有得属性

• properties: 用来配置对象属性

4、Java中利用JSON Schema校验数据

下面我们用一个简单的例子演示一下JSON Schema在java程序中校验数据

4.1 首先配置依赖

1. jsonschema-generator是一个根据java object生成JSON Schema的工具，支持Draft 6, 7, 2019-09， 2020-12

2. everit-json-schema是官方推荐的一个校验工具

4.2 再准备一个JSON Schema

约定输入的JSON数据的目的实际是要用这个数据转化成java对象，所以我们用一个java对象生成一个JSON Schema

这样我们就获得了一个JSON Schema

接下来我们准备一个用于验证的JSON数据，这是一个不符合JSON Schema约定的数据

校验数据

执行结果中包含了输入数据包含的6个不符合约定的地方

5、结语

JSON Schema提供了数据规范语法，JSON Schema 标准经过修订有多个Draft，当前的版本是Draft 202-12,Draft版本不同会略有差异。JSON Schema可以用于校验接口输入数据、自动化测试、甚至可以用其生成代码，jsonschema2pojo就是一个这样的工具，利用JSON Schema在数据约束和校验方面可以提供一些便利。

参考

Understanding JSON Schema — Understanding JSON Schema 2020-12 documentation https://json-schema.org/understanding-json-schema/