JSON 模式：用于描述 JSON 文档的媒体类型

摘要

JSON 模式定义了媒体类型 "application/schema+json"，这是一种基于 JSON 的格式，用于描述 JSON 数据的结构。JSON 模式断言 JSON 文档应该是什么样子，以及如何从 JSON 文档中提取信息，以及如何与 JSON 文档进行交互。媒体类型 "application/schema-instance+json" 为 "application/schema+json" 提供了更丰富的功能集成，超出了 "application/json" 文档所能提供的功能。 ¶

1. 简介

JSON Schema 是一种用于定义 JSON 数据结构的 JSON 媒体类型。JSON Schema 用于定义 JSON 数据的验证、文档、超链接导航和交互控制。 ¶

本规范定义了 JSON Schema 的核心术语和机制，包括通过引用指向另一个 JSON Schema、取消引用 JSON Schema 引用、指定使用的方言、指定方言的词汇表要求以及定义预期的输出。 ¶

其他规范定义了用于对验证、链接、注释、导航和交互进行断言的词汇表。 ¶

2. 约定和术语

本文件中使用的关键术语“必须”、“不得”、“必需”、“应”、“不应”、“建议”、“不建议”、“可选”的解释如 RFC 2119 [RFC2119] 中所述。 ¶

本文件中使用的术语“JSON”、“JSON 文本”、“JSON 值”、“成员”、“元素”、“对象”、“数组”、“数字”、“字符串”、“布尔值”、“真”、“假”和“空值”的解释如 RFC 8259 [RFC8259] 中所述。 ¶

3. 概述

本文档提出了一种新的媒体类型“application/schema+json”，用于标识用于描述 JSON 数据的 JSON Schema。它还提出了一种可选的媒体类型“application/schema-instance+json”，以提供额外的集成功能。JSON Schema 本身就是 JSON 文档。本规范及其相关规范定义了关键字，允许作者以多种方式描述 JSON 数据。 ¶

JSON Schema 使用关键字来断言对 JSON 实例的约束或用附加信息来注释这些实例。其他关键字用于将断言和注释应用于更复杂的 JSON 数据结构，或者基于某种条件。 ¶

为了便于重用，关键字可以组织成词汇表。词汇表包含关键字列表及其在元模式中标识的语法和语义。方言定义为一组词汇表及其在元模式中标识的必需支持。 ¶

JSON Schema 可以通过定义附加词汇表或非正式地通过在任何词汇表之外定义附加关键字来扩展。未识别的单个关键字只是将其值收集为注释，而关于未识别词汇表的行为可以在声明使用哪些词汇表时控制。 ¶

本文档定义了一个核心词汇表，任何实现都必须支持，并且无法禁用。其关键字都以“$”字符为前缀，以强调其必需的性质。该词汇表对于“application/schema+json”媒体类型的正常运行至关重要，并用于引导加载其他词汇表。 ¶

此外，本文档定义了一个推荐的词汇表，用于有条件地应用子模式，以及将子模式应用于对象和数组的内容。无论这些模式是用于断言验证、注释还是两者兼而有之，都需要该词汇表或非常类似的词汇表来编写非平凡 JSON 实例的模式。虽然不是必需的核心词汇表的一部分，但为了实现最大的互操作性，本文档中包含了该附加词汇表，强烈建议使用它。 ¶

其他文档定义了用于结构验证或超媒体注释等目的的进一步词汇表。这些其他文档每个都定义了一个方言，收集编写用于该文档目的的模式所需的标准词汇表集。 ¶

4. 定义

{
    "title": "root",
    "items": {
        "title": "array item"
    }
}

6. 一般注意事项

7. 关键字行为

JSON Schema 关键字属于几个通用的行为类别。断言验证实例是否满足约束，产生布尔结果。注释附加应用程序可以以任何他们认为合适的方式使用的信息。应用器将子模式应用于实例的各个部分并组合其结果。¶

