互联网工程任务组 A. Wright,编辑
互联网草案
预期状态:信息性 H. Andrews,编辑
过期时间:2020 年 3 月 20 日
B. Hutton,编辑
Wellcome Sanger 研究所
2019 年 9 月 17 日

JSON Schema 验证:JSON 结构验证的词汇表
draft-handrews-json-schema-validation-02

摘要

JSON Schema(application/schema+json)有几个用途,其中之一是 JSON 实例验证。本文档指定了 JSON Schema 的词汇表,用于描述 JSON 文档的含义,为使用 JSON 数据的用户界面提供提示,并对有效文档的外观做出断言。

读者须知

此草案的问题列表可以在以下位置找到:<https://github.com/json-schema-org/json-schema-spec/issues>.

有关更多信息,请参阅 <https://json-schema.fullstack.org.cn/>.

要提供反馈,请使用此问题跟踪器、主页上列出的通信方式或电子邮件联系文档编辑。

本文档状态

此互联网草案完全符合 BCP 78 和 BCP 79 的规定提交。

互联网草案是互联网工程任务组 (IETF) 的工作文档。请注意,其他团体也可能将工作文档作为互联网草案发布。当前互联网草案的列表在 https://datatracker.ietf.org/drafts/current/ 上。

互联网草案是有效期最长为六个月的草案文档,可能随时更新、替换或被其他文档废弃。互联网草案不适合用作参考材料,也不得引用它们,除非是“正在进行的工作”。

此互联网草案将于 2020 年 3 月 20 日过期。

版权声明

版权所有 (c) 2019 IETF 信托和被认定为文档作者的人员。保留所有权利。

