系统
浅色
深色JSON 超级模式草案 06 版本说明
从草案 luff-json-hyper-schema-00（草案 04）迁移到草案 wright-json-schema-hyperschema-01（草案 06）的版本说明。
该 草案 07 的迁移说明 提供了从草案 04 迁移到草案 07 的更直接的概述，通过跳过草案 05 和草案 06 的复杂中间状态。保留此页面是为了历史兴趣，但不建议那些只想使用最新草案的人使用。
面向实现者： 建议只实现草案 07，而不是草案 06 或更早的版本。
- 问：草案 04 和草案 06 之间有哪些不兼容的更改？
- 问：为什么在草案 06 发布之前对超级模式进行了多次重大更改？
- 问：为什么规范不再提及或像 HTML 一样运行？
- 问：那么我如何指示在链接上支持哪些 HTTP 方法？
- 问：真的吗。我如何明确指示在链接上支持哪些 HTTP 方法？
- 问：如果“targetSchema”不是响应，我该如何描述响应？
问：草案 04 和草案 06 之间有哪些不兼容的更改？
在草案 04 和 06 之间，我们对超级模式进行了重大重新审查，超级模式从未像 JSON Schema 验证那样被广泛采用。
虽然我们知道草案 06 中仍然存在重大差距，但我们认为这是一组很好的更改，可以用来收集反馈。随着草案 07 的发布，应该使用该草案或更高版本，而草案 06 成为历史上的好奇。
从草案 04 到草案 05 的更改
| 关键字 | 更改 | 后果 |
|---|---|---|
"base" | 替换查找最近的“self”链接以确定 "href" 的基本 URI | 如果您依赖“self”链接来更改基本 URI，请明确设置 "base" |
"rel" | 删除“full”关系 | 使用 "item" |
"rel" | 删除“instances”和“create”关系 | 使用 "collection" |
"rel" | 删除“root”关系 | 在您的 "href" URI 模板中使用片段 |
"fragmentResolution" | 已删除 | 媒体类型决定如何解释片段 |
"pathStart" | 已删除 | [没有替换] |
"method" | 更改回 HTML 表单语义 的“get”和“post”，而不是所有 HTTP 方法 | [由于反馈表明这令人困惑，因此在草案 06 中再次更改] |
从草案 05 到草案 06 的更改
| 关键字 | 更改 | 后果 |
|---|---|---|
"method" | 已删除 | 对于 HTTP 方法建议，请参阅问题 #73 和 #296（如果需要，使用 "method" 或 "allow" 作为扩展关键字）；不再需要指示如何使用 "schema" 和 "encType" |
"schema" | 已删除 | 使用 "hrefSchema"、"submissionSchema" 或 "targetSchema" |
"encType" | 已删除 | 对请求正文使用 "submissionEncType"；不再需要用于 URI 查询字符串 |
"hrefSchema" | 已添加 | 替换 "method": "get", "schema": {...}，具有附加功能 |
"submissionSchema" | 已添加 | 替换 "method": "post", "schema": {...} |
"submissionEncType" | 已添加 | 替换 "method": "post", "encType": "..." |
"href" | 删除预处理 | 将在未来的草案中进行替换和扩展 |
正确使用 "targetSchema"
虽然 "targetSchema" 在最近的草案中并没有改变其含义，但它却被广泛误解。因此，将它按规定使用可能会让人感觉像是发生了改变。
由于草案-04 强调将单个 HTTP 方法作为 "method" 值，许多用户将 "targetSchema" 解释为对 "method" 中方法的响应的暗示。这从一开始就是错误的；所有草案都将此关键字定义为描述目标资源的表示形式，该表示形式作为对 HTTP GET 的响应出现，但可能出现在其他响应中，也可能不出现。
草案-06 阐明了这种用法，并提供了关于它与不同 HTTP 方法一起使用的指导。这包括将 "targetSchema" 用作 PUT 和 PATCH 的请求描述。在草案-04 中，许多用户使用 "schema" 来描述 PUT 和 PATCH 请求，这是没有必要的。
然而，"targetHints" 提案 已被接受加入草案-07。除其他事项外，它能够暗示 "Accept-Patch"，这对于正确使用 "targetSchema" 与 HTTP PATCH 是必需的。草案-07 中将包含示例和详细指导。
问：为什么在草案-06 发布之前对超模式进行了一些重大更改？
答：在最终审查期间，人们发现关于如何使用该规范没有达成共识。这些后期更改对于发布一个具有明确含义的规范是必要的，这样我们才能获得对其内容的反馈，而不是不同的解释。最初我们试图简单地澄清现有内容，但后来我们意识到，人们一开始就对现有内容没有达成一致。
问：为什么该规范不再提及或表现得像 HTML？
答：我们达成共识，认为现有的类比弊大于利，原因有两个：
- 从草案-03 到草案-04 的改变，让
"method"可以表示任何 HTTP 方法，而不是 HTML 的<form method="...">"get" 和 "post" 值，这破坏了最初与 HTML 的类比，而试图将其改回来则没有得到认可。 - 只能使用
"schema"和"encType"用于 URI 查询字符串（但不是 URI 的其他部分）或请求主体，但没有办法同时使用它们，这对于 API 设计来说过于严格。
拆分 "schema"
与其让 "schema" 根据 "method" 执行两种不同的操作，我们将其拆分为两个关键字，每个关键字对应一个用途。这允许在需要时同时使用它们，这是 HTML 表单中没有的用例。
"hrefSchema" 替换了 "method": "get" 的用法，但它利用了 URI 模板变量，因此客户端数据驱动的动态 URI 不再局限于查询字符串。使用这种方法不再需要 "encType"。
"submissionSchema" 直接替换了 "method": "post" 的用法，其中 "submissionEncType" 替换了 "encType"。
删除 "method"
草案-05 试图恢复草案-03 中 "method" 的行为，但反馈告诉我们，用户发现这种改变非常令人困惑。在 "schema" 拆分之后，草案-05 中 "method" 的行为不再需要。
我们本可以切换到草案-04 中 "method" 的行为，但除了从反复更改中产生更多的困惑之外，草案-04 中对 "method" 的方法与 LDO 设计的其余部分也不一致。最显著的是，它造成了 "targetSchema" 用法的问题，如上所述。
问：那么我如何指示在链接上支持哪些 HTTP 方法？
答：理想情况下，这由您的链接关系类型隐式传达，这是跨机器面向超媒体的主要语义指示器。 RFC 5988 提供了有关创建自定义（又称“扩展”）链接关系的指导。
一些 URI 方案和命名空间，例如 urn: 方案中的 UUID 命名空间，或者 tag: 方案，特别适合创建唯一标识符。
当然，还有一些方法可以在运行时检测到这一点，例如 HTTP 的 "Allow" 响应标头，或者尝试一种方法并相应地处理 405 Method Not Allowed 错误。
问：不，真的。我如何 *明确* 指示链接上支持哪些 HTTP 方法？
答："targetHints" 提案 是草案-07 的一部分，因此将其用作草案-06 的扩展是可行的，但我们建议此时只使用草案-07。
问：如果 "targetSchema" 不是响应，我如何描述响应？
答：您应该为各种成功和错误响应创建超模式，但是将它们连接到链接更多的是一个文档问题，而不是一个使用问题：每个响应都会指示自己的模式，因此您不需要在运行时提前知道它。
超模式从未有过一个关键字来明确地将响应与操作（如 HTTP 方法）相关联。这种用例似乎是关于生成 API 文档，因此这很可能是 JSON Schema API 文档词汇表 的候选者。