扩展关键字**应该**保留在这些类别中，牢记注释特别灵活。复杂的行为通常最好委托给基于注释数据的应用程序，而不是直接作为模式关键字实现。但是，扩展关键字**可以**为专门目的定义其他行为。¶

针对模式评估实例涉及对模式中的所有关键字进行处理，以针对实例中的适当位置进行处理。通常，应用器关键字被处理，直到达到没有应用器（因此没有子模式）的模式对象。实例中的适当位置根据模式对象中的断言和注释关键字进行评估，并将它们的结果根据应用器的规则收集到父模式中。¶

一旦所有子模式都被评估，父模式对象的评估就可以完成，尽管在某些情况下，评估可能会由于断言结果而被短路。当收集注释时，一些断言结果短路是不可能的，因为需要检查所有子模式以进行注释收集，包括那些不能进一步改变断言结果的子模式。¶

{
    "type": ["string", "null"],
    "maxLength": 255
}

{
    "title": "Feature list",
    "type": "array",
    "prefixItems": [
        {
            "title": "Feature A",
            "properties": {
                "enabled": {
                    "$ref": "#/$defs/enabledToggle",
                    "default": true
                }
            }
        },
        {
            "title": "Feature B",
            "properties": {
                "enabled": {
                    "description": "If set to null, Feature B
                                    inherits the enabled
                                    value from Feature A",
                    "$ref": "#/$defs/enabledToggle"
                }
            }
        }
    ],
    "$defs": {
        "enabledToggle": {
            "title": "Enabled",
            "description": "Whether the feature is enabled (true),
                            disabled (false), or under
                            automatic control (null)",
            "type": ["boolean", "null"],
            "default": null
        }
    }
}

{
    "oneOf": [
        {
            "title": "Integer Value",
            "type": "integer"
        },
        {
            "title": "String Value",
            "type": "string"
        }
    ]
}

8. JSON Schema 核心词汇表

本节中声明的关键字（均以 "$" 开头）构成了 JSON Schema 核心词汇表。这些关键字对于处理任何模式或元模式都是必需的，包括跨多个文档拆分的模式或元模式，或者存在是为了保留关键字用于需要保证互操作性的目的。¶

为了启动进一步词汇表的处理，核心词汇表 MUST 一直被视为强制性的。使用"$vocabulary" (第 8.1 节) 关键字声明正在使用的词汇表的元模式 MUST 明确列出核心词汇表，该词汇表 MUST 具有值为 true 的值，表示它是必需的。¶

此词汇表（仅此词汇表）的 false 值的行为是未定义的，当 "$vocabulary" 存在但未包含核心词汇表时，行为也是未定义的。但是，RECOMMENDED 实施检测这些情况并在发生这些情况时引发错误。声明元模式可选地使用核心是没有意义的。¶

不使用 "$vocabulary" 的元模式 MUST 被认为需要核心词汇表，就好像它的 URI 存在且值为 true 一样。¶

核心词汇表的当前 URI 为：<https://json-schema.fullstack.org.cn/draft/2020-12/vocab/core>。¶

相应元模式的当前 URI 为：https://json-schema.fullstack.org.cn/draft/2020-12/meta/core。¶

虽然 "$" 前缀并未正式保留用于核心词汇表，但 RECOMMENDED 扩展关键字（在词汇表中或其他地方）以非 "$" 字符开头，以避免将来可能发生的冲突。¶

{
    "type": "array",
    "items": { "$ref": "#/$defs/positiveInteger" },
    "$defs": {
        "positiveInteger": {
            "type": "integer",
            "exclusiveMinimum": 0
        }
    }
}

9. 加载和处理架构

{
    "$id": "https://example.net/root.json",
    "items": {
        "type": "array",
        "items": { "$ref": "#item" }
    },
    "$defs": {
        "single": {
            "$anchor": "item",
            "type": "object",
            "additionalProperties": { "$ref": "other.json" }
        }
    }
}

{
    "$id": "https://example.com/foo",
    "items": {
        "$id": "https://example.com/bar",
        "additionalProperties": { }
    }
}

