| 互联网工程任务组 | F. Galiegue，编 |
| 互联网草案 | |
| 预期状态：信息性 | K. Zyp，编 |
| 过期时间：2017 年 8 月 26 日 | SitePen（美国） |
| G. Court | |
| 2013 |
JSON 模式：核心定义和术语
draft-zyp-json-schema-04
JSON 模式定义了媒体类型“application/schema+json”，这是一种基于 JSON 的格式，用于定义 JSON 数据的结构。JSON 模式为给定应用程序所需的 JSON 数据及其交互方式提供了契约。JSON 模式的目的是定义 JSON 数据的验证、文档、超链接导航和交互控制。
本互联网草案完全符合 BCP 78 和 BCP 79 的规定提交。
互联网草案是互联网工程任务组 (IETF) 的工作文档。请注意，其他团体也可能将工作文档作为互联网草案分发。当前互联网草案的列表位于 http://datatracker.ietf.org/drafts/current/。
互联网草案是有效期最长为六个月的草案文档，可能会随时被其他文档更新、替换或废弃。将互联网草案用作参考材料或引用它们（除了“正在进行的工作”之外）是不合适的。
本互联网草案将于 2017 年 8 月 26 日过期。
版权所有 (c) 2013 IETF 信托和被标识为文档作者的人员。保留所有权利。
本文件受 BCP 78 和 IETF 信托的 IETF 文档相关法律条款 (http://trustee.ietf.org/license-info) 的约束，这些条款在本文件发布之日生效。请仔细阅读这些文档，因为它们描述了您对本文件的权利和限制。从本文件提取的代码组件必须包含简化的 BSD 许可证文本，如信托法律条款第 4.e 节所述，并且按简化的 BSD 许可证提供，不提供任何担保。
JSON 模式是一种用于定义 JSON 数据结构的 JSON 媒体类型。JSON 模式为给定应用程序所需的 JSON 数据及其交互方式提供了契约。JSON 模式的目的是定义 JSON 数据的验证、文档、超链接导航和交互控制。
本规范定义了 JSON 模式核心术语和机制；相关规范在此规范的基础上构建，定义了 JSON 模式的不同应用。
本文件中，“必须”、“禁止”、“必需”、“应”、“不应”、“建议”、“不建议”、“推荐”、“可以”和“可选”等关键词的解释如 RFC 2119 [RFC2119] 中所述。
本文件中，“JSON”、“JSON 文本”、“JSON 值”、“成员”、“元素”、“对象”、“数组”、“数字”、“字符串”、“布尔值”、“真”、“假”和“空”等术语的解释如 RFC 4627 [RFC4627] 中所述。
在引用 [RFC4627] 中定义的 JSON 对象时，术语“成员”和“属性”可以互换使用。
在引用 [RFC4627] 中定义的 JSON 数组时，术语“元素”和“项”可以互换使用。
JSON 模式是一个 JSON 文档，该文档必须是一个对象。由 JSON 模式（本规范或相关规范）定义的对象成员（或属性）称为关键字或模式关键字。
JSON 模式可以包含不是模式关键字的属性。
空模式是 JSON 模式，没有属性，或者具有不是模式关键字的属性。
这个 JSON 模式示例没有子模式
{
"title": "root"
}
JSON 模式也可以嵌套，如以下示例所示
{
"title": "root",
"otherSchema": {
"title": "nested",
"anotherSchema": {
"title": "alsoNested"
}
}
}
在这个示例中，“nested” 和 “alsoNested” 是子模式，“root” 是根模式。
JSON 模式为 JSON 值定义了七种基本类型
当且仅当以下情况时，两个 JSON 值才被认为是相等的
实例是任何 JSON 值。实例可以用一个或多个模式描述。
实例也可以称为“JSON 实例”或“JSON 数据”。
本文件建议使用新的媒体类型“application/schema+json”来标识用于描述 JSON 数据的 JSON 模式。JSON 模式本身是用 JSON 编写的。本规范和相关规范定义了关键字，允许根据允许的值、文本描述和解释与其他资源的关系来描述这些数据。以下部分是对相关规范中定义的功能的摘要。
JSON 模式允许应用程序验证实例，无论是非交互式还是交互式。例如，应用程序可以收集 JSON 数据并检查这些数据是否与给定的一组约束相匹配；另一个应用程序可以使用 JSON 模式来构建一个交互式界面，以便根据 JSON 模式描述的约束收集用户输入。
JSON 模式提供了一种从实例提取到其他资源的链接关系的方法，以及描述实例作为多媒体数据的解释的方法。这使得 JSON 数据可以被解释为丰富的超媒体文档，并置于更大的一组相关资源的上下文中。
据了解，实例可以是 [RFC4627] 中定义的任何有效 JSON 值。因此，JSON 模式不要求实例为特定类型：JSON 模式可以描述任何 JSON 值，包括空值。
JSON 模式与编程语言无关。唯一的限制是 [RFC4627] 中表达的限制以及主机编程语言的限制。
本规范承认 HTTP [RFC2616] 在互联网上使用的主导协议及其相关规范的丰富性。
本规范使用这些规范的子集来推荐一组机制，这些机制可被该协议使用，以将 JSON 实例与一个或多个模式关联起来。
JSON 模式没有为除 HTTP 之外的任何其他协议的客户端-服务器接口定义任何语义。这些语义是应用程序相关的，或者取决于参与使用 JSON 模式以满足自身需求的各方之间的协议。
本规范承认，一些编程语言及其关联的解析器对浮点数和整数使用不同的内部表示，而另一些则没有。
因此，出于互操作性的考虑，JSON Schema 上下文中使用的 JSON 值（无论是 JSON Schema 还是实例），都应确保数学整数被表示为本规范中定义的整数。
实现可以自由选择为 JSON 模式定义额外的关键字。除了明确的协议之外，模式作者不应期望同行实现支持这些额外的关键字。实现应忽略不支持的关键字。
模式和实例都是 JSON 值。因此，RFC 4627 [RFC4627] 中定义的所有安全注意事项都适用。
"$schema" 关键字既用作 JSON 模式版本标识符，也用作资源的位置，该资源本身是一个 JSON 模式，用于描述为此特定版本编写的任何模式。
此关键字必须位于 JSON Schema 的根目录。该关键字的值必须是一个 URI [RFC3986] 和一个有效的 JSON 引用 [json-reference]；此 URI 必须是绝对的且规范化的。位于此 URI 的资源必须成功描述自身。建议方案作者在其方案中包含此关键字。
以下是预定义的值
在使用自定义关键字扩展 JSON Schema 时，方案作者应该为“$schema”定义一个自定义 URI。此自定义 URI 必须不是预定义值之一。
JSON Schema 使用 JSON 引用 [json-reference] 作为方案寻址机制。它通过两种方式扩展了此规范
在方案中改变 URI 被称为定义一个新的解析范围。方案的初始解析范围是方案本身的 URI（如果有），或者如果方案不是从 URI 加载的，则为空 URI。
此关键字的值必须是一个字符串，并且必须是一个有效的 URI。此 URI 必须是规范化的，并且不应该是一个空片段（#）或空 URI。
“id”关键字（或简称为“id”）用于改变解析范围。当遇到一个 id 时，实现必须将此 id 解析到最直接的父范围。解析后的 URI 将是此子方案及其所有子方案的新解析范围，直到遇到另一个 id 为止。
在使用“id”改变解析范围时，方案作者应该确保解析范围在方案中是唯一的。
此方案将作为示例
{
"id": "http://x.y.z/rootschema.json#",
"schema1": {
"id": "#foo"
},
"schema2": {
"id": "otherschema.json",
"nested": {
"id": "#bar"
},
"alsonested": {
"id": "t/inner.json#a"
}
},
"schema3": {
"id": "some://where.else/completely#"
}
}
以下 URI 编码的 JSON 指针 [json-pointer]（从根方案开始）处的子方案定义了以下解析范围
在将 URI 解析到解析范围时，实现可以选择两种操作模式
实现必须支持规范反引用，并且可以支持内联反引用。
例如，考虑此方案
{
"id": "http://my.site/myschema#",
"definitions": {
"schema1": {
"id": "schema1",
"type": "integer"
},
"schema2", {
"type": "array",
"items": { "$ref": "schema1" }
}
}
}
当实现遇到“schema1”引用时，它会将它解析到最直接的父范围，从而导致 URI“http://my.site/schema1#”。处理此 URI 的方式将根据选择的反引用模式而有所不同
在使用内联反引用时，解析范围可能导致 URI 具有一个非空的片段部分，该部分不是 JSON 指针，如以下示例所示
{
"id": "http://some.site/schema#",
"not": { "$ref": "#inner" },
"definitions": {
"schema1": {
"id": "#inner",
"type": "boolean"
}
}
}
选择支持内联反引用的实现应该能够使用这种类型的引用。但是，选择使用规范反引用的实现不需要支持它。
内联反引用可以产生与根方案的规范 URI 不同的规范 URI。方案作者应该确保使用规范反引用的实现获得与使用内联反引用的实现相同的内容。
使用不是 JSON 指针的片段的扩展 JSON 引用不能被选择不支持内联反引用的实现反引用。这种类型的引用是为了向后兼容而定义的，不应该在新方案中使用。
此规范承认，大多数交互式 JSON Schema 处理将在 HTTP 上进行。因此，本节建议使用目前可用于此协议的机制来实现实例/方案关联。实例被认为是由一个（或多个）方案描述的。
建议将名为“profile”的 MIME 类型参数附加到正在处理的实例的“Content-Type”标头。如果存在，此参数的值必须是一个有效的 URI，并且此 URI 应该解析到一个有效的 JSON Schema。MIME 类型必须是“application/json”，或任何其他子类型。
这样的标头的示例是
Content-Type: application/my-media-type+json;
profile=http://example.com/my-hyper-schema#
在使用“Link”标头时，使用的关系类型必须是“describedBy”，如 RFC 5988，第 5.3 节 [RFC5988] 中定义的。 “Link”标头的目标 URI 必须是一个有效的 JSON Schema。
这样的标头的示例是
Link: <http://example.com/my-hyper-schema#>; rel="describedBy"
JSON Schema 的拟议 MIME 媒体类型定义如下
| [RFC2119] | Bradner, S.， "RFC 中用于指示要求级别的关键词"，BCP 14，RFC 2119，DOI 10.17487/RFC2119，1997 年 3 月。 |
| [RFC2616] | Fielding, R.， Gettys, J.， Mogul, J.， Frystyk, H.， Masinter, L.， Leach, P. 和 T. Berners-Lee， "超文本传输协议 - HTTP/1.1"，RFC 2616，DOI 10.17487/RFC2616，1999 年 6 月。 |
| [RFC3986] | Berners-Lee, T.， Fielding, R. 和 L. Masinter， "统一资源标识符 (URI)：通用语法"，STD 66，RFC 3986，DOI 10.17487/RFC3986，2005 年 1 月。 |
| [RFC4627] | Crockford, D.， "用于 JavaScript 对象表示法 (JSON) 的 application/json 媒体类型"，RFC 4627，DOI 10.17487/RFC4627，2006 年 7 月。 |
| [RFC5988] | Nottingham, M.， "Web 链接"，RFC 5988，DOI 10.17487/RFC5988，2010 年 10 月。 |
| [json-reference] | Bryan, P. 和 K. Zyp， "JSON 引用（正在进行的工作）"，2012 年 9 月。 |
| [json-pointer] | Bryan, P. 和 K. Zyp， "JSON 指针（正在进行的工作）"，2012 年 9 月。 |
| [json-schema-03] | Court, G. 和 K. Zyp， "JSON Schema，草案 3"，2012 年 9 月。 |