JSON 架构（模式）

JSON Schema 是一个描述和验证 JSON 数据结构的强大工具，您可以将 JSON Schema 视为一种规范，该规范指定了 JSON 数据的结构、键命名、值类型等，您可以通过以下方式对其进行验证。 ：验证提供的JSON数据，确保数据准确性。因此，调试接口的过程中经常会使用JSON Schema来验证接口数据的正确性。

什么是 JSON 架构？

JSON Schema 翻译为由 IETF 创建和起草的“JSON Schema”。那么 JSON Schema 有什么作用呢？

IETF 代表互联网工程任务组，是一个大型公共非政府国际组织，翻译过来就是“国际互联网工程任务组”。

假设您想使用 JSON 存储产品信息，如下所示：

 
{
    "id": 1,
    "name": "JSONチュートリアル",
    "author": "IT基礎",
    "price": 99.9
} 

如上所示，这是一个非常简单的JSON数据，但是“id”是什么意思，“name”字段可以省略吗，“price”字段的值可以为0等等。

JSON Schema 就是为了解决上述问题而诞生的。JSON Schema 指定了 JSON 中出现的字段、字段的含义、字段的类型等信息，并指定了 JSON 数据在 JSON 中是如何定义的。验证是否符合架构。

模式定义

JSON Schema本身就是JSON格式的数据，如下例所示。

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

在上述架构中，JSON 数据必须满足以下要求：

• 类型是对象。
• 您可以在 JSON 中包含四个键：
  • name：必须是字符串类型。
  • 电子邮件：必须是字符串类型。
  • 年龄：必须是大于0的整数。
  • 电话：必须是字符串类型，并且必须与指定的正则表达式匹配。
• 在上面列出的四个键中，必须定义姓名和电子邮件，而年龄和电话号码是可选的。
• 除上述四个按键外，不能使用其他按键。

下面是符合上述架构的 JSON 数据。

 
{
    "name": "IT基礎",
    "email": "admin@it-kiso.com",
    "age": 18
} 

我们都知道JSON支持string、number、object、array、boolean、null等多种类型，针对不同的类型，Schema提供了一组关键字以及它们的用法：

1）字符串（字符串）

下表列出了与 JSON Schema 字符串相关的关键字。

关键词	解释	期权价值
最小长度	最小字符串长度。不能为负数
最大长度	最大字符串长度。不能为负数
图案	正则表达式
格式	字符串格式	日期和时间：日期和时间，例如2018-11-13T20:20:39+00:00 “time”：时间，例如 20:20:39+00:00 “Date”：日期，例如 2018-11-13 “Email”：电子邮件地址 “Hostname”：主机名 “ipv4”：IPv4 地址 “ipv6”：IPv6 地址 “uri”：统一资源标识符 (URI) “uri-template”：URI 模板（任何级别） “regex”：正则表达式

2) 数字类型

下表列出了 JSON Schema 中与数字相关的关键字。

关键词	解释	例子
整数	整数	{“类型”：“整数”}
数字	数字，包括整数和浮点数	{“类型”：“数字”}
多种的	数字必须是指定数字的倍数（正数）	{“类型”：“数字”，“multipleOf”：3}
最低限度	值允许的最小值	{“类型”：“数字”，“分钟”：1}
最大限度	允许的最大值	{“类型”：“数量”，“最大”：9}

3）对象

特性

JSON 架构允许您使用properties 关键字定义JSON 数据的键，如以下示例所示。

 
{
    "type": "object",
    "properties": {
        "name": { "type": "string"},
        "age": {"type": "number", "multipleOf": 3},
        "date": {
            "type": "string",
            "format": "date"
        }
    }
} 

附加属性（附加属性）

在 JSON 架构中，您可以使用 extraPropertiesis 为架构对象定义附加属性，其值为 false 或如下例所示：

 
{
    "type": "object",
    "properties": {
        "number": { "type": "number"},
        "street_name": { "type": "string"},
        "street_type": {
            "type": "string",
            "enum": ["Street", "Avenue", "Boulevard"]
        }
    },
    "additionalProperties": { "type": "string"}
} 

所需属性

在 JSON Schema 中，您可以使用 required 关键字来声明必须在 JSON 中定义的键。 required 值是一个数组，并且数组中的每个值必须是唯一的，如下例所示。

 
{
    "type": "object",
    "properties": {
        "name": { "type": "string" },
        "email": { "type": "string" },
        "address": { "type": "string" },
        "telephone": { "type": "string" }
    },
    "required": ["name", "email"]
} 

属性名称

在 JSON 架构中，您可以使用 propertyNames 定义 JSON 数据中键的命名约定，如以下示例所示。

 
{
    "type": "object",
    "propertyNames": {
        "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
    }
} 

属性数量（大小）

在 JSON 架构中，您可以使用 minProperties（最小数量）和 maxProperties（最大数量）关键字来限制 JSON 对象中的键数量，如以下示例所示。

 
{
    "type": "object",
    "minProperties": 2,
    "maxProperties": 3
} 

4）数组

数组是值的有序集合，JSON 数组中的每个值可以是不同的类型。

元素（项目）

默认情况下，数组的值可以是任何类型，但在 JSON Schema 中，您可以使用 items、additionalItems 和 contains 关键字来验证数组中的值。

• 列表验证：任意长度的数组。数组中的每个值都匹配相同的模式。
• 元组验证：固定长度数组。数组中的每个值都可以匹配不同的模式。

