JSON 超媒体模式草案-07 版本说明

JSON 超媒体模式 草案-07 完成了从草案-06 开始的超媒体模式重构工作。

超媒体模式现在只专注于为 JSON 文档添加超链接，因此用于其他目的的关键字（readOnly 和 media）已被 移动到验证规范。

新草案 已经过完全重写，以提高清晰度和可访问性，因此最好将其视为一项新的提案。我们希望将来添加教程材料，但这超出了版本说明的范围。

但是，如果你想从早期草案迁移，本页将作为关键更改的指南。新增内容远比更改多，应直接从新规范中学习，直到我们可以提供教程为止。

请注意，草案-handrews-json-schema-hyperschema-00 已被草案-handrews-json-schema-hyperschema-01 替换，以修复令人困惑的错误。更新的 -01 草案仍被视为草案-07。它现在使用正确的 URI 引用草案-07 元模式，以及其他排版修复。-00 和 -01 之间没有功能性更改。

• 从草案-06 迁移
• 从草案-05 迁移
• 从草案-04 迁移
  • GET
  • PUT
  • DELETE
  • POST
  • PATCH

从草案-06 迁移

没有更改草案-06 的功能，但为了清晰度和一致性，两个关键字被重命名了

• mediaType -> targetMediaType
• submissionEncType -> submissionMediaType

此外，hrefSchema 有点令人困惑，因此我们付出了更多努力来解释它的工作原理以及它如何在整个链接解析过程中发挥作用。

从草案-05 迁移

有关与草案-05 相关的的信息，请参阅 草案-06 版本说明。

从草案-04 迁移

在理想的草案-07 世界中，链接和 操作 不是同一个概念。借用 OpenAPI 的操作对象 中的术语，HTTP 方法是操作，每个链接（由单个 LDO 描述）都可以支持多个操作。

因此，与草案-04 不同，草案-07 超媒体模式 没有为每个操作提供单独的链接。这使得下面的迁移指南充其量只是近似值。

有关草案-04 的 method 和 targetSchema 通常如何用于创建单操作链接，以及这如何给迁移到多操作链接带来挑战，请参阅 草案-06 版本说明。这些版本说明还解释了草案-04 中定义的链接关系随后被删除的原因，以及实例基准 URI 确定方式的变化。

除了这些更改之外，最小的迁移将类似于以下行，尽管 有意缺乏明确的响应描述（除非响应恰好是目标资源的表示形式）意味着草案-04 的某些用例在草案-07 中没有直接的类似物。

下面列表中未提及的任何关键字对于该链接操作保持不变。

GET

• "method": "GET" -> "targetHints": {"allow": ["GET"]}
• mediaType -> targetMediaType
• schema -> hrefSchema，并将参数添加到 href 中
• encType -> 如果是 application/x-www-form-urlencoded，则删除；否则请联系邮件列表

PUT

如果您有一个 PUT 链接，其中 schema/encType 与 targetSchema/mediaType 不同，其中 targetSchema/mediaType 描述的是非表示响应，那么这些字段将没有直接的替换。

• "method": "PUT" -> "targetHints": {"allow": ["PUT"]}
• schema -> targetSchema
• encType -> targetMediaType

DELETE

DELETE 不接受请求有效负载，因此 schema 和 encType 应该被忽略。如果 targetSchema 和 mediaType 被用于除刚刚删除的资源的表示之外的响应，那么它们将没有直接的替换。

• "method": "DELETE" -> "targetHints": {"allow": ["DELETE"]}
• mediaType -> targetMediaType（如果描述的是表示）

POST

在大多数情况下，POST 的响应 不是目标资源的表示，而是 POST 尝试执行的操作的结果或状态。因此，targetSchema 和 mediaType 几乎肯定会删除。除此之外

• "method": "POST" -> "targetHints": {"allow": ["POST"]}
• schema -> submissionSchema
• encType -> submissionMediaType

PATCH

在 Hyper-Schema 中如何建模一个正确的 PATCH（使用补丁媒体类型而不是请求中的 application/json）一直不太清楚。一个选项是将其与 PUT 相同对待，只是在 encType 中使用补丁媒体类型。假设采用这种方法（以及与 PUT 相同的 taregetSchema/mediaType 注意事项）

• "method": "PATCH" -> "targetHints": {"allow": ["PATCH"]}
• schema -> targetSchema
• "encType": "..." -> "targetHints": {"accept-patch": "..."}