Json Schema简介

什么是Json Schema? 以一个例子来说明

假设有一个web api,接受一个json请求,返回某个用户在某个城市关系最近的若干个好友。一个请求的例子如下:

{ "city" : "chicago", "number": 20, "user" : { "name":"Alex", "age":20 } }

在上面的例子中,web api要求提供city,number,user三个成员,其中city是字符串,number是数值,user是一个对象,又包含了name和age两个成员。

对于api来说,需要定义什么样的请求合法,即什么样的Json对于api来说是合法的输入。这个规范可以通过Json Schema来描述,对应的Json Schema如下。
        { "type": "object",     "properties": {      "city": { "type": "string" },         "number": { "type": "number" },         "user": {          "type": "object",          "properties": {              "name" : {"type": "string"},                 "age" : {"type": "number"}             }                              } } }
例子可以通过Json Schema Validator来验证。

什么是Json Schema?

Json Schema定义了一套词汇和规则,这套词汇和规则用来定义Json元数据,且元数据也是通过Json数据形式表达的。Json元数据定义了Json数据需要满足的规范,规范包括成员、结构、类型、约束等。

本文后面的部分是简要介绍Json Schema定义的这些规则,以及如何用这些规则描述规范。

Json Schema定义了一系列关键字,元数据通过这些关键字来描述Json数据的规范。其中有些关键字是通用的;有些关键字是针对特定类型的;还有些关键字是描述型的,不影响合法性校验。本文的主要内容就是介绍这些关键字的应用。

2. 类型关键字

首先需要了解的是"type"关键字,这个关键字定义了Json数据需要满足的类型要求。"type"关键字的用法如下面几个例子:

{"type":"string"}。规定了Json数据必须是一个字符串,符合要求的数据可以是

"Today is a good day."
"I love you"

{"type" : "object"}。规定了Json数据必须是一个对象,符合要求的数据可以是

{"name" : "Alexander", "age" : 98}
{}

{"type" : "number"}。规定了Json数据必须是一个数值,符合要求的数据可以是。Java Script不区分整数、浮点数,但是Json Schema可以区分。

2
0.5

{"type": "integer"}。要求数据必须是整数。

2

{"type" : "array"}。规定了Json数据必须是一个数组,符合要求的数据可以是

["abc", "cdf"]
[1, 2, 3]
["abc", 25, {"name": "Alexander"} ]
[]

{"type" : "boolean"}。这个Json Schema规定了Json数据必须是一个布尔,只有两个合法值

true
false

{"type" : "null"}。null类型只有一个合法值

null

3. 简单类型

这部分介绍类型特定的关键,包括字符串、数值、布尔、空值几种基本类型。

3.1 字符串

Json合法的字符串            

"Today is a good day."

对应的Json Schema

{"type": "string"}

可以进一步对字符串做规范要求。字符串长度匹配正则表达式字符串格式

3.1.1 字符串长度

关键字: minLength, maxLength

可以对字符串的最小长度、最大长度做规范。

{ "type" : "string", "minLength" : 2, "maxLength" : 3, } 3.1.2 正则表达式

关键字: pattern

可以对字符串应满足的Pattern做规范,Pattern通过正则表达式描述。

{ "type" : "string", "pattern" : "^(\\([0-9]{3}\\))?[0-9]{3}-[0-9]{4}$", } 3.1.3 字符串Format

关键字: format

可以通过Json Schema内建的一些类型,对字符串的格式做规范,例如电子邮件、日期、域名等。
{ "type" : "string", "format" : "date", }

Json Schema支持的format包括"date", "time", "date-time", "email", "hostname"等。具体可以参考文档。

3.2 数值

Json Schema数值类型包括"number"和"integer"。number合法的数值可以是

2
0.1

对应的Json Schema为

{"type": "number"}

如果是integer则只能是整数。"number"和"integer"的类型特定参数相同,可以限制倍数范围

3.2.1 数值满足倍数

关键字: multipleOf

可以要求数值必须某个特定值的整数倍。例如要求数值必须是10的整数倍。

{ "type" : "number", "multipleOf" : 10, } 3.2.2 数值范围

关键字: minimum, maximum, exclusiveMinimum, exclusiveMaximum

可以限制数值的方位,包括最大值、最小值、开区间最大值、开区间最小值。

要求数值在[0, 100)范围内。

{ "type" : "number", "minimum": 0, "exclusiveMaximum": 100 } 3.3 布尔

布尔类型没有额外的类型特定参数。

3.4 空值

null类型没有额外的类型特定参数。

4. 复合类型

复合类型可以通过Nest的方式构建复杂的数据结构。包括数组、对象。

4.1 数组

Json数组合法数据的例子

[1, 2, 3]
[1, "abc", {"name" : "alex"}]
[]

Json Schema为

{"type": "array"}

内容版权声明:除非注明,否则皆为本站原创文章。

转载注明出处:https://www.heiqu.com/wsfsxf.html