使用JSON Schema进行参数验证
目录
什么是 JSON Schema
JSON Schema 是基于 JSON 语法,用来描述 JSON 数据格式的一种规范。可以数据校验、生成接口文档,生成模拟数据等多种用途。
本质上,JSON 是由以下几种基本的数据结构组成的:
- 对象 objects
- 数组 array
- 数字 number
- 字符串 string
- 布尔值 boolean
- null
JSON Schema 对这些类型都做了规定。同时,JSON Schema 的规范也在不断的迭代更新,下文讲解基于 Draft 4。
公共属性
常用
type
定义数据类型;enum
定义可取值列表;default
定义默认值,默认值虽然有定义,但是不强制要求实现;
元数据
title
标题(可选)description
描述(可选)$schema
声明这是一个 schema,值一般为http://json-schema.org/schema#
,也可以为一个指向官网草案版本的链接,例如:http://json-schema.org/draft-06/schema#
组合验证属性
anyOf
传一个 schema 列表,只要满足其中一个就验证通过。allOf
传一个 schema 列表,必须满足其中全部才能验证通过。oneOf
传一个 schema 列表,仅仅满足其中一个时才验证通过。not
传一个 schema,不满足时会验证通过。
验证
验证 all
当 JSON Schema 为空时,任意内容都能通过验证
|
|
验证 string
|
|
附加参数有:
minLength
规定最小长度maxLength
规定最大长度pattern
正则表达式,建议使用^…$
进行整行匹配;format
草案中规定的一些内置的格式,不强制要求实现;
验证 number
number 有两种细分类型: integer 和 number
integer
用于验证整型
|
|
number
|
|
附加参数有:
multipleOf
被验证值必须是该值的倍数,该值必须是正数。minimum
最小值exclusiveMinimum
传 bool 参数,最小值是否不包含边界值,默认包含,即 falsemaximum
最大值exclusiveMaximum
传 bool 参数,最大值是否不包含边界值,默认包含,即 false
边界值参数 Draft 6 和 Draft 4 有很大不同。
验证 object
|
|
**默认情况下,object 中不传某个属性或者多传某个属性都能够验证通过。**因此上述 Schema 对 {}
也能验证通过。
附加参数:
properties
定义属性additionalProperties
- True:允许附加属性
- False:不允许附加属性
- object:规定附加属性验证,例如
"additionalProperties": { "type": "string" }
规定附加属性必须是字符串。
required
一个元素唯一的非空列表(Draft 6 允许为空),规定必传参数;minProperties
maxProperties
dependencies
- 属性依赖,例如
"dependencies": {"credit_card": ["billing_address"]}
表示,拥有credit_card
属性时必须拥有billing_address
属性; - Schema 依赖,能够定义依赖变量的类型等,相当于内嵌 schema。
- 属性依赖,例如
patternProperties
使用正则定义的属性列表。可以与additionalProperties
配合使用,additionalProperties
只定义不希望被正则匹配的属性。
一个 Schema 依赖的例子:
|
|
一个 patternProperties
的例子:
|
|
验证 array
|
|
附加参数:
items
- 用于 List validation 时值为 schema,所有元素都要满足验证条件,例如
'items': {‘type': 'number'}
要求所有元素都是数字类型; - 用于 Tuple validation 时值为 schema 组成的列表,根据元素顺序依次验证每个元素,可以少传或者多传元素都能验证通过;
- 用于 List validation 时值为 schema,所有元素都要满足验证条件,例如
additionalItems
在 Tuple validation 时可以定义额外元素的验证。minItems
maxItems
uniqueItems
元素是否唯一
验证 boolean
|
|
0 和 1,字符串 “True” 和 “False” 都不能验证通过。
验证 null
|
|
复杂结构
Reuse
使用 $ref
可以在一个 schema 中引用另一个 schema,这样可以定义部分公共 schema,其他 schema 重用这部分公共 schema 即可,避免重复定义。
举例说明,下面的 schema 在 definitions
中对地址数据进行了描述,在定义其他地址时,可以应用该地址描述。
|
|
$ref
取值可以是:
- 同一 JSON Schema 文件中的定义,以
#
开头; - 相对路径 URI,例如
definitions.json#/address
; - 绝对路径 URI;
递归模式
$ref
元素可用于创建引用自身的递归模式。例如,一个 person 包含的 children 数组,每个 children 也是 person 实例。
但请注意,$ref
相互引用的模式可能会导致解析器中的无限循环,不应该这样做。
|
|