{
    "$id": "https://example.com/foo",
    "items": {
        "$ref": "bar"
    }
}

{
    "$id": "https://example.com/bar",
    "additionalProperties": { }
}

        Link: <https://example.com/my-hyper-schema>; rel="describedby"

        User-Agent: product-name/5.4.1 so-cool-json-schema/1.0.2 curl/7.43.0

10. 用于应用子模式的词汇表

本节定义了一组应用关键字词汇表，建议将它们用作其他词汇表的依据。¶

不使用 "$vocabulary" 的元模式应该被认为需要此词汇表，就像它的 URI 存在于值为 true 时一样。¶

此词汇表的当前 URI（称为应用器词汇表）是：<https://json-schema.fullstack.org.cn/draft/2020-12/vocab/applicator>。¶

相应元模式的当前 URI 是：https://json-schema.fullstack.org.cn/draft/2020-12/meta/applicator。¶

11. 未评估位置的词汇表

这些关键字的目的是使模式作者能够将子模式应用于尚未根据任何相邻关键字的任何动态范围子模式成功评估的数组项或对象属性。 ¶

这些实例项或属性可能已根据一个或多个相邻关键字子模式不成功地进行评估，例如，当 "anyOf" 的一个分支中的断言失败时。此类失败的评估不被视为有助于确定该项或属性是否已评估。只有成功的评估才被考虑。 ¶

如果数组中的项或对象属性被 "成功评估"，则在逻辑上它被认为在预期对象或数组的表示形式方面是有效的。例如，如果子模式表示一辆汽车，它需要 2-4 个车轮，并且 "wheels" 的值为 6，则实例对象不会被 "评估" 为一辆汽车，并且 "wheels" 属性被认为是 "未评估（成功地作为已知的事物）"，并且不会保留任何注释。 ¶

回想一下，相邻关键字是同一个模式对象中的关键字，动态范围子模式包括引用目标和词法子模式。 ¶

这些关键字的行为取决于应用于正在验证的实例位置的相邻关键字的注释结果。 ¶

不使用 "$vocabulary" 的元模式**应该**被认为需要此词汇表，就像其 URI 存在并且值为 true 一样。 ¶

此词汇表（称为 Unevaluated Applicator 词汇表）的当前 URI 是：<https://json-schema.fullstack.org.cn/draft/2020-12/vocab/unevaluated>。 ¶

相应元模式的当前 URI 是：https://json-schema.fullstack.org.cn/draft/2020-12/meta/unevaluated。 ¶

14. IANA 注意事项

15. 参考资料

附录 B. 操作架构文档和引用

已创建各种工具来根据引用 (“$ref”) 的出现方式和位置重新排列架构文档。本附录讨论哪些用例和操作符合本规范。¶

附录 D. 使用词汇表

{
  "$schema": "https://json-schema.fullstack.org.cn/draft/2020-12/schema",
  "$id": "https://example.com/meta/general-use-example",
  "$dynamicAnchor": "meta",
  "$vocabulary": {
    "https://json-schema.fullstack.org.cn/draft/2020-12/vocab/core": true,
    "https://json-schema.fullstack.org.cn/draft/2020-12/vocab/applicator": true,
    "https://json-schema.fullstack.org.cn/draft/2020-12/vocab/validation": true,
    "https://example.com/vocab/example-vocab": true
  },
  "allOf": [
    {"$ref": "https://json-schema.fullstack.org.cn/draft/2020-12/meta/core"},
    {"$ref": "https://json-schema.fullstack.org.cn/draft/2020-12/meta/applicator"},
    {"$ref": "https://json-schema.fullstack.org.cn/draft/2020-12/meta/validation"},
    {"$ref": "https://example.com/meta/example-vocab"}
  ],
  "patternProperties": {
    "^unevaluated": false
  },
  "properties": {
    "localKeyword": {
      "$comment": "Not in vocabulary, but validated if used",
      "type": "string"
    }
  }
}

