2019-09 版本说明

对于绝大多数模式作者来说，我们希望这些更改的影响最小。

最有可能令人沮丧的是，format 现在不再被默认视为验证断言（尽管应用程序或用户仍然可以配置验证器将其视为断言）。我们认为这是可以接受的，因为许多模式作者已经对它不一致的行为感到非常沮丧。

对于实现者来说，需要考虑的东西要多得多，关于实现主题的进一步指导即将发布。

• 不兼容更改
• 半不兼容更改
• 注释、错误和输出
• 关键字更改
  • 核心词汇表
  • 应用器词汇表
  • 验证词汇表
  • 格式词汇表
  • 内容词汇表
  • 元数据词汇表
  • 超级模式词汇表

有关每个文档的更改的基本列表，请参阅其变更日志

• 核心
• 验证
• 超级模式

不兼容更改

• 默认情况下，format 不再是断言。之所以这样做是因为 format 作为断言的不一致实现一直是模式作者遇到各种令人惊讶问题的一个无穷无尽的来源。默认行为现在将是可预测的，即使不是理想的。有几种方法可以打开断言功能，如下所述。但是，我们建议在应用程序层进行语义验证。
• 普通名称片段不再使用 $id 定义，而是使用新的关键字 $anchor（它具有不同的语法）。
• $id 不再包含片段（除了可能为空的片段，尽管不鼓励这样做）。
• 在可以使用多个 URI 表示同一模式的情况中，现在不鼓励使用其中一些 URI。这些 URI 被认为很少使用，因为涉及的行为相当令人困惑，直到 draft-07 的更新版本（draft-handrews-json-schema-01）才得到很好的解释。如果您对这些内容不太了解，那么您可能是安全的。

半不兼容更改

这些关键字的旧语法不是错误（默认元模式仍然验证它们），因此实现可以提供兼容模式。但是，迁移到新关键字非常简单，应优先考虑。

• definitions 现在是 $defs
• dependencies 已拆分为 dependentSchemas 和 dependentRequired

注释、错误和输出

注释关键字，如 title、readOnly 和 default 一直都是 JSON Schema 的一部分，但没有关于如何使用它们的指导。此草案正式化了实现如何将注释信息提供给应用程序。

同样，以前也没有关于验证失败时什么构成有用错误报告的指导。

为了解决这两个问题，我们现在建议实现支持一种或多种标准化的 输出格式。

关键字更改

所有关键字现在都已组织到 词汇表 中，核心和验证规范包含多个词汇表。在此过程中，一些关键字已从验证移动到核心。

核心词汇表

核心规范，第 8 节

应用器词汇表

核心规范，第 9 节

这些关键字以前在验证规范中

其他应用器词汇表关键字是 items, additionalItems, properties, patternProperties, additionalProperties, anyOf, allOf, oneOf, not, if, then, else.

验证词汇表

验证规范，第 6 节

格式词汇表

验证规范，第 7 节

由于 format 关键字的可选性，它一直存在问题。从来没有任何方法可以确保处理您的模式的实现支持 format，或者如果支持，在何种程度上验证每种类型的格式。理论上，由于每个格式都引用了一个标准规范，如果支持一个格式，它应该始终如一地工作。实际上，情况并非如此。

应用程序可以通过两种方式验证格式：它可以依靠 JSON 模式实现来验证它们（这可能会有或可能不会产生预期的结果），或者它可以记录 format 关键字的使用位置，并基于此执行自己的验证。通过将 format 视为一个 注释关键字 并支持 基本、详细或详细的输出格式 来支持第二种方法。

为了对该系统施加一些可预测性，该行为已在以下几个方面发生了变化。这里的关键区别在于，format 验证现在默认情况下是关闭的，但可以配置为打开。在 draft-07 中，它是默认打开的（但可能未实现），并且可以配置为关闭。

在以下图表中，“支持”列是指实现是否以及（对于 2019-09）在何种程度上声称支持 format 关键字。“配置”列是指是否以某种方式（在配置文件中，或通过命令行选项，或其他方式）配置了 format 的某些非默认行为。

draft-07 行为摘要

显然，每个实现都将在模式之间始终如一地工作，尽管一些格式可能比其他格式支持得更彻底，尽管规范中的措辞是如此。但是，在实践中，复杂的格式在每个实现中的支持程度不同。如果它们得到支持的话。

2019-09 行为摘要

本草案的目标是使默认行为可预测，并将不一致的行为作为一种可选功能。这并非完全令人满意，但我们认为这是减少围绕意外结果的投诉数量的一个好的第一步。这样，至少应该减少一些意外。

• “尽力”验证是一个相当弱的要求，这与当今实践中的工作方式相一致。简单的格式可能是完全有效的，复杂的格式可能被最小限度地验证甚至根本不被验证。

• “完全语法”验证意味着您可以期望进行相当彻底的语法验证，这可能与实现语言中可用的任何通用库所能做到的相一致。对于诸如 IP 地址和日期之类的格式，这被期望是完整的验证。对于诸如电子邮件地址之类的更复杂格式，支持可能仍然存在很大差异。目前尚不清楚有多少实现曾经提供过这种级别的支持。

• 词汇表错误的结果意味着实现将拒绝处理该模式，因为它无法满足词汇表要求。

请注意，鉴于几乎没有 draft-07 或更早的实现提供对每个格式的严格和完整的验证，似乎不太可能有任何实现能够在实践中支持选项 3 选项。

此外，还添加了两个新格式，并更新了一个规范引用

内容词汇表

验证规范，第 8 节

这些关键字现在纯粹指定为注释，而不是断言。围绕实现如何在验证过程之外可选地提供有关此信息的进一步自动处理提供了一些指导。

元数据词汇表

验证规范，第 9 节

超级模式词汇表

超模式规范，第 5 和 6 节