声明方言

JSON Schema 的一个版本被称为 方言。方言表示可以用来评估模式的 关键字 和语义集。每个 JSON Schema 版本都是 JSON Schema 的一个新方言。JSON Schema 提供了一种方法，让您可以声明模式符合哪个方言，并提供描述您自己的自定义方言的方法。

$schema

$schema 关键字用于声明模式是为哪个 JSON Schema 方言编写的。 $schema 关键字的值也是模式的标识符，可以用来验证模式是否根据 $schema 标识的方言验证有效。描述另一个模式的模式被称为 “元模式”。

$schema 应用于整个文档，必须位于根级别。它不适用于外部引用的 ($ref, $dynamicRef) 文档。这些模式需要声明自己的 $schema。

如果未使用 $schema，实现 可能会允许您外部指定一个值，或者它可能会对应该使用哪个规范版本来评估模式做出假设。建议所有 JSON Schema 都具有 $schema 关键字，以向读者和 工具 传达预期使用的规范版本。因此，大多数情况下，您希望在模式的根部使用此关键字

1"$schema": "https://json-schema.fullstack.org.cn/draft/2020-12/schema"

词汇

草案 2019-09 中的新功能

文档即将推出

特定草案信息

在引入词汇之前，您仍然可以使用自定义关键字扩展 JSON Schema，但这个过程要正式得多。您首先需要一个包含您的自定义关键字的元模式。最好的方法是制作您想要扩展的版本的元模式的副本，并将您的更改应用于您的副本。您需要选择一个自定义 URI 来标识您的自定义版本。此 URI 不能是用于标识官方 JSON Schema 规范草案的 URI 之一，并且可能应该包含您拥有的域名。您可以将此 URI 与 $schema 关键字一起使用，以声明您的模式使用您的自定义版本。

指南

JSON Schema 的优势之一是它可以用 JSON 编写，并在各种环境中使用。例如，它可以用于前端和后端的 HTML 表单验证。使用自定义词汇的问题在于，每个要使用模式的环境都需要了解如何评估词汇的关键字。元模式可用于确保模式的正确编写，但每个实现都需要自定义代码来了解如何评估词汇的关键字。

元数据关键字的互操作性最强，因为它们不会影响验证。例如，您可以添加一个 units 关键字。这将始终按照符合规范的验证器的预期工作。

schema

{ "type": "number", "units": "kg"}

data

42

符合模式

data

"42"

不符合模式

自定义关键字的下一个最佳选择是那些不适用于其他模式并且不修改现有关键字行为的关键字。一个 isEven 关键字就是一个例子。在某些验证胜过没有验证的上下文中，例如在浏览器中验证 HTML 表单，此模式将执行得尽可能好。仍然需要进行完整验证，并且应该使用理解自定义关键字的验证器。

schema

{ "type": "integer", "isEven": true}

data

2

符合模式

这通过了，因为验证器不理解 isEven

data

3

符合模式

该模式并没有完全受损，因为它不理解 isEven

data

"3"

不符合模式

互操作性最弱的自定义关键字类型是那些应用其他模式或修改现有关键字行为的关键字。一个例子是类似于 requiredProperties 的东西，它声明属性并使它们成为必需属性。这个例子展示了当用不理解自定义关键字的验证器评估时，模式如何变得几乎完全无用。这并不一定意味着 requiredProperties 是一个糟糕的关键字想法，只是如果模式可能需要在不理解自定义关键字的上下文中使用，它就不是正确选择。

schema

{ "type": "object", "requiredProperties": { "foo": { "type": "string" } }}

data

{ "foo": "bar" }

符合模式

这通过了，因为 requiredProperties 不被理解

data

{}

符合模式

这通过了，因为 requiredProperties 不被理解

data

{ "foo": 42 }

符合模式