{
  "$schema": "https://json-schema.fullstack.org.cn/draft/2020-12/schema",
  "$id": "https://example.com/meta/example-vocab",
  "$dynamicAnchor": "meta",
  "$vocabulary": {
    "https://example.com/vocab/example-vocab": true,
  },
  "type": ["object", "boolean"],
  "properties": {
    "minDate": {
      "type": "string",
      "pattern": "\d\d\d\d-\d\d-\d\d",
      "format": "date",
    }
  }
}

附录 E. 参考和生成用例

虽然预计参考的存在对验证结果是透明的，但代码生成器和 UI 渲染器等生成用例通常将参考视为语义上的重要意义。 ¶

为了使这种用例特定的语义明确，最佳实践是在与“$ref”等参考关键字相同的模式对象中创建注释关键字以供使用。 ¶

例如，这里有一个假设关键字，用于确定代码生成器是否应将参考目标视为一个不同的类，以及这些类如何相关。请注意，此示例仅用于说明目的，不打算提出功能性代码生成关键字。 ¶

{
    "allOf": [
        {
            "classRelation": "is-a",
            "$ref": "classes/base.json"
        },
        {
            "$ref": "fields/common.json"
        }
    ],
    "properties": {
        "foo": {
            "classRelation": "has-a",
            "$ref": "classes/foo.json"
        },
        "date": {
            "$ref": "types/dateStruct.json",
        }
    }
}

在这里，此模式表示某种面向对象的类。 “allOf”中的第一个参考被标记为基类。第二个没有分配类关系，这意味着代码生成器应将目标的定义与这个定义组合在一起，就好像没有参考一样。 ¶

查看属性，“foo”被标记为对象组合，而“date”属性则没有。它只是一个包含子字段的字段，而不是一个独立类的实例。 ¶

这种使用风格要求注释与参考位于同一个对象中，该对象必须可以识别为参考。 ¶

附录 F. 致谢

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

感谢 Jason Desrosiers、Daniel Perrett、Erik Wilde、Evgeny Poberezkin、Brad Bowman、Gowry Sankar、Donald Pipowitch、Dave Finlay、Denis Laxalde、Phil Sturgeon、Shawn Silverman 和 Karen Etheridge 对该文档的提交和补丁。 ¶

附录 G. 更改日志

在离开互联网草案状态之前将删除此部分。¶

draft-bhutton-json-schema-01

• 改进和澄清“type”，“contains”，“unevaluatedProperties”和“unevaluatedItems”关键字说明 ¶
• 澄清“规范 URI”的各个方面 ¶
• 关于注释和“additionalProperties”的歧义性说明 ¶
• 澄清词汇表不必正式定义 ¶
• 删除对剩余媒体类型参数的引用 ¶
• 修复多个示例 ¶

draft-bhutton-json-schema-00

• “$schema”可能更改为嵌入式资源 ¶
• 数组值“items”功能现在是“prefixItems” ¶
• “items”包含“additionalItems”的旧功能 ¶
• “contains”注释行为，以及“contains”和“unevaluatedItems”交互现在已指定 ¶
• 将 $recursive* 重命名为 $dynamic*，并修改行为 ¶
• $dynamicAnchor 定义了类似于 $anchor 的片段 ¶
• $dynamic*（以前是 $recursive）不再使用运行时基 URI 确定 ¶
• 定义复合模式文档（捆绑）和处理 ¶
• 参考 ECMA-262，第 11 版以获取正则表达式支持 ¶
• 正则表达式应支持 Unicode ¶
• 删除媒体类型参数 ¶
• 指定未知关键字被收集为注释 ¶
• 将“unevaluatedItems”和“unevaluatedProperties”从核心移至其自己的词汇表 ¶

draft-handrews-json-schema-02

