入门

创建你的第一个模式

JSON Schema 是一种词汇表，你可以用它来注释和验证 JSON 文档。本教程指导你完成创建 JSON Schema 的过程。

创建 JSON Schema 后，你可以使用你选择的语言中的验证器，将示例数据与你的模式进行验证。请访问 工具 并选择最适合你需求的验证器。

如果你已经知道如何创建 JSON Schema 并且正在寻找不同的 JSON Schema 用例，例如模式生成、代码生成、文档、UI 生成或 JSON Schema 处理或转换，请访问 工具 并探索 JSON Schema 生态系统中提供的强大工具。

menu-icon目录

概述

本指南中使用的示例是一个产品目录，它使用 JSON 对象存储数据，例如以下内容

数据
{ "productId": 1, "productName": "A green door", "price": 12.50, "tags": [ "home", "green" ]}

每个目录中的产品都包含以下信息：

  • productId: 产品标识符
  • productName: 产品名称
  • price: 消费者价格
  • tags: 可选的标识标签数组

JSON 对象是人类可读的，但它不包含任何上下文或元数据。从查看对象无法判断键的含义或可能的输入。JSON Schema 是一种为这些问题提供答案的标准。在本指南中，您将创建一个 JSON Schema 文档，用于描述一组 JSON 数据的结构、约束和数据类型。

JSON Schema 简介

实例是正在验证或描述的 JSON 文档，而模式是包含描述的文档。

最基本的模式是一个空的 JSON 对象，它不限制任何内容，允许任何内容，也不描述任何内容。

数据
{}

通过在模式中添加验证关键字，您可以对实例应用约束。例如，您可以使用 type 关键字将实例约束为对象、数组、字符串、数字、布尔值或 null。

数据
{ "type": "string" }

JSON Schema 准备好超媒体，非常适合注释您现有的基于 JSON 的 HTTP API。JSON Schema 文档由 URI 标识，这些 URI 可用于 HTTP 链接标头和 JSON Schema 文档中，以允许递归定义。

创建模式定义

要创建基本模式定义，请定义以下关键字：

  • $schema: 指定模式符合哪个版本的 JSON Schema 标准。
  • $id: 为模式设置 URI。您可以使用此唯一 URI 从同一文档内部或从外部 JSON 文档引用模式的元素。
  • title 和 description: 说明模式的意图。这些关键字不会对正在验证的数据添加任何约束。
  • type: 定义对 JSON 数据的第一个约束。在下面的产品目录示例中，此关键字指定数据必须是 JSON 对象。

例如

模式
{ "$schema": "https://json-schema.fullstack.org.cn/draft/2020-12/schema", "$id": "https://example.com/product.schema.json", "title": "Product", "description": "A product in the catalog", "type": "object"}

这些关键字使用 JSON 键定义。通常，正在验证的数据包含在 JSON 数据文档中，但 JSON Schema 也可以验证包含在其他内容类型（如文本或 XML 文件）中的 JSON 数据。

在 JSON Schema 术语中，$schema 和 $id 是 模式关键字，title 和 description 是 模式注释，而 type 是 验证关键字。

定义属性

本节添加了 properties 关键字。在 JSON Schema 术语中，properties 是一个 验证关键字。当您定义 properties 时，您将创建一个对象，其中每个属性表示要验证的 JSON 数据中的一个键。您还可以指定对象中定义的哪些属性是必需的。

添加属性对象

使用产品目录示例，productId 是唯一标识产品的数值。由于这是产品的规范标识符，因此它是必需的。

要将 properties 对象添加到模式中

  1. 将 properties 验证关键字添加到模式的末尾

    1 ...
2   "title": "Product",
3   "description": "A product from Acme's catalog",
4   "type": "object",
5   "properties": {
6     "productId": {}
7   }

  2. 添加 productId 关键字，以及以下模式注释

    • description：描述 productId 是什么。在本例中，它是产品的唯一标识符。

    • type：定义期望的数据类型。对于本例，由于产品标识符是数值，因此使用 integer。

      1...
2  "properties": {
3    "productId": {
4      "description": "The unique identifier for a product",
5      "type": "integer"
6    }
7  }

使用新的 properties 验证关键字，整个模式如下所示

模式
{ "$schema": "https://json-schema.fullstack.org.cn/draft/2020-12/schema", "$id": "https://example.com/product.schema.json", "title": "Product", "description": "A product from Acme's catalog", "type": "object", "properties": { "productId": { "description": "The unique identifier for a product", "type": "integer" } }}

以下示例添加了另一个必需的键，productName。此值是字符串

模式
{ "$schema": "https://json-schema.fullstack.org.cn/draft/2020-12/schema", "$id": "https://example.com/product.schema.json", "title": "Product", "description": "A product from Acme's catalog", "type": "object", "properties": { "productId": { "description": "The unique identifier for a product", "type": "integer" }, "productName": { "description": "Name of the product", "type": "string" } }}

现在 properties 对象包含两个键，分别是 productId 和 productName。 当 JSON 数据根据此模式进行验证时，任何包含这两个字段中无效数据的文档都会导致验证失败。

