JSON Schema 介绍及应用
- 2019 年 12 月 4 日
- 筆記
本文作者：IMWeb jerytang 原文出处：IMWeb社区 未经同意，禁止转载
一、如何描述 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；
其次，它拥有 name、birthday、address 这三个字段
并且，name 、address 的字段值是一个字符串 String，birthday 的值是一个日期。
最后，将上面的信息如何用 JSON 来表示？如下：
{ "type": "object", "properties": { "name": { "type": "string" }, "birthday": { "type": "string", "format": "date" }, "address": { "type": "string" } } }
这个表示就是一个 JSON Schema ，JSON 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 }
exclusiveMaximum 为 true 表示包含边界值 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": "[email protected]" }
多出字段也是 ok 的
// ok { "name": "William Shakespeare", "email": "[email protected]", "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
三、JSON schema 的应用一：对数据做验证
验证库 jsonschema
var Validator = require('jsonschema').Validator; var v = new Validator(); var instance = 4; var schema = {"type": "number"}; console.log(v.validate(instance, schema));
接口数据校验
在实际开发中，前端和后端会约定接口，前端根据约定的接口，使用 mock 的数据来开发 demo，而后端去实现接口，前端和后端可以同步进行。等后端开发完毕后，可以通过预先 写好的脚本对返回接口进行批量的数据校验。
四、JSON schema 的应用二：根据 JSON Schema 生成数据采集 UI
对数据进行校验是在数据输出端保证数据的正确性，有没有什么方式能在数据输出时就保证数据正确性呢？
这里提供一种思路，观察 schema 可以发现，其实一条 Schema 描述已经包含了相当丰富 的数据信息了，每一种 schema 类型其实可以对应了一种 UI 展示，那么一条 Schema 其 实是可以生成一个表单，表单的 UI 逻辑中保证在提交表单前，数据是符合 Schema 规则 的，表单验证通过后，得到的就是符合 Schema 的 JSON 数据。
通过这个思想，可以做一套 JSON Schema -> UI -> JSON 的运营数据采集系统，见文章 开始的配图。效果如下图：
具体的实现，我们留到以后再谈。