本文档受 BCP 78 和 IETF 信托的《与 IETF 文档相关的法律条款》(https://trustee.ietf.org/license-info)的约束,该条款在本文档发布之日生效。请仔细阅读这些文档,因为它们描述了您对本文档的权利和限制。从本文档中提取的代码组件必须包含简化 BSD 许可证文本,如信托法律条款第 4.e 节所述,并且按简化 BSD 许可证中所述提供,不提供任何担保。


目录

1. 引言

JSON Schema 可用于要求给定的 JSON 文档(实例)满足一定数量的标准。这些标准是通过使用本规范中描述的关键字来断言的。此外,还定义了一组关键字来帮助交互式用户界面实例生成。

本规范将使用由 JSON Schema 核心 规范定义的概念、语法和术语。

2. 约定和术语

本文档中的关键词“必须”、“禁止”、“必需”、“应”、“不应”、“建议”、“不建议”、“推荐”、“可以”和“可选”应按 RFC 2119 中所述进行解释。

本规范使用术语“容器实例”来指代数组和对象实例。它使用术语“子实例”来指代数组元素或对象成员值。

如果数组值的任何两个元素都不相等,则称数组值中的元素是唯一的。

3. 概述

JSON Schema 验证对实例数据的结构做出约束。然后,满足所有断言约束的实例位置会使用包含非断言信息的任何关键字进行注释,例如描述性元数据和使用提示。如果实例中的所有位置都满足所有断言约束,则称该实例对模式有效。

每个模式对象都会独立地针对其适用的每个实例位置进行评估。这极大地简化了验证器的实现要求,因为它们不需要在文档范围的验证过程中维护状态。

本规范定义了一组断言关键字,以及少量元数据关键字的词汇表,这些关键字可用于用有用信息注释 JSON 实例。 第 7 节 关键字主要用作注释,但也可以选择用作断言。 第 8 节 关键字是用于处理作为 JSON 字符串嵌入的文档的注释。

4. 互操作性注意事项

4.1. 字符串实例的验证

需要注意的是,空字符 (\u0000) 在 JSON 字符串中是有效的。无论底层编程语言是否能够处理此类数据,要验证的实例都可能包含带有此字符的字符串值。

4.2. 数值实例的验证

JSON 规范允许数字具有任意精度,JSON Schema 不会添加任何此类边界。这意味着 JSON Schema 处理的数值实例可以任意大,或者具有任意长的十进制部分,无论底层编程语言是否能够处理此类数据。

4.3. 正则表达式

使用正则表达式或将实例值限制为正则表达式的关键字受 JSON Schema 核心 规范中正则表达式的互操作性注意事项的约束。

5. 元模式

默认 JSON Schema 元模式的当前 URI 是 <https://json-schema.fullstack.org.cn/draft/2019-09/schema>。为了方便模式作者,此元模式描述了本规范和 JSON Schema 核心规范中定义的所有词汇表,以及两个保留用于过渡期的旧关键字。每个部分下面都给出了各个词汇表和词汇表元模式 URI。某些词汇表是可选支持的,这将在相关部分详细说明。

为了更正错误,可以在规范草案之间发布更新的词汇表和元模式 URI。实现应考虑在此规范草案之后和下一个草案之前发布的日期,以表示与此处列出的相同语法和语义。

6. 结构验证的词汇表

模式中的验证关键字对实例的成功验证施加要求。这些关键字都是断言,没有任何注释行为。

不使用“$vocabulary”的元模式应被视为需要此词汇表,就好像其 URI 存在且值为 true 一样。

此词汇表的当前 URI(称为验证词汇表)是: <https://json-schema.fullstack.org.cn/draft/2019-09/vocab/validation>.

相应元模式的当前 URI 是: <https://json-schema.fullstack.org.cn/draft/2019-09/meta/validation>.

6.1. 任何实例类型的验证关键字

6.1.1. type

此关键字的值必须是字符串或数组。如果它是数组,则数组的元素必须是字符串,并且必须是唯一的。

字符串值必须是六种基本类型之一(“null”、“boolean”、“object”、“array”、“number”或“string”),或“integer”,它与任何具有零小数部分的数字匹配。

如果且仅当实例位于此关键字列出的任何集合中时,实例才有效。

6.1.2. enum

此关键字的值必须是数组。此数组应至少包含一个元素。数组中的元素应是唯一的。

如果实例的值等于此关键字的数组值中的一个元素,则实例会成功针对此关键字进行验证。

数组中的元素可能属于任何类型,包括 null。

6.1.3. const

此关键字的值可以是任何类型,包括 null。

使用此关键字在功能上等效于具有单个值的 "enum"

如果实例的值等于关键字的值,则实例将成功验证此关键字。

6.2. 数值实例的验证关键字(number 和 integer)

6.2.1. multipleOf

"multipleOf" 的值必须是数字,严格大于 0。

只有当数值实例除以此关键字的值的结果为整数时,该实例才有效。

6.2.2. maximum

"maximum" 的值必须是数字,代表数值实例的包含上限。

如果实例是数字,则只有当实例小于或等于 "maximum" 时,此关键字才有效。

6.2.3. exclusiveMaximum

"exclusiveMaximum" 的值必须是数字,代表数值实例的独占上限。

如果实例是数字,则只有当实例的值严格小于(不等于)"exclusiveMaximum" 时,该实例才有效。

6.2.4. minimum

"minimum" 的值必须是数字,代表数值实例的包含下限。

如果实例是数字,则只有当实例大于或等于 "minimum" 时,此关键字才有效。

6.2.5. exclusiveMinimum

"exclusiveMinimum" 的值必须是数字,代表数值实例的独占下限。

如果实例是数字,则只有当实例的值严格大于(不等于)"exclusiveMinimum" 时,该实例才有效。

6.3. 字符串的验证关键字

6.3.1. maxLength

此关键字的值必须是非负整数。

如果字符串实例的长度小于或等于此关键字的值,则该实例对该关键字有效。

字符串实例的长度定义为其字符数量,如 RFC 8259 中所定义。

6.3.2. minLength

此关键字的值必须是非负整数。

如果字符串实例的长度大于或等于此关键字的值,则该实例对该关键字有效。

字符串实例的长度定义为其字符数量,如 RFC 8259 中所定义。

省略此关键字与值为 0 的行为相同。

6.3.3. pattern

此关键字的值必须是字符串。此字符串应根据 ECMA 262 正则表达式方言,是一个有效的正则表达式。

如果正则表达式成功匹配实例,则字符串实例被视为有效。提醒:正则表达式不会被隐式锚定。

6.4. 数组的验证关键字

6.4.1. maxItems

此关键字的值必须是非负整数。

如果数组实例的大小小于或等于此关键字的值,则该实例对 "maxItems" 有效。

6.4.2. minItems

此关键字的值必须是非负整数。

如果数组实例的大小大于或等于此关键字的值,则该实例对 "minItems" 有效。

省略此关键字与值为 0 的行为相同。

6.4.3. uniqueItems

此关键字的值必须是布尔值。

如果此关键字的布尔值为 false,则实例将成功验证。如果此关键字的布尔值为 true,则只有当实例的所有元素都是唯一的时,该实例才会成功验证。

省略此关键字与值为 false 的行为相同。

6.4.4. maxContains

此关键字的值必须是非负整数。

如果对 "contains" 的模式有效的元素数量小于或等于此关键字的值,则数组实例对 "maxContains" 有效。

如果在同一个模式对象中不存在 "contains",则此关键字不会产生任何影响。

6.4.5. minContains

此关键字的值必须是非负整数。

如果对 "contains" 的模式有效的元素数量大于或等于此关键字的值,则数组实例对 "minContains" 有效。

允许值为 0,但这仅用于设置从 0 到 "maxContains" 值的出现次数范围。值为 0 且没有 "maxContains" 会导致 "contains" 始终通过验证。

如果在同一个模式对象中不存在 "contains",则此关键字不会产生任何影响。

省略此关键字与值为 1 的行为相同。

6.5. 对象的验证关键字

6.5.1. maxProperties

此关键字的值必须是非负整数。

如果对象实例的属性数量小于或等于此关键字的值,则该实例对 "maxProperties" 有效。

6.5.2. minProperties

此关键字的值必须是非负整数。

如果对象实例的属性数量大于或等于此关键字的值,则该实例对 "minProperties" 有效。

省略此关键字与值为 0 的行为相同。

6.5.3. required

此关键字的值必须是数组。此数组的元素(如果有)必须是字符串,并且必须是唯一的。

如果数组中的每个项目都是实例中属性的名称,则对象实例对该关键字有效。

省略此关键字与空数组的行为相同。

6.5.4. dependentRequired

此关键字的值必须是对象。此对象中的属性(如果有)必须是数组。每个数组中的元素(如果有)必须是字符串,并且必须是唯一的。

此关键字指定在存在特定其他属性时必需的属性。它们的要求取决于其他属性的存在。

如果对于出现在实例中以及作为此关键字的值内的名称,相应数组中的每个项目也是实例中属性的名称,则验证成功。

省略此关键字与空对象的行為相同。

7. 使用 "format" 的语义内容词汇表

7.1. 前言

仅结构验证可能不足以允许应用程序正确使用某些值。定义了 "format" 注释关键字,以允许模式作者为由权威资源(无论是 RFC 还是其他外部规范)准确描述的值的固定子集传达语义信息。

实现 MAY 将 "format" 视为断言,而不是注释,并尝试验证值是否符合指定的语义。有关详细信息,请参阅下面的实现要求。

此关键字的值称为格式属性。它必须是字符串。格式属性通常只能验证给定的一组实例类型。如果要验证的实例的类型不在此集合中,则此格式属性和实例的验证应成功。本节中定义的所有格式属性都适用于字符串,但可以指定格式属性以适用于 核心 JSON 模式 中定义的数据模型中定义的任何实例类型。 [CREF1]请注意,此规范中的 "type" 关键字定义了一个 "integer" 类型,它不是数据模型的一部分。因此,格式属性可以限制为数字,但不能专门限制为整数。但是,可以将数值格式与值为 "integer" 的 "type" 关键字一起使用,也可以明确定义为如果数字不是整数则始终通过,这与仅应用于整数本质上产生相同的效果。

不使用 "$vocabulary" 的元模式应被视为利用此词汇表,就好像其 URI 存在且值为 false 一样。有关详细信息,请参阅下面的实现要求。

此词汇表的当前 URI(称为格式词汇表)是:<https://json-schema.fullstack.org.cn/draft/2019-09/vocab/format>

相应元模式的当前 URI 是:<https://json-schema.fullstack.org.cn/draft/2019-09/meta/format>

7.2. 实现要求

"format" 关键字充当注释,以及可选的断言。 [CREF2]这是由于关键字的历史,并且与当前的关键字设计原则不一致。为了管理这种歧义,"format" 关键字在其自己的独立词汇表中定义,如上所述。词汇表声明的真值或假值控制处理使用 "format" 的模式所需的实现要求,以及模式作者可以依赖的行为。

7.2.1. 作为注释

如果实现支持注释收集,则必须收集格式的值作为注释。这在模式验证不可用或不足时启用应用程序级验证。

此要求不受词汇表声明的布尔值的影响,也不受下一节中描述的 "format" 断言行为配置的影响。 [CREF3]即使词汇表声明的值为 false,也要求注释收集是典型的,但对于确保即使在未实现断言评估的情况下,执行应用程序级验证的最佳实践也是可能的,这一点是必要的。由于 "format" 一直是此规范的一部分,因此即使在词汇表声明为 false 的情况下,也要求实现了解它,这被认为不是负担。

7.2.2. 作为断言

无论词汇表声明的布尔值为多少,能够将 "format" 评估为断言的实现都必须提供启用和禁用此类评估的选项。当选项未明确指定时,断言评估行为取决于词汇表声明的布尔值。

在实现整个规范时,此词汇表必须使用值为 false 支持(但请参见下面的详细信息),并且可以使用值为 true 支持。

当词汇表声明的值为 false 时,实现: [CREF4]这与实现的现状相匹配,实现提供了各种验证级别,包括对某些或所有格式属性根本不进行验证。它还旨在鼓励仅依赖注释行为并在应用程序中执行语义验证,这是推荐的最佳实践。

当词汇表声明的值为 true 时,支持此形式的词汇表的实现: [CREF5]预期对于诸如日期时间之类的简单格式,语法验证将是彻底的。对于诸如电子邮件地址之类的复杂格式,它们是各种标准和随着时间的推移而进行的大量调整的集合,具有模糊和/或过时的规则,这些规则可能或可能不会受到使用该值的应用程序的限制,因此最小的验证就足够了。例如,不包含 "@" 的实例字符串显然不是有效的电子邮件地址,并且包含 7 位 ASCII 以外的字符的 "email" 或 "hostname" 同样显然无效。

对格式属性进行最小验证的要求故意含糊不清且具有包容性,这是由于许多属性的复杂性。特别要注意,此要求仅限于语法检查;不能期望实现发送电子邮件、尝试连接到 URL 或以其他方式检查格式实例标识的实体是否存在。

建议实现为每种格式使用一个通用的解析库或一个众所周知的正则表达式。实现应该清楚地记录如何以及在何种程度上验证每个格式属性。

标准核心和验证元模式在其 "$vocabulary" 关键字中包含此词汇表,值为 false,因为默认情况下,实现不需要支持此关键字作为断言。使用值为 true 支持格式词汇表被理解为会大大增加代码大小,并在某些情况下会增加执行时间,并且不适合所有实现。

7.2.3. 自定义格式属性

实现可以支持自定义格式属性。除了双方之间的协议外,模式作者不应期望对等实现支持此类自定义格式属性。实现决不能因为未知格式属性而导致验证失败或停止处理。当将“format”视为注释时,实现应该收集已知和未知格式属性值。

词汇表不支持专门声明关键字的不同值集。由于此限制以及此关键字在历史上不一致的实现,如果需要互操作性,建议在自定义词汇表中定义其他关键字,而不是其他格式属性。

7.3. 定义的格式

7.3.1. 日期、时间和持续时间

这些属性适用于字符串实例。

日期和时间格式名称源自 RFC 3339,第 5.6 节。持续时间格式来自 ISO 8601 ABNF,如 RFC 3339 附录 A 所示。

支持格式的实现应该实现对以下属性的支持

date-time
如果字符串实例根据“date-time”产生式是有效的表示,则它对于此属性有效。
date
如果字符串实例根据“full-date”产生式是有效的表示,则它对于此属性有效。
time
如果字符串实例根据“full-time”产生式是有效的表示,则它对于此属性有效。
duration
如果字符串实例根据“duration”产生式是有效的表示,则它对于此属性有效。

实现可以使用该部分中定义的其他产生式名称支持其他属性。如果实现了“full-date”或“full-time”,则必须实现相应的短格式(分别为“date”或“time”),并且必须表现相同。实现不应定义名称与 RFC 3339 产生式匹配的扩展属性,除非它根据该产生式的规则进行验证。 [CREF6]目前尚无关于是否需要支持所有 RFC 3339 格式的共识,因此这种保留命名空间的方法将鼓励实验,而不必承诺使用整个集合。格式实现要求要么变得更加灵活,要么这些要求可能被提升为完全指定的属性或被删除。

7.3.2. 电子邮件地址

这些属性适用于字符串实例。

如果字符串实例是有效的 Internet 电子邮件地址,如下所示,则它对于这些属性有效

email
RFC 5322,第 3.4.1 节 所定义。
idn-email
RFC 6531 所定义

请注意,所有针对“email”属性有效的字符串也针对“idn-email”属性有效。

7.3.3. 主机名

这些属性适用于字符串实例。

如果字符串实例是 Internet 主机名的有效表示,如下所示,则它对于这些属性有效

hostname
RFC 1123,第 2.1 节 所定义,包括使用 RFC 5891,第 4.4 节 中指定的 Punycode 算法生成的主机名。
idn-hostname
如 RFC 1123 对主机名所定义,或如 RFC 5890,第 2.3.2.3 节 所定义的国际化主机名。

请注意,所有针对“hostname”属性有效的字符串也针对“idn-hostname”属性有效。

7.3.4. IP 地址

这些属性适用于字符串实例。

如果字符串实例是 IP 地址的有效表示,如下所示,则它对于这些属性有效

ipv4
根据 RFC 2673,第 3.2 节 中定义的“dotted-quad”ABNF 语法定义的 IPv4 地址。
ipv6
RFC 4291,第 2.2 节 所定义的 IPv6 地址。

7.3.5. 资源标识符

这些属性适用于字符串实例。

uri
如果字符串实例是有效的 URI,根据 [RFC3986],则它对于此属性有效。
uri-reference
如果字符串实例是有效的 URI 引用(URI 或相对引用),根据 [RFC3986],则它对于此属性有效。
iri
如果字符串实例是有效的 IRI,根据 [RFC3987],则它对于此属性有效。
iri-reference
如果字符串实例是有效的 IRI 引用(IRI 或相对引用),根据 [RFC3987],则它对于此属性有效。
uuid
如果字符串实例是 UUID 的有效字符串表示,根据 [RFC4122],则它对于此属性有效。

请注意,所有有效的 URI 都是有效的 IRI,所有有效的 URI 引用也是有效的 IRI 引用。

还要注意,“uuid”格式用于普通 UUID,而不是 URN 中的 UUID。例如“f81d4fae-7dec-11d0-a765-00a0c91e6bf6”。对于作为 URN 的 UUID,请使用“uri”格式,使用“pattern”正则表达式“^urn:uuid:”来指示 URI 方案和 URN 命名空间。

7.3.6. uri-template

此属性适用于字符串实例。

如果字符串实例是有效的 URI 模板(任何级别),根据 [RFC6570],则它对于此属性有效。

请注意,URI 模板可用于 IRI;没有单独的 IRI 模板规范。

7.3.7. JSON 指针

这些属性适用于字符串实例。

json-pointer
如果字符串实例是 JSON 指针的有效 JSON 字符串表示,根据 RFC 6901,第 5 节,则它对于此属性有效。
relative-json-pointer
如果字符串实例是有效的 相对 JSON 指针,则它对于此属性有效。

为了允许使用绝对和相对 JSON 指针,请使用“anyOf”或“oneOf”来指示对任一格式的支持。

7.3.8. regex

此属性适用于字符串实例。

正则表达式,应该根据 ECMA 262 正则表达式方言有效。

验证格式的实现必须至少接受本规范“正则表达式”部分中定义的 ECMA 262 的子集,并且应该接受所有有效的 ECMA 262 表达式。

8. 用于字符串编码数据内容的词汇表

8.1. 前言

本节中定义的注释表示实例包含以 JSON 字符串编码的非 JSON 数据。

这些属性提供了解释 JSON 数据为丰富多媒体文档所需的额外信息。它们描述了内容类型、编码方式和/或验证方式。它们不充当验证断言;格式错误的字符串编码文档决不能导致包含的实例被视为无效。

不使用“$vocabulary”的元模式应被视为需要此词汇表,就好像其 URI 存在且值为 true 一样。

此词汇表(称为内容词汇表)的当前 URI 为:<https://json-schema.fullstack.org.cn/draft/2019-09/vocab/content>.

相应元模式的当前 URI 为:<https://json-schema.fullstack.org.cn/draft/2019-09/meta/content>.

8.2. 实现要求

由于安全和性能问题,以及可能的 content type 的开放性,实现决不应默认自动解码、解析和/或验证字符串内容。这还支持将嵌入文档用于不同于处理包含文档的处理者的处理。

本节中的所有关键字仅适用于字符串,对其他数据类型没有影响。

实现可以提供自动解码、解析和/或验证字符串内容的功能。但是,它决不应默认执行这些操作,并且必须分别提供每个字符串编码文档的验证结果,而与封闭文档分开。此过程应该等同于根据原始模式完全评估实例,然后使用注释对每个字符串编码文档进行解码、解析和/或验证。 [CREF7]目前,此类自动解码、解析和验证功能的执行和返回解析数据和/或验证结果的确切机制尚未指定。如果此类功能证明很受欢迎,它可能会在未来的草案中得到更详细的规范。

另请参阅 安全注意事项 部分,了解根据这些关键字自动处理实例字符串可能带来的漏洞。

8.3. contentEncoding

如果实例值为字符串,则此属性定义该字符串应被解释为二进制数据,并使用此属性命名的编码进行解码。

此属性的可能值列在 RFC 2045,第 6.1 节RFC 4648 中。对于在两个 RFC 中都定义的“base64”,应该使用 RFC 4648 中的定义(它删除了行长度限制),因为各种其他规范已强制执行不同的长度。请注意,可以使用 "pattern" 关键字来限制字符串中的行长度。

如果此关键字不存在,但“contentMediaType”存在,则表示该媒体类型可以像任何其他 JSON 字符串值一样编码为 UTF-8,并且不需要额外的解码。

此属性的值必须是字符串。

8.4. contentMediaType

如果实例是字符串,则此属性表示字符串内容的媒体类型。如果“contentEncoding”存在,则此属性描述解码后的字符串。

此属性的值必须是字符串,它必须是媒体类型,如 RFC 2046 所定义。

8.5. contentSchema

如果实例是字符串,并且如果“contentMediaType”存在,则此属性包含一个模式,该模式描述字符串的结构。

此关键字可以与可以映射到 JSON Schema 数据模型的任何媒体类型一起使用。

如果“contentMediaType”不存在,则应忽略此属性的值。

8.6. 示例

以下是一个模式示例,说明了“contentEncoding”和“contentMediaType”的使用

{
    "type": "string",
    "contentEncoding": "base64",
    "contentMediaType": "image/png"
}

                    

此模式描述的实例预计为字符串,其值应可解释为 base64 编码的 PNG 图像。

另一个示例

{
    "type": "string",
    "contentMediaType": "text/html"
}

                    

此模式描述的实例预计为包含 HTML 的字符串,使用 JSON 字符串解码到的任何字符集。根据 RFC 8259 的第 8.1 节,在完全封闭的系统之外,这必须是 UTF-8。

此示例描述了一个使用 HMAC SHA-256 算法进行 MAC 的 JWT,并且在其声明集中需要“iss”和“exp”字段。

{
    "type": "string",
    "contentMediaType": "application/jwt",
    "contentSchema": {
        "type": "array",
        "minItems": 2,
        "items": [
            {
                "const": {
                    "typ": "JWT",
                    "alg": "HS256"
                }
            },
            {
                "type": "object",
                "required": ["iss", "exp"],
                "properties": {
                    "iss": {"type": "string"},
                    "exp": {"type": "integer"}
                }
            }
        ]
    }
}
                    

请注意,"contentEncoding" 不存在。虽然 "application/jwt" 媒体类型使用 base64url 编码,但该编码由媒体类型定义,它确定 JWT 字符串如何被解码成两个 JSON 数据结构列表:第一个是头部,第二个是负载。由于 JWT 媒体类型确保 JWT 可以用 JSON 字符串表示,因此无需进一步编码或解码。

9. 基本元数据注释词汇表

这些通用注释关键字提供了用于文档和用户界面显示目的的常用信息。它们不打算形成一套全面的功能。相反,可以为更复杂的基于注释的应用程序定义其他词汇表。

不使用“$vocabulary”的元模式应被视为需要此词汇表,就好像其 URI 存在且值为 true 一样。

此词汇表的当前 URI(称为元数据词汇表)是:<https://json-schema.fullstack.org.cn/draft/2019-09/vocab/meta-data>

相应元模式的当前 URI 是:<https://json-schema.fullstack.org.cn/draft/2019-09/meta/meta-data>

9.1. "title" 和 "description"

这两个关键字的值都必须是字符串。

这两个关键字都可以用于用有关此用户界面生成的数据的信息来装饰用户界面。标题最好简短,而描述将提供有关此模式描述的实例目的的解释。

9.2. "default"

此关键字的值不受限制。当此关键字的多个出现适用于单个子实例时,实现应该删除重复项。

此关键字可用于提供与特定模式关联的默认 JSON 值。建议默认值对关联模式有效。

9.3. "deprecated"

此关键字的值必须是布尔值。当此关键字的多个出现适用于单个子实例时,应用程序应该考虑实例位置已弃用,如果任何出现指定了 true 值。

如果 "deprecated" 的值为布尔值 true,则表明应用程序应该避免使用声明的属性。它可能意味着该属性将在将来被删除。

包含 "deprecated" 且值为 true 的根模式表明,正在描述的整个资源可能在将来被删除。

当 "deprecated" 关键字通过 "items" 应用于数组中的项目时,如果 "items" 是单个模式,则弃用与整个数组相关,而如果 "items" 是模式数组,则弃用与子模式位置相对应的项目相关。

省略此关键字与值为 false 的行为相同。

9.4. "readOnly" 和 "writeOnly"

这些关键字的值必须是布尔值。当这些关键字的多个出现适用于单个子实例时,如果任何出现指定了 true 值,则结果行为应与 true 值相同,否则应与 false 值相同。

如果 "readOnly" 的值为布尔值 true,则表明实例的值完全由拥有权限管理,应用程序尝试修改此属性的值预计将被该拥有权限忽略或拒绝。

标记为 "readOnly" 的整个文档的实例文档可能在发送到拥有权限时被忽略,或者可能导致错误,具体取决于权限的决定。

如果 "writeOnly" 的值为布尔值 true,则表明在从拥有权限检索实例时,该值永远不会出现。它可以在发送到拥有权限以更新或创建文档(或它所代表的资源)时出现,但不会包含在任何更新的或新创建的实例版本中。

标记为 "writeOnly" 的整个文档的实例文档可能会作为某种空白文档返回,或者在检索时可能会产生错误,或者检索请求可能会被忽略,具体取决于权限的决定。

例如,"readOnly" 用于将数据库生成的序列号标记为只读,而 "writeOnly" 用于将密码输入字段标记为只读。

这些关键字可用于协助用户界面实例生成。特别是,应用程序可以选择使用一个小部件,该小部件隐藏输入值,因为它们是在只写字段中键入的。

省略这些关键字与 false 值具有相同行为。

9.5. "examples"

此关键字的值必须是数组。数组中的值不受限制。当此关键字的多个出现适用于单个子实例时,实现必须提供所有值的扁平数组,而不是数组数组。

此关键字可用于提供与特定模式关联的示例 JSON 值,以说明用法。建议这些值对关联模式有效。

实现可以使用 "default" 的值(如果存在)作为附加示例。如果 "examples" 缺失,"default" 仍然可以以这种方式使用。

10. 安全注意事项

JSON 模式验证定义了 JSON 模式核心词汇表,并关注其中列出的所有安全注意事项。

JSON 模式验证允许使用正则表达式,正则表达式具有许多不同的(通常不兼容的)实现。一些实现允许嵌入任意代码,这超出了 JSON 模式的范围,必须禁止。正则表达式通常也可以被设计为计算起来非常昂贵(使用所谓的“灾难性回溯”),从而导致拒绝服务攻击。

支持根据 "contentEncoding" 和/或 "contentMediaType" 验证或以其他方式评估实例字符串数据的实现,存在以不安全的方式根据误导性信息评估数据的风险。应用程序可以通过仅在建立模式和实例之间的关系时(例如,它们共享相同的权限)执行此类处理来缓解此风险。

处理媒体类型或编码受该媒体类型或编码的安全注意事项的影响。例如,RFC 4329 脚本媒体类型 的安全注意事项适用于处理 JSON 字符串中编码的 JavaScript 或 ECMAScript。

11. 参考文献

11.1. 规范性引用

[ecma262] "ECMA 262 规范"
[json-schema] Wright, A.H. Andrews,"JSON 模式:描述 JSON 文档的媒体类型",互联网草案 draft-handrews-json-schema-02,2017 年 11 月。
[relative-json-pointer] Luff, G.H. Andrews,"相对 JSON 指针",互联网草案 draft-handrews-relative-json-pointer-01,2017 年 11 月。
[RFC1123] Braden, R.,"互联网主机要求 - 应用程序和支持",STD 3,RFC 1123,DOI 10.17487/RFC1123,1989 年 10 月。
[RFC2045] Freed, N.N. Borenstein,"多用途互联网邮件扩展 (MIME) 第一部分:互联网消息正文格式",RFC 2045,DOI 10.17487/RFC2045,1996 年 11 月。
[RFC2046] Freed, N.N. Borenstein,"多用途互联网邮件扩展 (MIME) 第二部分:媒体类型",RFC 2046,DOI 10.17487/RFC2046,1996 年 11 月。
[RFC2119] Bradner, S.,"RFC 中使用的指示需求级别的关键词",BCP 14,RFC 2119,DOI 10.17487/RFC2119,1997 年 3 月。
[RFC2673] Crawford, M.,"域名系统中的二进制标签",RFC 2673,DOI 10.17487/RFC2673,1999 年 8 月。
[RFC3339] Klyne, G.C. Newman,"互联网上的日期和时间:时间戳",RFC 3339,DOI 10.17487/RFC3339,2002 年 7 月。
[RFC3986] Berners-Lee, T.Fielding, R.L. Masinter,"统一资源标识符 (URI):通用语法",STD 66,RFC 3986,DOI 10.17487/RFC3986,2005 年 1 月。
[RFC3987] Duerst, M.M. Suignard,"国际化资源标识符 (IRI)",RFC 3987,DOI 10.17487/RFC3987,2005 年 1 月。
[RFC4122] Leach, P.Mealling, M.R. Salz,"通用唯一标识符 (UUID) URN 命名空间",RFC 4122,DOI 10.17487/RFC4122,2005 年 7 月。
[RFC4291] Hinden, R.S. Deering,"IP 版本 6 地址架构",RFC 4291,DOI 10.17487/RFC4291,2006 年 2 月。
[RFC4648] Josefsson, S.,"Base16、Base32 和 Base64 数据编码",RFC 4648,DOI 10.17487/RFC4648,2006 年 10 月。
[RFC5322] Resnick, P.,"互联网消息格式",RFC 5322,DOI 10.17487/RFC5322,2008 年 10 月。
[RFC5890] Klensin, J.,"应用程序的国际化域名 (IDNA):定义和文档框架",RFC 5890,DOI 10.17487/RFC5890,2010 年 8 月。
[RFC5891] Klensin, J.,"应用程序中的国际化域名 (IDNA):协议",RFC 5891,DOI 10.17487/RFC5891,2010 年 8 月。
[RFC6531] Yao, J.W. Mao,"SMTP 扩展用于国际化电子邮件",RFC 6531,DOI 10.17487/RFC6531,2012 年 2 月。
[RFC6570] Gregorio, J.Fielding, R.Hadley, M.Nottingham, M.D. Orchard,"URI 模板",RFC 6570,DOI 10.17487/RFC6570,2012 年 3 月。
[RFC6901] Bryan, P.Zyp, K.M. Nottingham,"JavaScript 对象表示法 (JSON) 指针",RFC 6901,DOI 10.17487/RFC6901,2013 年 4 月。
[RFC8259] Bray, T.,"JavaScript 对象表示法 (JSON) 数据交换格式",STD 90,RFC 8259,DOI 10.17487/RFC8259,2017 年 12 月。

11.2. 信息性引用

[RFC4329] Hoehrmann, B.,"脚本媒体类型",RFC 4329,DOI 10.17487/RFC4329,2006 年 4 月。

附录 A. 从验证移动到核心的关键字

从本草案开始,几个关键字已从本文档移动到 核心规范,在某些情况下进行了重命名或其他更改。这影响了以下以前的验证关键字

"definitions"
重命名为 "$defs" 以匹配 "$ref" 并缩短输入类型。模式词汇表作者不应定义具有不同行为的 "definitions" 关键字,以避免使仍使用旧名称的模式失效。虽然 "definitions" 不存在于本文档引用的单一词汇表元模式中,但它仍然存在于默认元模式中,实现应该假设 "$defs" 和 "definitions" 在使用该元模式时具有相同行为。
"allOf", "anyOf", "oneOf", "not", "if", "then", "else", "items", "additionalItems", "contains", "propertyNames", "properties", "patternProperties", "additionalProperties"
所有这些关键字都将子模式应用于实例并合并其结果,而不断言任何自身条件。没有断言关键字,这些应用器只能通过使用 false 布尔模式或通过反转 true 布尔模式的结果(或等效模式对象)来导致断言失败。出于这个原因,它们最好定义为一种通用机制,验证、超模式和扩展词汇表都可以基于它。
"依赖项"
此关键字有两种不同的行为模式,这使得它的实现和推理变得比较困难。模式形式已移至核心并重命名为“dependentSchemas”,作为应用器词汇的一部分。它类似于“properties”,不同之处在于它不将子模式应用于属性值,而是将其应用于包含该属性的对象。属性名数组形式保留在这里并重命名为“dependentRequired”,因为它是一种断言,是条件使用“required”断言关键字的快捷方式。

附录 B. 致谢

感谢 Gary Court、Francis Galiegue、Kris Zyp 和 Geraint Luff 对 JSON Schema 初稿的贡献。

感谢 Jason Desrosiers、Daniel Perrett、Erik Wilde、Ben Hutton、Evgeny Poberezkin、Brad Bowman、Gowry Sankar、Donald Pipowitch、Dave Finlay 和 Denis Laxalde 对文档的提交和补丁。

附录 C. 变更日志

[CREF8]本节在离开 Internet-Draft 状态之前将被删除。

draft-handrews-json-schema-validation-02

draft-handrews-json-schema-validation-01

draft-handrews-json-schema-validation-00

draft-wright-json-schema-validation-01

draft-wright-json-schema-validation-00

draft-fge-json-schema-validation-00

作者地址

奥斯汀·赖特 (编辑) 电子邮件: [email protected]
亨利·安德鲁斯 (编辑) 电子邮件: [email protected]
本·哈顿 (编辑) Wellcome Sanger Institute 电子邮件: [email protected] URI: https://jsonschema.dev