定义必需属性

本节介绍如何指定某些属性是必需的。 本示例将现有的两个键设为必需，并添加另一个名为 price 的必需键。 price 键具有 description 和 type，就像其他键一样，但它还指定了最小值。 由于商店中没有免费商品，因此每个产品都要求价格值大于零。 使用 exclusiveMinimum 验证关键字来定义此值。

定义必需属性

  1. 在 properties 对象中，添加 price 键。包含通常的 schema 注释 description 和 type，其中 type 是一个数字

    1   "properties": {
2     ...
3     "price": {
4       "description": "The price of the product",
5       "type": "number"
6     }
7   }

  2. 添加 exclusiveMinimum 验证关键字并将值设置为零

    1   "price": {
2     "description": "The price of the product",
3     "type": "number",
4     "exclusiveMinimum": 0
5   }

  3. 将 required 验证关键字添加到 schema 的末尾，在 properties 对象之后。将 productID、productName 和新的 price 键添加到数组中

    1 ...
2   "properties": {
3     ...
4     "price": {
5       "description": "The price of the product",
6       "type": "number",
7       "exclusiveMinimum": 0
8     },
9   },
10   "required": [ "productId", "productName", "price" ]

有了新的 required 关键字和 price 键，整个 schema 看起来像这样

模式
{ "$schema": "https://json-schema.fullstack.org.cn/draft/2020-12/schema", "$id": "https://example.com/product.schema.json", "title": "Product", "description": "A product from Acme's catalog", "type": "object", "properties": { "productId": { "description": "The unique identifier for a product", "type": "integer" }, "productName": { "description": "Name of the product", "type": "string" }, "price": { "description": "The price of the product", "type": "number", "exclusiveMinimum": 0 } }, "required": [ "productId", "productName", "price" ]}

exclusiveMinimum 验证关键字设置为零，这意味着只有大于零的值被视为有效。要将零包含为有效选项，可以使用 minimum 验证关键字代替。

定义可选属性

本节介绍如何定义可选属性。在本例中，使用以下标准定义名为 tags 的关键字

  • tags 关键字是可选的。
  • 如果包含 tags，它必须包含至少一个项目。
  • 所有标签必须是唯一的。
  • 所有标签必须是文本。

要定义可选属性

  1. 在 properties 对象中，添加 tags 关键字。包含通常的 schema 注释 description 和 type，并将 type 定义为数组

    1 ...
2   "properties": {
3     ...
4     "tags": {
5       "description": "Tags for the product",
6       "type": "array"
7     }
8   }

  2. 添加一个新的验证关键字 items 来定义数组中出现的内容。例如，string

    1 ...
2     "tags": {
3       "description": "Tags for the product",
4       "type": "array",
5       "items": {
6         "type": "string"
7       }
8     }

  3. 为了确保数组中至少有一个项目，请使用 minItems 验证关键字

    1 ...
2     "tags": {
3       "description": "Tags for the product",
4       "type": "array",
5       "items": {
6         "type": "string"
7       },
8       "minItems": 1
9     }

  4. 为了确保数组中的每个项目都是唯一的，请使用 uniqueItems 验证关键字并将它设置为 true

    1 ...
2     "tags": {
3       "description": "Tags for the product",
4       "type": "array",
5       "items": {
6         "type": "string"
7       },
8       "minItems": 1,
9       "uniqueItems": true
10     }

有了新的 tags 关键字，整个 schema 看起来像这样

模式
{ "$schema": "https://json-schema.fullstack.org.cn/draft/2020-12/schema", "$id": "https://example.com/product.schema.json", "title": "Product", "description": "A product from Acme's catalog", "type": "object", "properties": { "productId": { "description": "The unique identifier for a product", "type": "integer" }, "productName": { "description": "Name of the product", "type": "string" }, "price": { "description": "The price of the product", "type": "number", "exclusiveMinimum": 0 }, "tags": { "description": "Tags for the product", "type": "array", "items": { "type": "string" }, "minItems": 1, "uniqueItems": true } }, "required": [ "productId", "productName", "price" ]}

由于新关键字不是必需的，因此 required 部分没有变化。

创建嵌套数据结构

前面的示例描述了一个只有单层级的扁平 schema。本节介绍如何在 JSON Schema 中使用嵌套数据结构。

要创建嵌套数据结构

  1. 在 properties 对象中，创建一个名为 dimensions 的新键

    1 ...
2   "properties": {
3   ...
4     "dimensions": {}
5   }

  2. 将 type 验证关键字定义为 object

    1 ...
2   "dimensions": {
3     "type": "object"
4   }

  3. 添加 properties 验证关键字以包含嵌套数据结构。在新 properties 关键字中，添加 length、width 和 height 的关键字，它们都使用 number 类型

    1 ...
2   "dimensions": {
3     "type": "object",
4     "properties": {
5       "length": {
6         "type": "number"
7       },
8       "width": {
9         "type": "number"
10       },
11       "height": {
12         "type": "number"
13       }
14     }
15   }

  4. 为了使这些属性中的每一个都是必需的，请在 dimensions 对象中添加一个 required 验证关键字

    1 ...
