跳到主要内容

JSON Schema 介绍

如何描述 JSON ?

JSON (JavaScript Object Notation) 缩写,JSON 是一种数据格式,具有简洁、可读性高、支持广泛的特点。JSON 有以下基本数据类型

// # 1. object
{ "key1": "value1", "key2": "value2" }

// # 2. array
[ "first", "second", "third" ]

// # 3. number
42

// # 4. string

"This is a string"

// # 5. boolean

true

false

// # 6. null

null

在其它语言中也有类似的内建数据类型,但是由于 JavaScript 的广泛应用,而 JSON 作 为 JavaScript 原生的数据类型,具备更加广泛的支持。

有了上面列举的基本数据类型,JSON 能非常灵活的表示任意复杂的数据结构。举个例子:

  {
"name": "George Washington",
"birthday": "February 22, 1732",
"address": "Mount Vernon, Virginia, United States"
}

如何描述上面 JSON 对象呢?

首先,它是一个 object

其次,它拥有 namebirthdayaddress 这三个字段

并且,nameaddress 的字段值是一个字符串 Stringbirthday 的值是一个日期。

最后,将上面的信息如何用 JSON 来表示?如下:

  {
"type": "object",
"properties": {
"name": { "type": "string" },
"birthday": { "type": "string", "format": "date" },
"address": { "type": "string" }
}
}

这个表示就是一个 JSON SchemaJSON Schema 用于描述 JSON 数据。

相同的数据,可能有不同的表示,比如下面的两种表示,包含的信息量基本是一致的:

  // # 1. 表示一
{
"name": "George Washington",
"birthday": "February 22, 1732",
"address": "Mount Vernon, Virginia, United States"
}

// # 2. 表示二
{
"first_name": "George",
"last_name": "Washington",
"birthday": "1732-02-22",
"address": {
"street_address": "3200 Mount Vernon Memorial Highway",
"city": "Mount Vernon",
"state": "Virginia",
"country": "United States"
}
}

在特定的应用场景中,应用程序对数据的结构要求是确定的,出于对数据描述的规范化需 求,需要用 JSON Schema 来规范化。使用 JSON Schema 可以描述 JSON 数据所包含的字 段、以及字段值的类型,以及依赖关系等。

相同信息量的数据,采用不同的形式来表达,用 JSON Schema 来描述也是不一样的,表示二的 JSON Schema 如下:

  {
"type": "object",
"properties": {
"first_name": { "type": "string" },
"last_name": { "type": "string" },
"birthday": { "type": "string", "format": "date-time" },
"address": {
"type": "object",
"properties": {
"street_address": { "type": "string" },
"city": { "type": "string" },
"state": { "type": "string" },
"country": { "type" : "string" }
}
}
}
}

从上面的描述,可以很自然的想到 JSON Schema 可以用来做数据校验,比如前后端先把数 据接口约定好,写好 JSON Schema,等后端把接口输出完毕,直接用 JSON Schema 来对接 口做验收。

关于 JSON Schema 的应用,对 JSON Schema 有过了解的人可以直接跳到第三、四部分。

接下来对 JSON Schema 做一些举例说明。

JSON Schema 示例

1. 空 schema

{}

以下都是合法的 JSON

42

"I'm a string"

[{"an": "aaa","bbb":{"nest":"data"}}]

2. type 指定 JSON 数据类型

{ "type": "string" }
"I'm a string"

42

{ "type": "number" }

42

"42"
type` 的可能取值: `string``number``object``array``boolean``null

3. type 可以包含多个类型

{ "type": ["number", "string"] }
"I'm a string" // 合法

42 // 合法

["Life", "the universe", "and everything"] // 不合法

4. string 限定长度

{
"type": "string",
"minLength": 2,
"maxLength": 3
}
"AA" // 合法
"AAA" // 合法
"A" // 不合法
"AAAA" // 不合法

5. string 模式匹配

{
"type": "string",
"pattern": "^(\\([0-9]{3}\\))?[0-9]{3}-[0-9]{4}$"
}
"555-1212" // ok

"(888)555-1212" // ok

"(888)555-1212 ext. 532" // not ok

"(800)FLOWERS" // not ok

6. string 值的枚举

{
"type": "string",
"enum": ["red", "amber", "green"]
}
"red" // ok

"blue" // not ok: blue 没有在 enum 枚举项中

7. integer

integer 一定是整数类型的 number

{ "type": "integer" }
42 // ok
1024 // ok

8. multipleOf 数字倍数

{ "type": "number", "multipleOf": 2.0 }
42 // ok
21 // not ok

9. number 限定范围

{
"type": "number",
"minimum": 0,
"maximum": 100,
"exclusiveMaximum": true
}

exclusiveMaximumtrue 表示不包含边界值 maximum,类似的还有 exclusiveMinimum 字段.

10. object 不允许有额外的字段

{
"type": "object",
"properties": {
"number": { "type": "number" },
"street_name": { "type": "string" },
"street_type": {
"type": "string",
"enum": ["Street", "Avenue", "Boulevard"]
}
},
"additionalProperties": false
}
{ "number": 1600, "street_name": "Pennsylvania", "street_type": "Avenue" } // ok
{ "number": 1600, "street_name": "Pennsylvania", "street_type": "Avenue","direction": "NW" } // not ok