验证列表

如果希望数组中的所有值都匹配相同的模式，可以使用 items 关键字设置单个模式来验证数组中的所有值。使用单个架构时，additionalItems 关键字不起作用（将数组中的所有值验证为数字），如以下示例所示。

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

contains 关键字只需要验证数组中的一项或多项（它只需要包含至少一个数字元素），如以下示例所示：

 
{
    "type": "array",
    "contains": {
        "type": "number"
    }
} 

元组验证

在JSON数据中，如果数组中的每个值都有不同的含义，那么这些值也可以有不同的类型。例如：

[门牌号、街道名称、街道类型、方向]

为此，该架构允许您验证 JSON 数据，如下所示：

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

数组长度（长度）

可以使用 minItems、maxItems 关键字指定数组的长度。如下例所示（指定数组长度范围为2~3）：

 
{
    "type": "array",
    "minItems": 2,
    "maxItems": 3
} 

注意：数组长度不能为负数。

独特性

将 uniqueItems 关键字设置为 true 会使数组中的每个元素都唯一，如以下示例所示。

 
{
    "type": "array",
    "uniqueItems": true
} 

5) 布尔值

Boolean 类型只有两个值：true 和 false，如下例所示。

{“类型”：“布尔值”}

6）空值（null）

空类型通常用于指示不存在值。如果值类型指定为null，则表示值类型指定为null，如下例所示。

{“类型”：“空”}

7) 通用关键词

JSON Schema 包含一些用于松散验证的常见关键字，标题、描述、默认和示例。这些关键字主要用于说明架构的特性和功能。这些注释属性不是必需的，但建议使用。

• 标题和描述关键字必须是字符串。 “标题”应该简短，“描述”应该提供模式的详细描述。
• default 关键字用于定义默认值。
• example 关键字用于提供示例列表以根据模式进行验证。

如下例所示：

 
{
    "title": "Match anything",
    "description": "This is a schema that matches anything.",
    "default": "Default value",
    "examples": ["Anything", 4035]
} 

评论

$comment 关键字用于添加注释/注释，其值必须是字符串。

枚举值

enum关键字用于定义枚举值（固定值集）。这必须是一个至少包含一个值的数组，并且每个值必须是唯一的。另外，type 和 enum 是并行的，必须同时满足，如下例所示。

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

恒定值

const 关键字用于定义常量值，如以下示例所示。

 
{
    "properties": {
        "country": {
            "const": "United States of America"
        }
    }
} 

const 是 enum 的语法糖，因此以下两个定义是等效的：

 
{ "const": "United States of America" }
{ "enum": [ "United States of America" ]} 

8) $schema 关键字

$schema 关键字用于声明 JSON 架构版本。我们建议所有 JSON 架构都声明 $schema 并使其成为架构中的第一个键值对，如以下示例所示。

 
{"$schema": "http://json-schema.org/draft-04/schema#"} 

如果需要声明特定版本的 JSON Schema，可以设置 $schema 的值，如下所示：

• http://json-schema.org/draft-07/schema#
• http://json-schema.org/draft-06/schema#
• http://json-schema.org/draft-04/schema#

9) $ref 关键字

$ref 关键字用于引用另一个位置的模式片段，其值是 URI 引用。对于引用同一文档的架构片段，$ref 值必须以井号 (#) 开头。例如：

{ “$ref”: “#/定义/地址” }

在上面的例子中，“#/definitions/address”的意思是：

• 转到文档的根目录。
• 找到“definitions”键的值。
• 在该对象中，找到键“address”的值。

如果您想引用另一个架构文件：

{ “$ref”: “definitions.json#/address” }

一个完整的例子如下所示：

 
{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "definitions": {
        "address": {
            "type": "object",
            "properties": {
                "street_address": { "type": "string" },
                "city": { "type": "string" },
                "state": { "type": "string" }
            },
            "required": ["street_address", "city", "state"]
        }
    },
    "type": "object",
    "properties": {
        "billing_address": { "$ref": "#/definitions/address" },
        "shipping_address": { "$ref": "#/definitions/address" }
    }
} 

您还可以使用 $ref 关键字引用当前模式的部分内容（类似于编程中的递归）。例如，假设您有一个包含数组 Children 的 person 架构，其中每个数组也是一个 person 实例，如以下示例所示：

 
{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "definitions": {
        "person": {
            "type": "object",
            "properties": {
                "name": { "type": "string" },
                "children": {
                    "type": "array",
                    "items": { "$ref": "#/definitions/person" },
                    "default": []
                }
            }
        }
    },
    "type": "object",
    "properties": {
        "person": { "$ref": "#/definitions/person" }
    }
} 

10) $id 关键字

$id 关键字的值是 URI 引用，有两个用途：

• 为您的架构声明一个唯一标识符。
• 声明一个可以引用 $ref 的基本 URI。

例如，如果您想引用 https://it-kiso.com/ 域名的 schema，您可以这样设置 $id：

{“$id”：“https://it-kiso.com/schemas/address.json”}

上面定义了$id后，如果想用$ref来引用同域名的其他schema，可以简写成这样：

{ “$ref”: “person.json” }

一旦了解了 JSON Schema，您就可以使用它来验证 JSON 数据。互联网上有很多 JSON Schema 库，您可以在JSON Schema 官方网站上找到合适的库。

除了使用第三方库之外，还可以通过在线工具（例如https://jsonschemaint.com/#!/version/draft-04/markup/json ）使用架构。