迈向稳定的 JSON Schema

大约在去年这个时候，我在 API 规范大会上主持了一场关于 JSON Schema 未来的讨论。最热门的话题是，JSON Schema 什么时候会“完成”。当然，我们经常听到这个问题。这个问题源于我们发布版本上的“草稿”标签。“草稿”这个词多年来给我们的社区带来了不少困惑，所以让我们花点时间来理解它的来源。

为什么是“草稿”？

JSON Schema 一直在松散地遵循 IETF 标准跟踪 RFC 流程。这意味着我们的发布形式是互联网草案 (I-D)。这就是我们称它们为草稿的原因。但是，由于 JSON Schema 在生产系统中的广泛使用，将其像典型的 I-D 一样对待是不可能的。因此，我们使用“草稿”这个词有点像遗留产物，因为 IETF 流程在 JSON Schema 上更有意义。

这是一个问题，因为当人们听到“草稿”时，他们会听到“未完成”或“未准备好投入生产”。这不是我们对待我们发布版本的方式。预期并鼓励每个版本都投入生产使用。这与 OpenAPI 发布新版本没什么不同。没有人会问 OpenAPI 什么时候会“完成”。JSON Schema 只是因为我们称我们的版本为“草稿”而被不同地看待。

真正的问题

但这不仅仅是一个品牌问题。当人们问 JSON Schema 什么时候会脱离“草稿”时，他们真正想表达的意思是，JSON Schema 什么时候会“稳定”。他们希望能够编写一个模式，并确保无论 JSON Schema 如何在未来发展，它都将以相同的方式继续工作。他们希望能够更新他们的依赖项，而不必更新那些运行良好的模式。

这也影响到库维护人员。需要在没有向后或向前兼容性保证的情况下支持多个版本的 JSON Schema 会变得很麻烦，并且导致许多维护人员放弃支持较旧的版本。当这种情况发生时，用户可能会被迫选择更新所有未损坏的现有模式，或者锁定在不再支持的 JSON Schema 库版本上。

我们的解决方案

这些是我们将在下一个版本中努力解决的问题。而不是像每次发布都发布一个新的不可变且不兼容的 JSON Schema 版本，我们的下一个版本将是一个长期存在的稳定且不断发展的版本。在这种情况下，“稳定”意味着任何更改都必须遵循严格的向后和向前兼容性要求。这将非常类似于 JavaScript，因为它在发展过程中，你始终可以确保你的现有模式将继续与你使用的任何 JSON Schema 库一起工作，但使用新功能存在风险，因为并非所有库都已实现这些功能。

这种稳定且不断发展的规范的愿景与 IETF 流程并不完全契合。我们考虑过一些途径，但没有提出任何我们认为能让我们继续发展标准并在短期内摆脱“草稿”的方案。因此，实现我们愿景的第一步是将我们的主要规范开发与 IETF 流程分离。这种分离使我们能够为主要规范开发追求一种更符合我们愿景的新模型。

无论你是否喜欢 JavaScript 语言的发展方向，它似乎已经为允许持续发展而没有牺牲互操作性和持久性找到了一个有效流程。这就是我们选择将我们的新流程建立在用于发展 JavaScript 语言的流程上的原因。在我们下一个版本中，你今天使用的大多数关键字和功能将被声明为稳定，并且它们将永远不会以向后不兼容的方式更改。我们目前不方便稳定的功能和关键字将成为我们正在努力定义的新的分阶段发布流程的一部分。分阶段发布流程的目标是确保功能获得足够的实施、测试和真实世界的验证，让我们有信心将其声明为稳定。该流程不仅应该让我们更有信心，而且应该让我们能够更快地实现这种信心。

标准考虑

从下一个版本开始，JSON Schema 规范将在我们的网站上自行发布。

关于自行发布的一个担忧是其他标准是否能够引用 JSON Schema 规范。我们已经从参与标准制定的个人那里收到了反馈，他们认为我们的方法是可接受的，因为我们与 OpenJS 基金会会员资格，他们可以在其标准中引用我们的规范。我们不知道所有标准机构是否会得出相同的结论，但此反馈让我们相信这不会是一个重大问题。

虽然主规范将自行发布，但我们仍在继续通过 IETF 流程工作，只要有意义。例如，我们正在通过 HTTPAPIs WG 注册我们的媒体类型，例如application/schema+json。我们还在研究通过 IETF 标准化可重用组件，例如相对 JSON 指针。

底线

关于新流程的详细信息将在最终确定后在另一篇文章中分享，但这里是一些用户可以预期的结果。

• 如果你只使用稳定功能，你将保证 JSON Schema 库之间的互操作性，并且你将永远不需要仅仅为了跟上新版本而更新你的模式。
• 你可以在新功能稳定之前安全地使用它们，只要使用你模式的库支持该功能。
• 兼容性/互操作性保证仅适用于下一个版本及以后的版本。你需要将你的模式更新到稳定版本，但你将不需要在 JSON Schema 发展过程中不断更新它们。
• 自定义方言和词汇表将继续作为自定义和扩展 JSON Schema 的核心概念。
• 实现者不需要维护不同的代码来支持过去的稳定版本。支持 2025 年版本的库将自动支持 2023 年和 2024 年版本。过去的稳定版本将不再需要维护为不同的版本。但是，继续支持“草稿”版本的实现仍然需要将这些版本作为与当前稳定版本不同的版本进行维护。