因为包含了额外的字段 direction,而 schema 规定了不允许额外的字段 "additionalProperties": false

11. object 允许有额外的字段,并限定类型

{
"type": "object",
"properties": {
"number": { "type": "number" },
"street_name": { "type": "string" },
"street_type": {
"type": "string",
"enum": ["Street", "Avenue", "Boulevard"]
}
},
"additionalProperties": { "type": "string" }
}
{ "number": 1600, "street_name": "Pennsylvania", "street_type": "Avenue","direction": "NW" } // ok

{ "number": 1600, "street_name": "Pennsylvania", "street_type": "Avenue", "office_number": 201 } // not ok
额外字段 `"office_number": 201` 是 number 类型,不符合 schema

12. object 必填字段

{
"type": "object",
"properties": {
"name": { "type": "string" },
"email": { "type": "string" },
"address": { "type": "string" },
"telephone": { "type": "string" }
},
"required": ["name", "email"]
}
// ok
{
"name": "William Shakespeare",
"email": "bill@stratford-upon-avon.co.uk"
}

多出字段也是 ok 的

// ok
{
"name": "William Shakespeare",
"email": "bill@stratford-upon-avon.co.uk",
"address": "Henley Street, Stratford-upon-Avon, Warwickshire, England",
"authorship": "in question"
}

少了字段,就是不行

// not ok
{
"name": "William Shakespeare",
"address": "Henley Street, Stratford-upon-Avon, Warwickshire, England",
}

13. object 指定属性个数

{
"type": "object",
"minProperties": 2,
"maxProperties": 3
}
{ "a": 0, "b": 1 } // ok
{ "a": 0, "b": 1, "c": 2, "d": 3 } // not ok

14. Dependencies 依赖

  略复杂,不提供示例

15. Object 属性的模式匹配

{
"type": "object",
"patternProperties": {
"^S_": { "type": "string" },
"^I_": { "type": "integer" }
},
"additionalProperties": false
}
{ "S_25": "This is a string" } // ok

{ "I_0": 42 } // ok
// not ok
{ "I_42": "This is a string" }

{ "keyword": "value" }

16. array 数组

// ok
{ "type": "array" }
[1, 2, 3, 4, 5]
[3, "different", { "types" : "of values" }]
// not ok:
{"Not": "an array"}

17. array 指定数组成员类型

{
"type": "array",
"items": {
"type": "number"
}
}
[1, 2, 3, 4, 5] // ok
[1, 2, "3", 4, 5] // not ok

18. array 指定数组成员类型,逐个指定

{
"type": "array",
"items": [{
"type": "number"
},{
"type": "string"
},{
"type": "string",
"enum": ["Street", "Avenue", "Boulevard"]
},{
"type": "string",
"enum": ["NW", "NE", "SW", "SE"]
}]
}
// ok
[1600, "Pennsylvania", "Avenue", "NW"]

[10, "Downing", "Street"] // 缺失一个也是可以的

[1600, "Pennsylvania", "Avenue", "NW", "Washington"] // 多出一个也是可以的
// not ok
[24, "Sussex", "Drive"]
["Palais de l'Élysée"]

19. array 指定数组成员类型,逐个指定,严格限定

{
"type": "array",
"items": [{
"type": "number"
},
{
"type": "string"
},
{
"type": "string",
"enum": ["Street", "Avenue", "Boulevard"]
},
{
"type": "string",
"enum": ["NW", "NE", "SW", "SE"]
}
],
"additionalItems": false
}
[1600, "Pennsylvania", "Avenue", "NW"] // ok

[1600, "Pennsylvania", "Avenue"] // ok

[1600, "Pennsylvania", "Avenue", "NW", "Washington"] // not ok 多出了字段就是不行

20. array 数组长度限制

{
"type": "array",
"minItems": 2,
"maxItems": 3
}
[1, 2] // ok

[1, 2, 3, 4] // not ok

21. array element uniqueness 数组元素的唯一性

{
"type": "array",
"uniqueItems": true
}
[1, 2, 3, 4, 5] // ok
[1, 2, 3, 3, 4] // not ok:出现了重复的元素 3

22. boolean

{ "type": "boolean" }
true // ok
0 // not ok

23. null

{ "type": "null" }
null // ok

"" // not ok

24. schema 的合并

string 类型,最大长度为 5 ;或 number 类型,最小值为 0

{
"anyOf": [
{ "type": "string", "maxLength": 5 },
{ "type": "number", "minimum": 0 }
]
}

`anyOf` 包含了两条规则,符合任意一条即可
"short" // ok
42 // ok
"too long" // not ok 长度超过 5
-5 // not ok 小于了 0

25. allOf、oneOf

  `anyOf` 是满足任意一个 Schema 即可,而 `allOf` 是要满足所有 Schema
`oneOf` 是满足且只满足一个

26. oneOf

{
"oneOf": [
{ "type": "number", "multipleOf": 5 },
{ "type": "number", "multipleOf": 3 }
]
}
10 // ok
15 // not ok 因为它既是 3 又是 5 的倍数

上面的 schema 也可以写为:

{
"type": "number",
"oneOf": [
{ "multipleOf": 5 },
{ "multipleOf": 3 }
]
}

27. not

{ "not": { "type": "string" } }

只要是非 string 类型即可

42 // ok
{"key" : "value"} // ok
"This is a string" // not ok