2   "dimensions": {
3     "type": "object",
4     "properties": {
5       "length": {
6         "type": "number"
7       },
8       "width": {
9         "type": "number"
10       },
11       "height": {
12         "type": "number"
13       }
14     },
15     "required": [ "length", "width", "height" ]
16 }

使用新的嵌套数据结构，整个 schema 看起来像这样

模式
{ "$schema": "https://json-schema.fullstack.org.cn/draft/2020-12/schema", "$id": "https://example.com/product.schema.json", "title": "Product", "description": "A product from Acme's catalog", "type": "object", "properties": { "productId": { "description": "The unique identifier for a product", "type": "integer" }, "productName": { "description": "Name of the product", "type": "string" }, "price": { "description": "The price of the product", "type": "number", "exclusiveMinimum": 0 }, "tags": { "description": "Tags for the product", "type": "array", "items": { "type": "string" }, "minItems": 1, "uniqueItems": true }, "dimensions": { "type": "object", "properties": { "length": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" } }, "required": [ "length", "width", "height" ] } }, "required": [ "productId", "productName", "price" ]}

新的 required 验证关键字只适用于 dimensions 键的范围。

添加外部引用

本节介绍如何引用 schema 之外的资源。跨多个数据结构共享 schema 是一种使它们更容易使用、阅读和保持最新的常用方法。到目前为止，产品目录 schema 是自包含的。本节创建一个新的 schema，然后在产品目录 schema 中引用它。

以下 schema 验证地理位置

模式
{ "$id": "https://example.com/geographical-location.schema.json", "$schema": "https://json-schema.fullstack.org.cn/draft/2020-12/schema", "title": "Longitude and Latitude", "description": "A geographical coordinate on a planet (most commonly Earth).", "required": [ "latitude", "longitude" ], "type": "object", "properties": { "latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "longitude": { "type": "number", "minimum": -180, "maximum": 180 } }}

要在产品目录 schema 中引用此 schema

  1. 在 properties 对象中，添加一个名为 warehouseLocation 的键

    1 ...
2   "properties": {
3   ...
4     "warehouseLocation": {}
5   }

  2. 要链接到外部地理位置 schema，请添加 $ref schema 关键字和 schema URL

    1 ...
2   "warehouseLocation": {
3     "description": "Coordinates of the warehouse where the product is located.",
4     "$ref": "https://example.com/geographical-location.schema.json"
5   }

有了外部 schema 引用，整个 schema 看起来像这样

模式
{ "$schema": "https://json-schema.fullstack.org.cn/draft/2020-12/schema", "$id": "https://example.com/product.schema.json", "title": "Product", "description": "A product from Acme's catalog", "type": "object", "properties": { "productId": { "description": "The unique identifier for a product", "type": "integer" }, "productName": { "description": "Name of the product", "type": "string" }, "price": { "description": "The price of the product", "type": "number", "exclusiveMinimum": 0 }, "tags": { "description": "Tags for the product", "type": "array", "items": { "type": "string" }, "minItems": 1, "uniqueItems": true }, "dimensions": { "type": "object", "properties": { "length": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" } }, "required": [ "length", "width", "height" ] }, "warehouseLocation": { "description": "Coordinates of the warehouse where the product is located.", "$ref": "https://example.com/geographical-location.schema.json" } }, "required": [ "productId", "productName", "price" ]}

根据 schema 验证 JSON 数据

现在您已经创建了 JSON Schema，是时候使用 JSON 数据 来验证它，使用 JSON Schema 验证器。

验证器是一个实现 JSON Schema 规范的工具。所有验证器都以类似的方式工作：它们将 JSON Schema 和 JSON 实例作为输入，并返回验证结果作为输出。

How JSON Schema works

要自己尝试，请访问 工具 并选择最适合您需求的验证器，或者使用以下提供的编辑器来探索不同的 Schema 和 Instance，并查看不同的验证结果。

JSON Schema

1

JSON Instance

1

验证结果

red cross

下一步？

现在您已经了解了如何创建 JSON Schema 并使用它来验证 JSON 数据，我们邀请您继续您的 JSON Schema 之旅

  • 访问 参考文档，了解有关 JSON Schema 的更多信息。
  • 探索 Spec 的当前版本的详细信息 2020-12。

如果你已经知道如何创建 JSON Schema 并且正在寻找不同的 JSON Schema 用例，例如模式生成、代码生成、文档、UI 生成或 JSON Schema 处理或转换，请访问 工具 并探索 JSON Schema 生态系统中提供的强大工具。

需要帮助？

您发现这些文档有帮助吗？

帮助我们让我们的文档变得更好！

在 JSON Schema，我们像重视其他任何类型的贡献一样重视文档贡献！

在 Github 上编辑此页面
了解如何贡献

仍然需要帮助？

学习 JSON Schema 通常很令人困惑，但别担心，我们在这里帮助您！。

在 Github 上向社区提问
在 Slack 上向社区提问