格式校验利器：JSON Schema 简介

JSON 是什么

JSON，全称 JavaScript Object Notation. 是 JS 的数据结构的子集。相信你们对 JSON 也很是熟悉了。JSON 一共只有六种数据结构，这里列举他们在 JS 和 Python 中的叫法以及在 JSON 中的例子：

JS	Python3	JSON
string	string	"ABC"
number	int/float	123 -1.23
boolean	bool	true false
null	None	null
object	dictnu	{"key": "value"}
array	list	["ABC", 123, true]

因为 JSON 是 JS 语法的子集，因此下文中我都会使用 JS 的称呼。

得益于 JSON 极致的简单和 JS 的普遍使用，JSON 很快流行了起来。可是简单也有简单的坏处，人们逐渐发现 JSON 缺乏一些必要的功。

JSON Schema 是什么？

当先后端使用 JSON 通讯的时候，双方须要验证 JSON 的数据格式，好比验证 array 的长度、number 的大小、甚至于相似 object 中有某两个属性不能并存等等要求。固然这些规则均可以使用代码进行验证，可是这样写起来太繁琐了，因此为了描述并校验 JSON 的格式，JSON Schema 诞生了。

这里有一个很是简单的 JSON Schema 的例子：

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "type": "object",
    "properties": {
        "name":  { "type": "string" },
        "email": { "type": "string" },
    	"age": {
            "type": "integer",
            "minimum": 0,
            "exclusiveMinimum": false,
        },
    	"telephone": {
            "type": "string",
            "pattern": "^(\\([0-9]{3}\\))?[0-9]{3}-[0-9]{4}$"
        }
    },
	"required": ["name", "email"],
  "additionalProperties": false
}
复制代码

上面这个 JSON 描述了这样的一个 JSON：

• 类型是 object
• 有四个属性：
  • name：
    • 类型为 string
  • email：
    • 类型为 string
  • Age：
    • 类型为整数
    • 这个整数要大于等于 0
  • telephone：
    • 类型为 string
    • 须要符合这个正则表达式
• 上面这四个属性中必须出现有的 name 和 email，剩下的两个是可选的
• 除了这四个属性外，不容许出现其余属性

好比说，这样的一个 JSON 就符合这些要求：

{
    "name": "Sherlock Holmes",
    "email": "sherlock@gmail.com",
    "age": 164
}
复制代码

能够看到，JSON Schema 自己也是一个 JSON。同一个 JSON，同一个世界先后端都能看懂，那么的话这个 JSON Schema 就既能够做为执行代码，又能够做为文档。这种统一确保了代码和文档不会脱节，省去了写文档的功夫。毕竟程序员最讨厌的就是没有文档的代码和写文档了。

Understanding JSON Schema

在这里，我强烈推荐阅读 Understanding JSON Schema，以致于我要专门写一章来介绍它。这是一个很是适合初学者的教程，有着及其清晰的例子。虽然截止写稿时其版本还停留在 draft-04，不过瑕不掩瑜，依然是我心中最优秀的 JSON Schema 教程。

在这里列一下 Understanding JSON Schema 的大纲，方便查漏补缺：

• Type-specific keywords
  • string
    • minLength
    • maxLength
    • pattern
  • Numeric types
    • types: integer, number
    • multipleOf
    • range: minimum, exclusiveMinimum, maximum, exclusiveMaximum
  • object
    • properties
    • additionalProperties
    • required
    • size: minProperties, maxProperties
    • dependencies
    • patternProperties
  • array
    • items
    • length: minItems, maxItems
    • uniqueItems
  • boolean
  • null
• Generic keywords
  • Metadata: title, description, default
  • Enumerated values: enum
• Combining schemas
  • allOf
  • anyOf
  • oneOf
  • not
• The $schema keyword
• Regular Expressions

版本

截止到今天，JSON Schema 一共有 7 个版本，最新的是 draft-07。不一样版本之间并不（彻底）兼容，因此最佳实践是在写 JSON Schema 的时候使用 $schema 关键字标记当前使用的是哪一个规范。

下面举个例子，展现了 draft-04 和 draft-06 中「大于」和「大于等于」写法：

大于：

{
    "$schema": "https://json-schema.org/draft-06/schema#",
    "type": "number",
    "exclusiveMinimum": 0
}
复制代码

{
    "$schema": "https://json-schema.org/draft-04/schema#",
    "type": "number",
    "minimum": 0,
    "exclusiveMinimum": true
}
复制代码

大于等于：

{
    "$schema": "https://json-schema.org/draft-06/schema#",
    "type": "number",
    "minimum": 0
}
复制代码

{
    "$schema": "https://json-schema.org/draft-04/schema#",
    "type": "number",
    "minimum": 0,
    "exclusiveMinimum": false
}
复制代码

注：在 draft-04 中，exclusiveMinimum 的默认值就是 false，因此能够不写。

在 draft-04 中，exclusiveMinimum 的值是 boolean，draft-06 中改为了 number。在相同含义的状况下，新版的写法的确更加简洁。

关于不一样版本之间的区别能够查看官网的 Migrating from older drafts 一节。

总结

JSON Schema 做为一个验证 JSON 的通用语法，我认为它成功完成了本身的任务。虽然有一些诸如可读性不高，写法繁琐的缺点，可是我认为这些都是必要的妥协。

原文连接：ocavue.com/jsonschema.…