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

摘要

JSON Schema 定义了媒体类型“application/schema+json”，这是一种基于 JSON 的格式，用于描述 JSON 数据的结构。JSON Schema 断言 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 模式关键字分为几个常见的行为类别。断言验证实例是否满足约束，生成布尔结果。注释附加应用程序可以随意使用的信息。应用程序将子模式应用于实例的部分并组合其结果。¶

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

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

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

{
    "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 一样。 ¶

此词汇表的当前 URI（称为 Unevaluated 应用器词汇表）是：<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 渲染器等生成用例通常认为引用在语义上是重要的。¶

为了使这种特定用例的语义明确，最佳实践是在同一个 schema 对象中创建用于注释关键字，与 $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",
        }
    }
}

这里，这个 schema 代表某种面向对象的类。 "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. 变更日志

在离开 Internet-Draft 状态之前，此部分将被删除。¶

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 确定¶
• 定义复合模式文档（bundle）和处理¶
• 引用 ECMA-262，第 11 版以获得正则表达式支持¶
• 正则表达式应该支持 unicode¶
• 删除媒体类型参数¶
• 指定未知关键字被收集为注释¶
• 将 "unevaluatedItems" 和 "unevaluatedProperties" 从核心移动到它们自己的词汇表中¶

draft-handrews-json-schema-02

• 更新到 RFC 8259 以获得 JSON 规范¶
• 将 "definitions" 从验证规范移动到这里作为 "$defs"¶
• 将应用器关键字从验证规范移动到它们自己的词汇表中¶
• 将 "dependencies" 的 schema 形式从验证规范移动到 "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¶
• 详尽的 schema 标识示例¶
• 用实现如何以及何时可能从另一个文档中知道一个 schema 来替换 "外部引用"¶
• 用实现如何在解析过程中识别 schema 标识符来替换 "内部引用"¶
• 解除引用以前的 "内部" 或 "外部" 引用始终是相同的过程¶
• 轻微的格式改进¶

draft-handrews-json-schema-00

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

draft-wright-json-schema-01

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

draft-wright-json-schema-00

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

draft-zyp-json-schema-04

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

draft-zyp-json-schema-00

• 初始草案。¶