草案-06 版本说明

从 zyp-04 和 fge-00 (草案-04) 迁移到 wright-01 (草案-06) 的版本说明。

注意：草案-07 已发布

请注意，草案-07 的核心和验证与草案-06 向后兼容。有关更多信息，请参阅该草案的迁移说明。

问：草案-04 和草案-06 之间有什么变化？
问：草案-05 发生了什么？
问：围绕着使用 “additionalProperties” 重用模式的所有讨论结果如何？

问：草案-04 和草案-06 之间有什么变化？

向后不兼容的变化

关键字	变化	后果
`"id"`	被 `"$id"` 替换	不再容易与名为 `"id"` 的实例属性混淆
`"$id"`	替换 `"id"`	行为相同，`$` 前缀与另外两个核心关键字匹配
`"$ref"`	仅在预期模式的位置允许	现在可以描述名为 `"$ref"` 的实例属性
`"exclusiveMinimum"` 和 `"exclusiveMaximum"`	从布尔值更改为数字，以与关键字独立性原则保持一致	在以前会使其中一个为真的地方，将值更改为相应的 `"minimum"` 或 `"maximum"` 值，并删除 `"minimum"`/`"maximum"` 关键字
`"type"`	`"integer"` 的定义	在草案-04 中，`"integer"` 被列为原始类型，并定义为 “没有小数部分或指数部分的 JSON 数字”；在草案-06 中，`"integer"` 不被认为是原始类型，并且仅在关键字 `"type"` 的部分中定义为 “任何具有零小数部分的数字”；因此，`1.0` 在草案-04 和更早版本中不是有效的 `"integer"` 类型，但在草案-06 和更高版本中是有效的 `"integer"` 类型；请注意，这两个草案都指出整数 SHOULD 在 JSON 中编码为没有小数部分

新增和向后兼容的变化

关键字	变化	后果
布尔值作为模式	在任何地方都允许，不仅仅是 `"additionalProperties"` 和 `"additionalItems"`	`true` 等价于 `{}`，`false` 等价于 `{"not": {}}`，但意图更清晰，并且实现可以更容易地优化这些情况
`"propertyNames"`	新增	采用验证所有属性的名称而不是其值的模式
`"contains"`	新增	如果其模式验证了至少一个数组项，则通过验证的数组关键字
`"const"`	新增	一个元素 `"enum"` 的更可读形式
`"required"`	允许空数组	空数组表示不需要任何属性
`"dependencies"`	允许对属性依赖项使用空数组	空数组表示给定属性没有依赖项
`"format": "uri-reference"`	新增	根据 RFC 3986 允许相对 URI 引用；请参阅下面有关 `"uri"` 作为格式的部分
`"format": "uri-template"`	新增	指示符合 RFC 6570 的 URI 模板值，如 JSON 超级模式在 `"href"` 中使用的那样
`"format": "json-pointer"`	新增	表示一个 JSON 指针值，例如 `/foo/bar`; 请勿将其用于 JSON 指针 URI 片段，例如 `#/foo/bar`：这些的正确格式是 `"uri-reference"`
`"示例"`	新增	没有验证效果的示例数组；`"default"` 的值可用作示例，无需在此关键字下重复

格式：`"uri"` 与 `"uri-reference"`

虽然并非技术上的更改，但 "uri" 格式的行为没有明确说明，并且经常被错误地实现和使用（包括在 draft-04 元模式中）。

"uri" 仅应在需要绝对 URI（以方案开头）时使用。

当允许使用相对路径、片段或任何其他样式的 URI 引用（根据 RFC 3986）时，请使用 "uri-reference"。

提供从 draft-04 到 draft-06 转换的实现可能希望提供一个选项来将 "uri" 格式转换为 "uri-reference"，尽管任何此类选项应默认情况下被禁用以实现严格的符合性。

问：草案-05 发生了什么？

draft-05 核心和验证规范旨在对 draft-04 进行更清晰和可读的重写，以使我们为 draft-06 更改奠定坚实的基础。实现者应该不实现或宣传对“draft-05”的支持。

通过实现 draft-04 发布后立即提出的建议来支持“draft-05”的实现应该删除该支持或为其命名不同的名称以避免混淆。

问：与 `"additionalProperties"` 相关的所有关于重新使用模式的讨论发生了什么？

关于将 "additionalProperties" 设置为除 true 之外的值的模式重新使用的提议有几种。大多数人特别关注它为 false 的情况，但相同的行为也发生在任何非 true 值上。

此领域的所有提议将成为 draft-08 的重点。虽然我们在 draft-07 期间在消除一些选项方面取得了进展，但剩下的分歧足够深，以至于需要将其作为草案的重点（draft-07 的主要重点是超模式）。

困难在于，如果你尝试这样做

数据

{ "type": "object", "allOf": [ { "$ref": "#/definitions/foo" }, { "$ref": "#/definitions/bar" } ], "definitions": { "foo": { "properties": { "foo": { "type": "string" } }, "additionalProperties": false }, "bar": { "properties": { "bar": { "type": "number" } }, "additionalProperties": false } }}

对任何非空对象实例的验证总是会失败。 "additionalProperties" 仅了解直接相邻的 "properties" 和 "patternProperties"，以确保每个子模式无论与其他子模式一起使用还是单独使用，都具有相同的含义。

因此，在此示例中，如果实例具有“bar”属性，它将因“bar”不为“foo”而失败第一个子模式。如果它具有“foo”属性，它将因“foo”不为“bar”而失败第二个子模式。任何其他属性都会导致两个模式都失败。

使用新的 "propertyNames" 关键字提供了一种解决方法

数据

{ "type": "object", "allOf": [ { "$ref": "#/definitions/foo" }, { "$ref": "#/definitions/bar" } ], "propertyNames": { "anyOf": [ { "$ref": "#/definitions/fooNames" }, { "$ref": "#/definitions/barNames" } ] }, "definitions": { "foo": { "properties": { "foo": { "type": "string" } } }, "fooNames": { "enum": ["foo"] }, "bar": { "properties": { "bar": { "type": "number" } } }, "barNames": { "enum": ["bar"] } }}