• 更新至 RFC 8259 以获取 JSON 规范 ¶
• 将“definitions”从验证规范移至此处作为“$defs” ¶
• 将应用器关键字从验证规范移至其自己的词汇表 ¶
• 将“dependencies”的模式形式从验证规范移至“dependentSchemas” ¶
• 正式化注释收集 ¶
• 指定推荐的输出格式 ¶
• 根据注释和断言结果定义关键字交互 ¶
• 添加了“unevaluatedProperties”和“unevaluatedItems” ¶
• 根据断言、应用器和注释模型定义“$ref”行为 ¶
• 允许关键字与“$ref”相邻 ¶
• 注意“$ref”目标涉及未知关键字的未定义行为 ¶
• 添加递归引用，主要用于元模式扩展 ¶
• 添加正式词汇表的概念，以及如何通过元模式识别它们 ¶
• 关于初始基 URI 超越网络检索的额外指导 ¶
• 允许“application/schema+json”的“schema”媒体类型参数 ¶
• 更好地解释媒体类型参数和 HTTP Accept 标头 ¶
• 使用“$id”仅建立规范和基绝对 URI，没有片段 ¶
• 将“$id”的简单名称片段形式替换为“$anchor” ¶
• 澄清 JSON 指针在“$id”边界上的行为不可靠 ¶

draft-handrews-json-schema-01

• 此草案纯粹是澄清，没有功能性更改 ¶
• 强调注释作为 JSON Schema 的主要用途 ¶
• 通过用例澄清 $id ¶
• 详尽的模式识别示例 ¶
• 将“外部引用”替换为实现何时以及如何可能从另一个文档中了解模式 ¶
• 将“内部引用”替换为实现如何在解析期间识别模式标识符 ¶
• 取消引用以前的“内部”或“外部”引用始终是相同的过程 ¶
• 次要格式改进 ¶

draft-handrews-json-schema-00

• 使模式关键字词汇表的概念更加清晰 ¶
• 注意“整数”的概念来自词汇表，而不是数据模型 ¶
• 将关键字分类为断言或注释，并描述其一般行为 ¶
• 根据广义断言解释布尔模式 ¶
• 为模式的非用户可见注释保留“$comment” ¶
• 关于“$id”和片段的措辞改进 ¶
• 注意使用递归引用扩展元模式的挑战 ¶
• 添加“application/schema-instance+json”媒体类型 ¶
• 推荐使用“schema”链接关系/参数而不是“profile” ¶

draft-wright-json-schema-01

• 更新了介绍 ¶
• 允许任何模式都是布尔值 ¶
• “$schema”不应出现在子模式中，尽管这可能会改变 ¶
• 将“id”更改为“$id”；所有核心关键字都以“$”为前缀 ¶
• 澄清和正式化“application/schema+json”的片段 ¶
• 注意对可以表示在 JSON 数据模型中的格式（例如 CBOR）的适用性 ¶

draft-wright-json-schema-00

• 更新了对 JSON 的引用 ¶
• 更新了对 HTTP 的引用 ¶
• 更新了对 JSON 指针的引用 ¶
• “id”的行为现在根据 RFC3986 指定 ¶
• 将 URI 的词汇表用法与 RFC3986 对齐 ¶
• 删除对 draft-pbryan-zyp-json-ref-03 的引用 ¶
• 将“$ref”的使用限制在期望模式的任何地方 ¶
• 添加了“JSON Schema 数据模型”的定义 ¶
• 添加了额外的安全注意事项 ¶
• 定义了“id”的子模式标识符的使用 ¶
• 重写了有关使用 HTTP 的部分 ¶
• 重写了有关使用 rel="describedBy" 和 rel="profile" 的部分 ¶
• 修复了许多无效的示例 ¶

draft-zyp-json-schema-04

• 从草案 v3 中抢救 ¶
• 将验证关键字拆分为单独的文档 ¶
• 将超媒体关键字拆分为单独的文档 ¶
• 初始拆分后草案 ¶
• 强制使用 JSON 参考、JSON 指针 ¶
• 定义“id”的作用。定义 URI 解析范围 ¶
• 添加互操作性考虑因素 ¶

draft-zyp-json-schema-00

• 初始草案 ¶