当前位置：首页 > news >正文

JSON Schema 2020-12 介绍

news 来源：原创 2025/6/14 7:29:27

一、概述

JSON Schema 是一种用于描述和验证 JSON 数据结构的规范，它提供了一种声明性的方法来定义 JSON 数据的格式、内容和约束条件。通过 JSON Schema，可以确保 JSON 数据符合预期的结构，满足特定的要求，从而提高数据交换的可靠性和一致性。

JSON Schema 2020-12 是 JSON Schema 规范的一个版本，于 2020 年 12 月发布。它是继 2019-09 版本之后的一个更新，包含了一些新的特性和改进，以增强模式定义的能力和灵活性。

二、历史背景

初始发布（2010 年）：
- JSON Schema 的早期版本是在 2010 年左右发布的，其目的是为 JSON 数据提供一个类似于 XML Schema 的模式定义方法。
草案版本：
- JSON Schema 规范以 IETF 草案的形式发布，版本号通常以年份和月份标识，例如 draft-07（2017 年 7 月）。
重要版本：
- draft-04（2013 年）：广泛采用的版本，许多工具和库都支持该版本。
- draft-06 和 draft-07（2017 年）：引入了对正则表达式、if/then/else 等的支持。
- 2019-09（draft-08）：开始使用年份和月份作为版本号，引入了 $defs、动态引用等新特性。
- 2020-12：本次介绍的版本，进一步完善了规范。

三、与 OpenAPI 的关系

OpenAPI 3.x：
- OpenAPI 使用 JSON Schema（遵循 draft-05 及更高版本）来定义 API 的请求和响应数据模型。
- 通过在 OpenAPI 中集成 JSON Schema，可以精确地描述接口的数据结构，方便客户端和服务器的开发。
兼容性：
- OpenAPI 3.1 开始，完全支持 JSON Schema 2020-12 规范，这意味着可以在 OpenAPI 中使用最新的 JSON Schema 特性。

四、核心概念

模式（Schema）：
- 描述 JSON 数据结构的蓝图，定义了数据的类型、格式、必需属性等。
关键词（Keywords）：
- JSON Schema 使用特定的关键词来描述约束条件，如 type、properties、items、required 等。
验证（Validation）：
- 通过将 JSON 数据与模式进行比较，验证数据是否符合模式所定义的约束。
引用（Ref）：
- 使用 $ref 关键词，可以在模式中引用其他模式，实现模式的复用和模块化。

五、JSON Schema 的基础结构

$schema：
- 指定所遵循的 JSON Schema 版本的 URI。
- 示例："$schema": "https://json-schema.org/draft/2020-12/schema"
基本类型验证：
- type：指定数据的类型，如 object、array、string、number、boolean、null。
对象类型的关键词：
- properties：定义对象的属性及其子模式。
- required：指定对象中必需的属性名称数组。
- additionalProperties：控制对象中未在 properties 中定义的额外属性。
- patternProperties：使用正则表达式匹配属性名称，应用相应的子模式。
数组类型的关键词：
- items：定义数组元素的模式，可以是单一模式或模式数组。
- additionalItems：当 items 是一个模式数组时，控制额外元素。
- minItems、maxItems：指定数组元素的最小和最大数量。
- uniqueItems：布尔值，指定数组元素是否必须唯一。
字符串类型的关键词：
- minLength、maxLength：字符串的最小和最大长度。
- pattern：用于匹配字符串的正则表达式。
数值类型的关键词：
- minimum、maximum：指定数值的最小和最大值。
- exclusiveMinimum、exclusiveMaximum：严格小于或大于指定的值。
- multipleOf：指定数值必须是某个值的倍数。
通用关键词：
- enum：指定可以接受的固定值列表。
- const：指定一个固定的常量值。
- $ref：引用其他模式的 URI。

六、动态引用（Dynamic References）

动态引用是 2020-12 版本引入的重要特性，主要通过 $dynamicRef 和 $dynamicAnchor 实现。

$dynamicAnchor：
- 用于定义动态锚点，在模式中标记一个位置，供动态引用使用。
- 示例：
```
{"$dynamicAnchor": "node","type": "object","properties": {"child": { "$dynamicRef": "#node" }}
}
```
$dynamicRef：
- 类似于 $ref，但在引用解析时，会动态地向上查找具有匹配 $dynamicAnchor 的模式。
- 解决了在递归模式或组合模式中，无法使用相对引用的问题。

七、内容关键字的增强

contentEncoding：
- 指定字符串的编码方式，如 base64、quoted-printable。
- 示例：
```
{"type": "string","contentEncoding": "base64"
}
```
contentMediaType：
- 指定字符串内容的媒体类型（MIME type），如 application/json、text/html。
- 示例：
```
{"type": "string","contentMediaType": "image/png","contentEncoding": "base64"
}
```

contentSchema：

指定嵌入内容的模式定义，多用于字符串中包含嵌套的 JSON 数据时。

示例：

{"type": "string","contentMediaType": "application/json","contentSchema": {"type": "object","properties": {"name": { "type": "string" },"age": { "type": "integer", "minimum": 0 }}}
}

八、示例

示例：定义用户信息的 JSON Schema

{"$schema": "https://json-schema.org/draft/2020-12/schema","$id": "https://example.com/user.schema.json","title": "用户信息","description": "描述用户信息的模式","type": "object","properties": {"id": {"description": "用户唯一标识符","type": "string"},"name": {"description": "用户姓名","type": "string","minLength": 1},"email": {"description": "用户邮箱","type": "string","format": "email"},"age": {"description": "用户年龄","type": "integer","minimum": 0},"profileImage": {"description": "Base64 编码的用户头像","type": "string","contentEncoding": "base64","contentMediaType": "image/png"},"address": {"$ref": "https://example.com/address.schema.json"}},"required": ["id", "name", "email"]
}

解释：
- 使用 $schema 指定了模式所遵循的版本，即 2020-12。
- properties 中定义了用户的各个属性。
- 使用了 contentEncoding 和 contentMediaType 来描述 profileImage 的编码和媒体类型。
- 通过 $ref 引用了外部的地址模式，实现模式的复用和模块化。

九、应用场景

数据验证：
- 在数据传输和存储过程中，使用 JSON Schema 验证数据的完整性和正确性。
API 参数和响应验证：
- 定义 API 接口的请求参数和响应结构，确保客户端和服务器之间的数据格式一致。
配置文件验证：
- 验证系统或应用程序的配置文件是否符合预期的格式和内容要求。
文档生成：
- 根据 JSON Schema 自动生成数据格式的文档，提供给开发者或使用者参考。
代码生成：
- 根据模式生成数据模型的代码，实现对数据的读取、写入和操作。

十、工具和生态系统

JSON Schema 验证库：
- AJV：高性能 JSON Schema 验证器，支持最新的规范版本。
  
  链接：https://ajv.js.org/
- jsonschema：用于 Python 的 JSON Schema 验证库。
  
  链接：https://github.com/Julian/jsonschema
编辑器和 IDE 支持：
- VSCode：通过插件支持 JSON Schema 的语法高亮、自动补全和验证。
- JSON Schema Store：提供大量的公共 JSON Schema，自动与编辑器集成。
  
  链接：https://www.schemastore.org/
在线工具：
- JSON Schema 在线验证器：提供在线的模式编写和数据验证功能。
  
  链接：https://www.jsonschemavalidator.net/
文档生成工具：
- DocGen：根据 JSON Schema 生成人类可读的文档。
代码生成工具：
- quicktype：从 JSON Schema 生成多种语言的数据模型代码。
  
  链接：https://quicktype.io/