JSON Schema 参考书

本文作者：IMWeb 孙世吉 原文出处：IMWeb社区 未经同意，禁止转载

1 简介

JSON 模式（JSON Schema）是一种基于 JSON 格式定义 JSON 数据结构的规范。其用于：

• 描述现有数据格式。
• 干净的人类和机器可读的文档。
• 完整的结构验证，有利于自动化测试，可用于验证客户端提交的数据。

表现形式上来说 JSON Schema实际上也还是JSON数据。

JSON Schema制定了一系列规范，使得我们可以使用它来定义JSON数据的格式。

这有点像我们先定义了“语言”是什么怎么用，然后可以用“语言”来规定什么是诗词歌赋。“诗词歌赋”以及“诗词歌赋的定义”实际上也都还是“语言”。

简单来说，我们有JSON数据①，我们可以定义JSON数据②用来描述①的结构。这时候JSON数据②也就是JSON Schema，它可以描述以及验证JSON数据①。

JSON数据①：

{
    "name": "shijisun",
    "age": 24,
    "gender": "male"
}

JSON数据②（JSON Schema）：

{
    "type": "object",
    "properties": {
        "name": {
            "type": "string",
            "minLength": 4
        },
        "age": {
            "type": "integer",
            "minimum": 0,
            "maximum": 130
        },
        "gender": {
            "type": "string",
            "enum": [
                "male",
                "female"
            ]
        }
    }
}

如上所示，JSON数据②描述JSON数据①：

1、是一个json对象，有三个属性：name、age和gender；

2、name属性的值是一个字符串，最小长度4；

3、age属性的值是一个整形数，最小值0.最大值130；

4、gender属性的值是一个字符串，只能取“male”或者“female”

2 基础

JSON数据有两种结构：object和array

而object和array中的value可以取到如下几种类型的值。

本节说明怎么使用Schema描述上述类型与结构。

2.1 基本类型

JSON Schema为json值定义了7种基本类型，基本与JSON定义一致：

2.2 schema定义

2.2.1 定义Schema实例

一个最简单的JSON Schema实例：

{
    "type": SchemaType
}

其中SchemaType是JSON Schema支持的基本类型，例如 "boolean"。

2.2.2 定义非嵌套类型

使用Schema定义一个类型为boolean、integer、number、string或null的json数据。

Schema：

{
    "type": "integer"
}

示例数据：

12345

上面描述了一个值为整型数的json数据，同理只要使用2.1说明的其他类型替换type字段的内容即可用于定义其他类型。

2.2.3 定义嵌套类型

2.2.3.1 object

• 类型为object的Schema，通过properties属性声明键值对中key的值与value的类型

Schema：

{
    "type": "object",
    "properties": {
        "id": {
            "type": "integer"
        },
        "name": {
            "type": "string"
        },
        "age": {
            "type": "integer"
        },
        "gender": {
            "type": "string"
        }
    }
}

示例数据：

{
    "id": 12345,
    "name": "shijisun",
    "age": 24,
    "gender": "male"
}

例如：在上述例子中，定义object下有一个值为integer类型的属性“id”

2.2.3.2 array

• 类型为为array的Schema，通过items属性定义列表内元素的类型

Schema：

{
    "type": "array",
    "items": {
        "type": "string"
    }
}

示例数据：

[
  "hello",
  "world",
  "!"
]

2.2.4 嵌套定义说明

如果以 {{Schema}} 表示定义的JSON Schema实例，例如2.2.3中列举的都是Schema实例。 那么JSON Schema的嵌套定义规则可以表示成下面的形式：

{
    "type": "object",
    "properties": {
        "key1": {{Schema}},
        "key2": {{Schema}}
    }
}

{
    "type": "array",
    "items": {{Schema}}
}

你会发现这与JSON的定义是一致的。

我们可以使用JSON Schema描述所有可能出现的JSON数据结构

3 进阶

在上文我们已经可以使用JSON Schema描述现有JSON数据的格式了，但是你会发现我们可以定义object里面有什么属性，各个属性是什么类型；array里面的是什么类型的数据。但是我们还未对具体的数据进行限制，例如字符串的长度，整型数的取值范围，数组的长度等。

而JSON Schema实际上也定义了这些规范，以下列举了部分JSON Schema定义的用于数据验证的关键字。

注：下面的描述中，跟Schema有效性相关的实例一般指JSON Schema实例，与json数据验证相关的实例一般指JSON数据实例。

3.1 元数据关键字

3.2 通用验证关键字

3.3 跟类型相关的关键字

3.3.1 数字

以上关键字同时适用于integer和number

3.3.2 字符串

3.3.3 数组

3.3.4 对象

dependencies中定义的(name, schema)

模式依赖：name对应的JSON值必须也满足schema的定义；

dependencies中定义的(name, propertyset)

属性依赖：如果JSON实例拥有对应的属性名name，则也必须有name对应的propertyset数组内的所有属性名。

3.4 语义有效性

单独的结构验证可能不足以验证一个实例是否满足应用程序的所有要求。

format关键字对值的固定子集进行可互操作的语义验证。

这些子集已经被权威机构进行准确的描述，例如data-time、mail、hostname、ipv4等。

4 更多

官方网站

生成JSON Schema在线工具

Schema验证JSON数据在线工具