OpenAPI 规范 v3.2.0

OAD 中每个文档 MUST 完全解析，以定位可能的引用目标。 包括对 JSON Schema 规范（2020-12草案）的解析要求，并根据URI 相对引用对基础 URI 做修改。 引用目标由字段如 OpenAPI 对象的 $self、Schema 对象的 $id、$anchor 和 $dynamicAnchor 关键字定义。

工具 MUST NOT 在完全解析所有可作为 OAD 部分的文档前，将某引用视为无法解析。

如在解析引用时只解析了文档的一部分，则行为为实现自定义或未定义；参见 碎片化解析警告及 附录 G 详细说明。

OpenAPI 描述内用于引用、外部文档或如许可证等补充信息的 URI 作为标识符被解析，规范中称为 URI，与API URL区分。注意部分 URI 字段因历史原因名为 url，但描述采用正确的“URI”术语。

如文档解析所述，多个字段可用于将 OpenAPI 文档或 Schema 对象关联到 URI，该 URI 不一定与文档或 schema 的实际位置一致。这样在不同部署环境（如本地文件系统，安全或网络受限环境）下可使用相同引用。

除非另行说明，所有作为 URI 的字段 MAY 接受 [RFC3986] 第 4.2 节 定义的相对引用。

本规范的若干特性要求解析某些非 URI 连接至 OAD 其它部分。

在单文档 OAD 中这些连接可明确解析；在多文档 OAD 下，解析过程属于实现自定义，但须符合本节约束。 部分情况下可用明确的 URI 替代，强烈建议 OAD 作者 RECOMMENDED 使用 URI 以提升工具兼容性。

解析来自引用（非入口）文档的 Components 对象和Tag 对象名称时，建议工具 RECOMMENDED 从入口文档解析而不是当前文档。解析基于 operationId 的 Operation 对象时，建议同时考虑所有已解析文档中的 Operation 对象。

隐式连接解析不影响 URI 解析 及其目标。

更多细节及使用隐式连接的对象和字段清单详见 附录 G：解析与解析指导。

假设以下 OpenAPI 文档的检索 URI 为 https://device1.example.com：

openapi: 3.2.0
$self: https://apidescriptions.example.com/foo
info:
  title: Example API
  version: 1.0
servers:
- url: .
  description: The production API on this device
- url: ./test
  description: The test API on this device

对于 API URLs，应忽略标识 OpenAPI 文档的 $self 字段，改用检索 URI。这样会得到规范化的生产 URL 为 https://device1.example.com，以及规范化的测试 URL 为 https://device1.example.com/test。

假设存在如下路径，如果使用，则具体定义 /pets/mine 将优先匹配：

  /pets/{petId}
  /pets/mine

以下路径被视为相同且无效：

  /pets/{petId}
  /pets/{name}

以下情况可能导致歧义解析：

  /{entity}/me
  /books/{id}

这些字段 MAY 与 content 或 schema 一起使用。

example 与 examples 字段互斥；有关验证要求的指导，请参阅 Working with Examples。

该对象 MAY 可通过 规范扩展 进行扩展。

注意，虽然如果 in 为 "header" 时 "Cookie" 作为 name 并非被禁止，但这样定义 cookie 参数的效果是未定义的；应使用 in: "cookie"。

对于简单场景，schema 和 style 可以描述参数的结构和语法。

这些字段 MUST NOT 与 in: "querystring" 一起使用。

对于具有 schema 且 in: "header" 或 in: "cookie", style: "cookie" 的参数，需要注意：

• 序列化这些值时，不应应用 URI 百分号编码（MUST NOT）。
• 解析这些参数时，任何看起来像百分号编码的内容都不应被解码（MUST NOT）。
• 如果使用的 RFC6570 实现自动执行编码或解码步骤，则在使用之前必须撤销这些步骤（MUST）。

在这些情况下，实现 MUST 原样传递值，而不是尝试对其进行引用或转义，因为头和 cookie 的引用规则与转义约定差异太大，无法自动处理；有关引用和转义的指导，请参见 附录 D。

另请参见 附录 C：使用基于 RFC6570 的序列化 以获取更多指导。

对于更复杂的场景，content 字段可定义参数的媒体类型和 schema，并提供其使用示例。

对于 in: "querystring" 和 application/x-www-form-urlencoded 的使用，请参见 Encoding the x-www-form-urlencoded Media Type。

OpenAPI Initiative 维护了一个 Media Type Registry，汇总了本规范期望支持的媒体类型并索引了哪些章节讨论了哪些媒体类型。该注册表还链接到 IANA 注册（若存在）以及与每种媒体类型相关的最重要的规范文档。 在该注册表中作为扩展或为后续版本添加的任何附加媒体类型，MAY 被本版本 OAS 的实现所支持。

在本规范中，顺序媒体类型 定义为任何由重复结构组成且没有头部、尾部、信封或其它元数据附加到序列之外的媒体类型。

一些顺序媒体类型示例（包括一些未在 IANA 注册但常用的）为：

  application/jsonl
  application/x-ndjson
  application/json-seq
  application/geo+json-seq
  text/event-stream
  multipart/mixed

在前面三个示例中，重复结构为任何 JSON value。第四个重复的是 application/geo+json 结构化值，而 text/event-stream 则重复与服务器发送事件相关的自定义文本格式。最后列出的 multipart/mixed 提供任意媒体类型文档的有序列表，有时用于流式传输。 注意尽管 multipart 格式在技术上允许前言和结尾，但 RFC 指示应忽略它们，使其实际作为注释，本规范不对其进行建模。

实现 MUST 支持将顺序媒体类型映射到 JSON Schema 数据模型，方法是将其视为按相同顺序排列的数组中的值。

关于在流式上下文中处理顺序媒体类型的更多信息，包括对 text/event-stream 内容的特殊考虑，请参见 Complete vs Streaming Content。对于 multipart 类型，也请参见 Encoding By Position。

maxLength 关键字 MAY 用于设置由字符串数据（包括编码的二进制数据）或未编码的二进制数据组成的流式有效载荷的预计上限长度。对于未编码的二进制数据，长度以八位字节（octets）计。 在这种用例中，maxLength MAY 在常规 JSON Schema 验证之外被实现，因为 JSON Schema 并不直接适用于二进制数据，并且对编码的二进制流将其完整存于内存中可能不可行。

encoding 字段的行为旨在支持 Web 表单，因此仅为结构为允许重复值的名-值对的媒体类型定义，最显著的是 application/x-www-form-urlencoded 与 multipart/form-data。

要使用 encoding 字段，字段下的每个键 MUST 在属性中存在；没有对应属性的 encoding 条目 SHALL 被忽略。 数组属性 MUST 通过对数组的每个项应用给定的 Encoding Object 来处理，以生成每个数组项对应的一个已编码值，且这些已编码值使用相同的 name，这与 [RFC7578] 第 4.3 节 建议的为表单字段提供多个值的做法一致。 对于顶层非数组属性以及顶层数组内的值（包括数组值）的所有其他值类型，应将 Encoding Object 应用于整个值。 这些名-值对在目标媒体类型中的顺序由实现定义。

对于 application/x-www-form-urlencoded，编码键 MUST 映射到参数名称，值按照 Encoding Object 的规则生成。有关使用与不使用 encoding 字段的指导与示例，请参见 Encoding the x-www-form-urlencoded Media Type。

对于 multipart，编码键 MUST 映射到每个部分的 Content-Disposition: form-data 头的 name 参数，如 [RFC7578] 所定义。关于非 ASCII 部分名称的指导，请参见 RFC7578 的 第 5 节。

有关带或不带 encoding 字段的更多指导与示例，请参见 Encoding multipart Media Types。

大多数 multipart 媒体类型（包括定义解析所有 multipart 类型基础规则的 multipart/mixed）没有命名的部分。 这些媒体类型的数据被建模为数组，每个部分对应一个按序的项。

要使用 prefixEncoding 和/或 itemEncoding 字段，必须存在 itemSchema 或数组形式的 schema。 这些字段类似于 JSON Schema 的 prefixItems 和 items 关键字，其中 prefixEncoding（若存在）提供一个 Encoding Object 数组，每个 Encoding Object 应用于数据数组中相同位置的值，而 itemEncoding 将其单个 Encoding Object 应用于数组中剩余的所有项。 与 prefixItems 一样，如果实例数组比 prefixEncoding 数组短，这并非错误；额外的 Encoding Objects SHALL 被忽略。

itemEncoding 字段也可与 itemSchema 一起使用以支持流式 multipart 内容。

prefixEncoding 字段可与任何 multipart 内容一起使用以强制固定的部分顺序。 这包括 multipart/form-data，对于此类情形，Encoding Object 的 headers 字段 MUST 用于提供 Content-Disposition 与部分名称，因为没有属性名可自动提供名称。

本规范的早期版本建议在非 multipart/form-data 的 multipart 媒体类型中使用每部分的 Content-Disposition: form-data 头的 name 参数 来规避 encoding 字段的限制。 实现 MAY 选择支持该变通方法，但由于该用法并不常见，非 form-data 类型的 multipart 媒体类型的实现很可能不会支持它。

请注意，由于此示例以 YAML 编写，Example Object 的 value 字段可以格式化为 YAML，因为 YAML 可轻松转换为 JSON，从而避免将 JSON 嵌入为字符串。

application/json:
  schema:
    $ref: '#/components/schemas/Pet'
  examples:
    cat:
      summary: An example of a cat
      value:
        name: Fluffy
        petType: Cat
        color: White
        gender: male
        breed: Persian
    dog:
      summary: An example of a dog with a cat's name
      value:
        name: Puma
        petType: Dog
        color: Black
        gender: Female
        breed: Mixed
    frog:
      $ref: '#/components/examples/frog-example'

另外，由于所有 JSON 都是有效的 YAML，示例值也可以在 YAML 文档中使用 JSON 语法：

application/json:
  schema:
    $ref: '#/components/schemas/Pet'
  examples:
    cat:
      summary: An example of a cat
      value: {
        "name": "Fluffy",
        "petType": "Cat",
        "color": "White",
        "gender": "male",
        "breed": "Persian"
      }
    dog:
      summary: An example of a dog with a cat's name
      value: {
        "name": "Puma",
        "petType": "Dog",
        "color": "Black",
        "gender": "Female",
        "breed": "Mixed"
      }
    frog:
      $ref: '#/components/examples/frog-example'

对于任何其序列项为 JSON 值的 顺序媒体类型，无需对每个值进行转换。 JSON 文本序列（[RFC7464] 的 application/json-seq 以及 [RFC8091] 的 +json-seq 结构后缀）、JSON Lines（application/jsonl）和 NDJSON（application/x-ndjson）都属于此类。注意 JSON Lines 与 NDJSON 的媒体类型尚未在 IANA 注册，但被广泛使用。

下面示例展示了用于流式日志条目和响应查询时返回固定长度集合的 Media Type Objects，展示了 schema 与 itemSchema 之间的关系以及何时使用它们，尽管在两种情况下 examples 字段相同。

components:
  schemas:
    LogEntry:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
        level:
          type: integer
          minimum: 0
        message:
          type: string
    Log:
      type: array
      items:
        $ref: "#/components/schemas/LogEntry"
      maxItems: 100
  examples:
    LogJSONSeq:
      summary: Log entries in application/json-seq
      # JSON Text Sequences require an unprintable character
      # that cannot be escaped in a YAML string, and therefore
      # must be placed in an external document shown below
      externalValue: examples/log.json-seq
    LogJSONPerLine:
      summary: Log entries in application/jsonl or application/x-ndjson
      description: JSONL and NDJSON are identical for this example
      # Note that the value must be written as a string with newlines,
      # as JSONL and NDJSON are not valid YAML
      value: |
        {"timestamp": "1985-04-12T23:20:50.52Z", "level": 1, "message": "Hi!"}
        {"timestamp": "1985-04-12T23:20:51.37Z", "level": 1, "message": "Bye!"}
  responses:
    LogStream:
      description: |
        A stream of JSON-format log messages that can be read
        for as long as the application is running, and is available
        in any of the sequential JSON media types.
      content:
        application/json-seq:
          itemSchema:
            $ref: "#/components/schemas/LogEntry"
          examples:
            JSON-SEQ:
              $ref: "#/components/examples/LogJSONSeq"
        application/jsonl:
          itemSchema:
            $ref: "#/components/schemas/LogEntry"
          examples:
            JSONL:
              $ref: "#/components/examples/LogJSONPerLine"
        application/x-ndjson:
          itemSchema:
            $ref: "#/components/schemas/LogEntry"
          examples:
            NDJSON:
              $ref: "#/components/examples/LogJSONPerLine"
    LogExcerpt:
      description: |
        A response consisting of no more than 100 log records,
        generally as a result of a query of the historical log,
        available in any of the sequential JSON media types.
      content:
        application/json-seq:
          schema:
            $ref: "#/components/schemas/Log"
          examples:
            JSON-SEQ:
              $ref: "#/components/examples/LogJSONSeq"
        application/jsonl:
          schema:
            $ref: "#/components/schemas/Log"
          examples:
            JSONL:
              $ref: "#/components/examples/LogJSONPerLine"
        application/x-ndjson:
          schema:
            $ref: "#/components/schemas/Log"
          examples:
            NDJSON:
              $ref: "#/components/examples/LogJSONPerLine"

我们的 application/json-seq 示例必须放在外部文档中，因为它同时使用换行符和不可打印的记录分隔符（0x1E），该字符无法在 YAML 块文本中转义：

0x1E{
  "timestamp": "1985-04-12T23:20:50.52Z",
  "level": 1,
  "message": "Hi!"
}
0x1E{
  "timestamp": "1985-04-12T23:20:51.37Z",
  "level": 1,
  "message": "Bye!"
}

在此示例中，假设在 Special Considerations for Server-Sent Events 节中提供的通用事件 schema 可通过 #/components/schemas/Event 访问：

description: A request body to add a stream of typed data.
required: true
content:
  text/event-stream:
    itemSchema:
      $ref: "#/components/schemas/Event"
      required: [event]
      oneOf:
      - properties:
          event:
            const: addString
      - properties:
          event:
            const: addInt64
          data:
            $comment: |
              Since the `data` field is a string,
              we need a format to signal that it
              should be handled as a 64-bit integer.
            format: int64
      - properties:
          event:
            const: addJson
          data:
            $comment: |
              These content fields indicate
              that the string value should
              be parsed and validated as a
              JSON document (since JSON is not
              a binary format, `contentEncoding`
              is not needed)
            contentMediaType: application/json
            contentSchema:
              type: object
              required: [foo]
              properties:
                foo:
                  type: integer

下面的 text/event-stream 文档是上述示例的一个有效请求体示例：

event: addString
data: This data is formatted
data: across two lines
retry: 5

event: addInt64
data: 1234.5678
unknownField: this is ignored

: This is a comment
event: addJSON
data: {"foo": 42}

为更清楚地展示该流如何处理，下面是等效的 JSON Lines 文档，显示数值与 JSON 数据如何作为字符串处理，以及未知字段与注释如何被忽略且不会传入 schema 验证：

{"event": "addString", "data": "This data is formatted\nacross two lines", "retry": 5}
{"event": "addInt64", "data": "1234.5678"}
{"event": "addJSON", "data": "{\"foo\": 42}"}

这些字段 MAY 可与下节所定义的 RFC6570 风格序列化字段一并使用或单独使用。

该对象 MAY 可通过 Specification Extensions 进行扩展。

contentType 的默认值如下，其中 n/a 在 contentEncoding 列中表示 contentEncoding 的存在或值与该情况无关。 本表基于 Encoding Object 所应用的值，参见 Encoding Usage and Restrictions。 注意在 Encoding By Name 情况下，对于类型为 "array" 的属性，这一值是数组项；对于其它类型则是整个值。因此本表中 array 行仅适用于在按名称编码时位于顶层数组内部的数组值。

如何处理 null 类型的 type 值取决于 null 值的序列化方式。 若 null 值被完全省略，则 contentType 无关紧要。 有关数据类型转换选项的讨论，请参阅 Appendix B。

当对 multipart/form-data 使用 RFC6570 风格序列化时，MUST NOT 应用 URI 百分号编码，且 allowReserved 的值无影响。 另见 Appendix C: Using RFC6570 Implementations 以获取额外指导。

注意：至少存在 style、explode 或 allowReserved 中的任一显式值，相当于在 Parameter Objects 中使用 schema 且 in: "query"。 若这三者都缺失，则等同于使用 content，但媒体类型由 contentType 指定，而非通过 Media Type Object 指定。

当不存在 encoding 字段时，序列化策略基于 Encoding Object 的默认值：

requestBody:
  content:
    application/x-www-form-urlencoded:
      schema:
        type: object
        properties:
          id:
            type: string
            format: uuid
          address:
            type: object
            properties: {}

在此示例中，考虑一个 id 为 f81d4fae-7dec-11d0-a765-00a0c91e6bf6 且美国式地址（含 ZIP+4）如下：

{
  "streetAddress": "123 Example Dr.",
  "city": "Somewhere",
  "state": "CA",
  "zip": "99999+1234"
}

假设采用最紧凑的 JSON 表示（去除不必要的空白），我们期望看到如下请求体，其中空格字符被替换为 +，并且 +、"、:、,、{ 与 } 分别被百分号编码为 %2B、%22、%3A、%2C、%7B 与 %7D：

id=f81d4fae-7dec-11d0-a765-00a0c91e6bf6&address=%7B%22streetAddress%22%3A%22123+Example+Dr.%22%2C%22city%22%3A%22Somewhere%22%2C%22state%22%3A%22CA%22%2C%22zip%22%3A%2299999%2B1234%22%7D

注意根据 Encoding Object 的默认行为，id 关键字被视为 text/plain 并按原样序列化。 若将其视为 application/json，则序列化值将是包含引号的 JSON 字符串，而引号会被百分号编码为 %22。

下面示例展示将 id 参数（不含 address）作为 application/json 而不是 text/plain 序列化，然后按 [WHATWG-URL] 的 form-urlencoded 规则编码：

id=%22f81d4fae-7dec-11d0-a765-00a0c91e6bf6%22

注意 application/x-www-form-urlencoded 是文本格式，任何二进制数据都需要进行 base64 编码：

requestBody:
  content:
    application/x-www-form-urlencoded:
      schema:
        type: object
        properties:
          name:
            type: string
          icon:
            # The default content type with `contentEncoding` present
            # is `application/octet-stream`, so we need to set the correct
            # image media type(s) in the Encoding Object.
            type: string
            contentEncoding: base64url
  encoding:
    icon:
      contentType: image/png, image/jpeg

假设 name 为 example，且 icon 为一个实心红色的 2x2 像素 PNG，则会产生如下请求体：

name=example&icon=iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAIAAAD91JpzAAAABGdBTUEAALGPC_xhBQAAADhlWElmTU0AKgAAAAgAAYdpAAQAAAABAAAAGgAAAAAAAqACAAQAAAABAAAAAqADAAQAAAABAAAAAgAAAADO0J6QAAAAEElEQVQIHWP8zwACTGCSAQANHQEDqtPptQAAAABJRU5ErkJggg%3D%3D

注意即使使用“URL safe”的 contentEncoding: base64url，末尾的 = 填充字符仍需进行百分号编码。 一些 base64 解码实现可能根据 [RFC4648] 第 3.2 节 能够在没有填充的情况下处理字符串，但这并不保证，因此保留填充并依赖百分号解码通常更具互操作性。

当为 contentType 提供多个值时，解析仍然直接，因为文档中包含了该部分的实际 Content-Type。

对于编码和序列化，实施应 MUST 提供机制让应用程序指明意图使用的媒体类型。 实现 MAY 选择提供媒体类型嗅探（[SNIFF]）作为替代，但由于该过程固有的安全风险，该方法 MUST NOT 成为默认行为。

对 multipart 字段使用 contentEncoding 等同于指定一个 Encoding Object，其 headers 字段包含一个要求使用 contentEncoding 值的 Content-Transfer-Encoding 的 schema。 若对一个 multipart 字段同时使用了 contentEncoding，且该字段的 Encoding Object 的 headers 中包含了一个不允许来自 contentEncoding 的值的 Content-Transfer-Encoding schema，则序列化和解析的结果为未定义。

注意，如 Working with Binary Data 所述，若 Encoding Object 的 contentType（无论是显式设置还是通过默认规则隐式确定）与 Schema Object 中的 contentMediaType 不一致，则应忽略 contentMediaType。 因此，并且由于 Encoding Object 的 contentType 默认规则未考虑 Schema Object 的 contentMediaType，在 Encoding Object 中使用 contentMediaType NOT RECOMMENDED。

另请注意对于 multipart/form-data，Content-Transfer-Encoding 已被弃用（参见 [RFC7578] 第 4.7 节），因为 HTTP 已支持二进制数据。

有关表单媒体类型的百分号编码问题的详细检查，请参阅 Appendix E。

当不使用 encoding 字段时，编码由 Encoding Object 的默认值决定：

requestBody:
  content:
    multipart/form-data:
      schema:
        type: object
        properties:
          # default content type for a string without `contentEncoding`
          # is `text/plain`
          id:
            type: string
            format: uuid

          # default content type for a schema without `type`
          # is `application/octet-stream`
          profileImage: {}

          # for arrays, the `encoding` field applies the Encoding Object
          # to each item individually and determines the default content type
          # based on the type in the `items` subschema, which in this example
          # is an object, so the default content type for each item is
          # `application/json`
          addresses:
            type: array
            items:
              $ref: '#/components/schemas/Address'

使用 encoding，我们可以为二进制数据设置更具体的类型，或为复杂值设置非 JSON 格式。 我们也可以为每个部分描述其头部：

requestBody:
  content:
    multipart/form-data:
      schema:
        type: object
        properties:
          # No Encoding Object, so use default `text/plain`
          id:
            type: string
            format: uuid

          # Encoding Object overrides the default `application/json` content type
          # for each item in the array with `application/xml; charset=utf-8`
          addresses:
            description: addresses in XML format
            type: array
            items:
              $ref: '#/components/schemas/Address'

          # Encoding Object accepts only PNG or JPEG, and also describes
          # a custom header for just this part in the multipart format
          profileImage: {}

      encoding:
        addresses:
          contentType: application/xml; charset=utf-8
        profileImage:
          contentType: image/png, image/jpeg
          headers:
            X-Rate-Limit-Limit:
              description: The number of allowed requests in the current period
              schema:
                type: integer

根据 [RFC7578] 第 4.3 节，单个表单字段的多个文件通过为每个文件的部分使用相同的名称（在本例中为 file）上传：

requestBody:
  content:
    multipart/form-data:
      schema:
        properties:
          # The property name `file` will be used for all files.
          file:
            type: array
            items: {}

如 Encoding Object 的 contentType 字段文档 中所示，items 的空 schema 表示媒体类型为 application/octet-stream。

一个由 JSON 元数据文档随后跟随该元数据所描述的图像组成的 multipart/mixed 有载荷示例：

multipart/mixed:
  schema:
    type: array
    prefixItems:
    - # default content type for objects
      # is `application/json`
      type: object
      properties:
        author:
          type: string
        created:
          type: string
          format: datetime
        copyright:
          type: string
        license:
          type: string
    - # default content type for a schema without `type`
      # is `application/octet-stream`, which we need
      # to override.
      {}
  prefixEncoding:
  - # Encoding Object defaults are correct for JSON
    {}
  - contentType: image/*

如 [RFC2557] 所述，一组构成网页的资源可以在 multipart/related 有载荷中发送，通过为每个页面定义 Content-Location 头来保留从 text/html 文档到从属资源（脚本、样式表、图像等）的链接。 第一部分被用作根资源（除非使用 RFC2557 建议避免且在本示例中被禁止的 Content-ID），因此我们使用 prefixItems 与 prefixEncoding 来定义其必须是 HTML 资源，然后允许若干种不同类型的资源以任意顺序跟随。

为避免对其 URI 值进行百分号编码，Content-Location 头使用 content: {text/plain: {...}} 定义；详见 Appendix D。

components:
  headers:
    RFC2557NoContentId:
      description: Use Content-Location instead of Content-ID
      schema: false
    RFC2557ContentLocation:
      required: true
      content:
        text/plain:
          schema:
            $comment: Use a full URI (not a relative reference)
            type: string
            format: uri
  requestBodies:
    RFC2557:
      content:
        multipart/related; type=text/html:
          schema:
            prefixItems:
            - type: string
            items:
              anyOf:
              - type: string
              - $comment: To allow binary, this must always pass
          prefixEncoding:
          - contentType: text/html
            headers:
              Content-ID:
                $ref: '#/components/headers/RFC2557NoContentId'
              Content-Location:
                $ref: '#/components/headers/RFC2557ContentLocation'
          itemEncoding:
            contentType: text/css,text/javascript,image/*
            headers:
              Content-ID:
                $ref: '#/components/headers/RFC2557NoContentId'
              Content-Location:
                $ref: '#/components/headers/RFC2557ContentLocation'

本例假设一个设备拍摄大量图片并将其流式传输给调用方。与前例不同，我们在此使用 itemSchema，因为期望每张图片在到达时（或少量批次）被处理，而缓冲整个流将占用过多内存。

multipart/mixed:
  itemSchema:
    $comment: A single data image from the device
  itemEncoding:
    contentType: image/jpg

对于 multipart/byteranges（参见 [RFC9110] 第 14.6 节），需要包含 Content-Range 头：

关于为何使用 content: {text/plain: {...}} 来描述头值的解释，请参见 Appendix D。

multipart/byteranges:
  itemSchema:
    $comment: A single range of bytes from a video
  itemEncoding:
    contentType: video/mp4
    headers:
      Content-Range:
        required: true
        content:
          text/plain:
            schema:
              # The `pattern` regular expression that would
              # be included in practice is omitted for simplicity
              type: string

此示例定义了一个两部分的 multipart/mixed，其中第一部分是一个 JSON 数组，第二部分是一个嵌套的 multipart/mixed 文档。嵌套部分为 XML、纯文本和 PNG 图像。

multipart/mixed:
  schema:
    type: array
    prefixItems:
    - type: array
    - type: array
      prefixItems:
      - type: object
      - type: string
      - {}
  prefixEncoding:
    - {} # Accept the default application/json
    - contentType: multipart/mixed
      prefixEncoding:
      - contentType: application/xml
      - {} # Accept the default text/plain
      - contentType: image/png

value 与简写 example 字段旨在具有与 serializedValue（或 externalValue）相同的语义，但在 JSON（或 JSON 兼容的 YAML）表示与最终序列化形式无差异时提供更方便的语法。当将此语法用于 application/json 或任何 +json 媒体类型时，这些字段实际上等同于 dataValue，因为序列化是平凡的，因此使用它们是安全的。

对于仅包含单个字符串的数据，且序列化目标如 text/plain 保证字符串以不需进一步转义的方式序列化时，这些字段也安全可用。

对于其它序列化目标，“自然地用 JSON 或 YAML 表示”的歧义性，以及先前参数样式示例表中的错误，导致这些字段在非 JSON 目标上的支持与用法存在不一致。因此，在实践中对于非 JSON 目标，value 与简写 example 字段的行为通常由实现定义；OAD 作者 SHOULD 使用其它字段以确保互操作性。

牢记上一节中的注意事项，以及当仅涉及一个 Example Object 时可用简写 example 代替 value 的事实，使用下列指南决定应使用哪一字段。

若要展示一个将如何被 Schema Object 验证的示例：

• 如果意图是将示例随验证用的 schema 一起保留，请使用 Schema Object 的 examples 数组（来自 JSON Schema draft 2020-12）。
  • 仅当需要与 OAS v3.0 或更早版本兼容时，才使用 Schema Object 的单数 example。
• 如果意图是将示例与其序列化形式关联，或希望将示例与 schema 分离，请使用 Example Object 的 dataValue 字段。
  • 仅当需要与 OAS v3.1 或更早版本兼容且该值可“自然地在 JSON 或 YAML 中表示”而无需在验证就绪的值与序列化表示之间进行任何更改（例如百分号编码）时，才使用 Example Object 的 value 字段。

若要展示用于构建 HTTP/1.1 消息的序列化示例：

• 如果序列化能表示为有效的 Unicode 字符串且无需展示确切字符编码，请使用 Example Object 的 serializedValue 字段。
  • 仅当需要与 OAS v3.1 或更早版本兼容时，才使用 value 的字符串形式。
• 对于其它值，或希望将示例与 OpenAPI 文档分离，请使用 Example Object 的 externalValue。

serializedValue 与 externalValue 两个字段都 MUST 展示数据的序列化形式。对于 Media Type Objects，这是一份合适媒体类型的文档，并应用任何 Encoding Object 的效果。对于使用 schema 与 style（而不是 Media Type Object）的 Parameter 与 Header Objects，请参见 Style Examples，了解何为序列化值。

若满足下列任一条件，则序列化可以在 serializedValue 中表示为有效的 Unicode 字符串：

• 该媒体类型支持 charset 参数，并且该参数指示任何 Unicode 编码（UTF-8、UTF-16 等）或上述编码的有效子集（例如 US-ASCII）。
• 该格式（例如 URI 或 HTTP 字段）或基于字符的媒体类型要求或默认使用 Unicode 编码，或其有效子集（如 US-ASCII），且未被 charset 覆盖。
• 该格式为复合格式，且所有部分至少满足上述一项，例如一个包含 application/json（默认 UTF-8）和 application/xml; charset=utf-8 的 multipart/mixed。

在所有这些情况下，将 OAD 的字符集（假定为 JSON 的互操作字符集 UTF-8）先转换为 Unicode 代码点，再转换为实际序列化字符集的过程是可定义的。

对于 externalValue，若未显式声明字符集且格式或媒体类型规范也未确定字符集，实施者 SHOULD 假设为 UTF-8。

工具实现 MAY 选择自动验证兼容性，并在不兼容时拒绝示例值。对于以 schema 就绪数据形式存在的示例，验证是直接且明确的。

对于序列化的示例，某些格式允许相同数据的多种有效表示形式（包括在 附录 B 中提到的场景）。在某些情况下，解析序列化示例并验证所得数据可以消除歧义，但在少数情况下解析本身也存在歧义。因此，OAD 作者应注意对某些序列化示例的验证在性质上属于尽力而为的特性。

在编写 YAML 时，dataValue 可以使用 JSON 语法（如 noRating 示例所示），但并非必须。虽然此示例对于 JSON 展示了 dataValue 与 serializedValue 的行为（在 withRating 示例中），但在大多数情况下只需要数据形式即可。

content:
  application/json:
    schema:
      type: object
      required:
      - author
      - title
      properties:
        author:
          type: string
        title:
          type: string
        rating:
          type: number
          minimum: 1
          maximum: 5
          multipleOf: 0.5
    examples:
      noRating:
        summary: A not-yet-rated work
        dataValue:
          author: A. Writer
          title: The Newest Book
      withRating:
        summary: A work with an average rating of 4.5 stars
        dataValue:
          author: A. Writer
          title: An Older Book
          rating: 4.5
        serializedValue: |
          {
            "author": "A. Writer",
            "title": "An Older Book",
            "rating": 4.5
          }

完整二进制数据使用 externalValue 展示：

content:
  image/png:
    schema: {}
    examples:
      Red:
        externalValue: ./examples/2-by-2-red-pixels.png

由于布尔值序列化无统一标准（参见 附录 B），本示例使用 dataValue 与 serializedValue 来展示该参数的布尔序列化方式：

name: flag
in: query
required: true
schema:
  type: boolean
examples:
  "true":
    dataValue: true
    serializedValue: flag=true
  "false":
    dataValue: false
    serializedValue: flag=false

由于 operationId 在 Operation Object 中是可选字段，因此引用在某些情况下 MAY 通过 URI 引用与 operationRef 一起使用来代替。 注意以下两个示例都通过 Paths Object 可以标识操作，以确保该操作的路径模板是无歧义的。

一个相对 URI 引用的 operationRef：

links:
  UserRepositories:
    # returns array of '#/components/schemas/repository'
    operationRef: '#/paths/~12.0~1repositories~1%7Busername%7D/get'
    parameters:
      username: $response.body#/username

一个非相对 URI 的 operationRef：

links:
  UserRepositories:
    # returns array of '#/components/schemas/repository'
    operationRef: https://na2.gigantic-server.com/#/paths/~12.0~1repositories~1%7Busername%7D/get
    parameters:
      username: $response.body#/username

注意在使用 operationRef 时，在 URI 片段中使用 JSON Pointer 时需要对斜线进行转义（使用 ~1），并且需要将 { 与 } 分别 URL 编码为 %7B 与 %7D。 上述示例中未转义、经百分号解码后的路径模板为 /2.0/repositories/{username}。

运行时表达式会保留被引用值的类型。 可以通过用花括号 {} 将表达式包围的方式将表达式嵌入到字符串值中。

这些字段 MAY 与 content 或 schema 一起使用。

example 与 examples 字段互斥；有关验证要求的指导，请参见 Working with Examples。

该对象 MAY 通过 Specification Extensions 扩展。

对于简单场景，schema 与 style 可以描述 header 的结构与语法。

在使用 schema 序列化 header 时，MUST NOT 应用 URI 百分号编码；若使用会自动应用编码的 RFC6570 实现，则在使用前 MUST 撤销该编码。 实现 MUST 原样传递 header 值，而不要尝试自动为 header 值添加引用，因为不同 header 的引用规则差异过大；有关引用与转义的指导，请参见 Appendix D。

另见 Appendix C: Using RFC6570-Based Serialization 以获取更多指导。

对于更复杂的情形，content 字段可定义 header 的媒体类型和 schema，并提供其使用示例。

如 JSON Schema Validation 规范 所定义，数据类型可以有一个可选的修饰关键字：format。如该规范所述，默认情况下 format 被视为非验证注释；是否验证 format 取决于具体实现。

OpenAPI Initiative 还托管了一个 Format Registry，用于记录由 OAS 用户和其它规范定义的格式。对任何注册格式的支持完全是 可选 的，对一个注册格式的支持并不意味着对其他格式的支持。

未伴随 format 关键字的类型遵循 JSON Schema 中的类型定义。若工具不识别某个特定 format，则可 MAY 回退仅按 type 进行处理，仿佛未指定 format。针对 JSON Schema 验证，每个格式应指定其适用的 JSON 数据类型集合。在此注册表中，这些类型在“JSON Data Type”列中列出。

OAS 定义的格式如下：

如在 数据类型 一节所述，type: number 与 type: integer 在数据模型中都被视为数字。

JSON 序列化的数据几乎等同于数据形式，因为 JSON Schema 的数据模型 与 JSON 表示几乎一致。序列化的 UTF-8 JSON 字符串 {"when": "1985-04-12T23:20:50.52"} 表示一个具有单个数据字段的对象，该字段名为 when，其字符串值为 1985-04-12T23:20:50.52。

具体的应用形式超出本规范范围，但可通过下面的模式示例说明我们的 JSON 实例：

type: object
properties:
  when:
    type: string
    format: date-time

一些应用可能会将该字符串在任意编程语言中保持为字符串，而其他应用可能会注意到 format 并将其作为 Python 的 datetime.datetime 实例，或 Java 的 java.time.ZonedDateTime。本规范仅要求数据根据模式有效，且诸如 format 之类作为注释的关键字按 JSON Schema 规范可用。

非 JSON 的序列化形式可能与其对应的数据形式有很大不同，且可能需要多个步骤才能解析。

延续我们的 “when” 示例，如果我们将对象序列化为 application/x-www-form-urlencoded，它将以 ASCII 字符串的形式出现：when=1985-04-12T23%3A20%3A50.52。该示例仍然易于使用，因为都是字符串数据，且与 JSON 的唯一区别是 URI 百分号编码和分隔语法（使用 = 替代 JSON 标点和引号）。

然而，许多非 JSON 的文本格式可能很复杂，必须检查相应的模式以将文本正确解析为可供模式使用的数据结构。将数据序列化为此类格式需要检查经过模式验证的数据，或执行相同的模式检查。

在检查模式时，给定一个起始模式，实施者 MUST 检查该模式以及通过仅跟随 $ref 和 allOf 关键字可到达的所有模式。这些模式保证适用于任何实例。在搜索模式以查找 type 时，如果 type 关键字的值是类型列表，并且序列化值可以成功解析为列表中多个类型之一，且没有其它可发现的 type 关键字来消除歧义，则行为由实现定义。未包含 type 的 Schema Objects MUST 被视为允许所有类型，无论其它关键字如何存在（例如 maximum 适用于数字，但并不要求实例必须为数字）。

实现 MAY 检查子模式或其它关键字（如 oneOf 或 $dynamicRef） 的可能引用目标，但 MUST NOT 试图解决歧义。例如，如果实现选择检查 anyOf，下列模式：

anyOf:
- type: number
  minimum: 0
- type: number
  maximum: 100

明确地指出了数字类型，但下列模式：

anyOf:
- type: number
- maximum: 100

则不明确，因为第二个子模式允许所有类型。

鉴于这些对模式搜索的有限要求，能够访问已验证数据的序列化器 MUST 在可能的情况下检查实际数据；不处理运行时数据（例如代码生成器）或无法访问已验证数据的实现 MUST 回退到模式检查。

还应记住，在 JSON Schema 中适用于特定类型的关键字（例如 pattern 适用于字符串，minimum 适用于数字）并不要求或暗示数据实际上会是该类型。

作为这些过程的示例，给定以下 OpenAPI 组件：

components:
  requestBodies:
    Form:
      content:
        application/x-www-form-urlencoded:
          schema:
            $ref: "#/components/schemas/FormData"
          encoding:
            extra:
              contentType: application/xml
  schemas:
    FormData:
      type: object
      properties:
        code:
          allOf:
          - type: [string, number]
            pattern: "1"
            minimum: 0
          - type: string
            pattern: "2"
        count:
          type: integer
        extra:
          type: object

以及下面这个要解析为数据形式的请求体：

code=1234&count=42&extra=%3Cinfo%3Eabc%3C/info%3E

我们必须首先在模式中搜索 properties 或其它定义属性的关键字，然后将每个属性的模式作为起点去搜索该属性的 type 关键字，过程如下（具体顺序由实现定义）：

• #/components/requestBodies/Form/content/application~1x-www-form-urlencoded/schema（起始模式，仅包含 $ref）
• #/components/schemas/FormData（跟随 $ref，发现 properties）
• #/components/schemas/FormData/properties/code（code 属性的起始模式）
• #/components/schemas/FormData/properties/code/allOf/0（跟随 allOf，发现 type: [string, number]）
• #/components/schemas/FormData/properties/code/allOf/1（跟随 allOf，发现 type: string）
• #/components/schemas/FormData/properties/count（count 属性的起始模式，发现 type: integer）
• #/components/schemas/FormData/properties/extra（extra 属性的起始模式，发现 type: object）

注意对 code 我们起初找到一个模糊的 type，但随后又找到了另一个 type 关键字，使两种可能性中只有一种有效。

通过这种检查，我们确定 code 是一个看起来像数字的字符串，而 count 需要在模式验证之前被解析为数字。此外，extra 字符串实际上是一个表示含有 info 属性的对象的 XML 序列化。这意味着该序列化的数据形式等价于下面的 JSON 对象：

{
  "code": "1234",
  "count": 42
  "extra": {
    "info": "abc"
  }
}

序列化该对象还需要将属性与 Encoding Objects 关联，并可能需要检查以确定 contentType 字段的默认值。如果无法获取到已验证的数据，则模式检查过程与解析时相同。

在该示例中，code 和 count 都是原始类型，且未出现在 encoding 字段中，因此按纯文本序列化。然而，extra 字段是一个对象，默认会被序列化为 JSON，但 encoding 字段中对 extra 的条目告知要改为以 XML 形式序列化。

OAS 可描述 原始 或 编码 的二进制数据。

• 原始二进制（raw binary）：用于允许未编码的二进制数据场景，例如将二进制有效负载作为整个 HTTP 消息体发送，或作为允许二进制部分的 multipart/* 有效负载的一部分。
• 编码二进制（encoded binary）：用于二进制数据嵌入到仅文本格式中，例如 application/json 或 application/x-www-form-urlencoded（无论是作为消息体还是 URL 查询字符串的一部分）。

在下面展示如何为二进制数据使用 Schema Object 关键字的表中，我们以 image/png 作为示例二进制媒体类型。任何二进制媒体类型（包括 application/octet-stream）均可表示二进制内容。

注意：由 contentEncoding 指示的编码会增大数据大小以便表示为 7 位 ASCII 文本，这与 HTTP 的 Content-Encoding 头（标识消息体是否以及如何被压缩）无关，且该头在本节描述的所有内容序列化完成后应用。由于 HTTP 允许未编码的二进制消息体，因此没有标准的 HTTP 头用于指示整个消息体使用 base64 或类似编码。

使用 contentEncoding 为 base64url 可确保在查询字符串和类型为 application/x-www-form-urlencoded 的消息体中所需的 URL 编码不需对已编码的二进制数据再做额外编码。

若媒体类型已设置，则 contentMediaType 关键字是冗余的，具体场景包括：

• 作为 Media Type Object 的键名
• 在 Encoding Object 的 contentType 字段中

如果 Schema Object 将由非 OAS 感知的 JSON Schema 实现处理，即便冗余也可能有用以包含 contentMediaType。但若 contentMediaType 与相关的 Media Type Object 或 Encoding Object 冲突，则 contentMediaType SHALL 被忽略。

有关流式二进制有效负载的指导，请参见 完整内容 与 流式内容。

当使用默认的 format-annotation 词汇表时，format 关键字，以及 contentMediaType、contentEncoding 和 contentSchema 关键字对数据定义约束，但被视为注释而非直接验证。扩展验证是强制执行这些约束的一种方式，且这些约束 MAY 被这样执行。

readOnly 与 writeOnly 关键字是注释，因为 JSON Schema 无法知道它正在验证的数据将如何被使用。对这些关键字的验证 MAY 通过检查注释、读/写方向以及（若相关）字段的当前值来完成。JSON Schema Validation Draft 2020-12 第 9.4 节 定义了这些关键字的期望行为，包括资源（称为“拥有权威”） MAY 忽略 readOnly 字段或将其视为错误。

同时为必需且只读的字段是一个示例，说明在 PUT 请求中忽略 readOnly: true 约束可能是有益的，特别是在值未被更改的情况下。这允许在 GET 时正确要求该字段，同时仍然在 PUT 时使用相同的表示与模式。即便只读字段不是必需的，移除它们对客户端来说也是繁重的，尤其当 JSON 数据复杂或深度嵌套时。

注意 readOnly 的行为与本规范的 3.0 版本存在差异。

OpenAPI 规范允许使用 JSON Schema 的 allOf 关键字来组合和扩展模型定义，从而实现模型组合。allOf 接受一组对象定义的数组，这些定义独立验证，但一起组成单个对象。

尽管组合提供了模型的可扩展性，但并不意味着模型之间存在继承层次结构。

JSON Schema 还提供 anyOf 和 oneOf 关键字，分别允许定义多个模式，其中至少一个或恰好一个必须有效。与 allOf 相同，这些模式也是独立验证的。这些关键字可用于描述多态，在该场景中单个字段可以接受多种类型的值。

OpenAPI 规范通过添加 discriminator 字段（其值为 Discriminator Object）扩展了 JSON Schema 对多态的支持。使用时，Discriminator Object 指示用于提示哪个 anyOf 或 oneOf 模式应验证模型结构的属性名称。判定属性 MAY 被定义为必需或可选，但若将其定义为可选，则 Discriminator Object MUST 包含 defaultMapping 字段，以指定在判定属性不存在时期望使用哪个 anyOf 或 oneOf 中的模式，或在 allOf 中引用当前模式的哪个模式。

定义继承实例的判定属性值有两种方式：

• 使用模式名称。
• 通过覆盖属性值 来覆盖模式名称。如果存在新的值，则优先于模式名称。

实现 SHOULD 支持使用 JSON Schema 的动态引用功能来定义通用或模板数据结构：

• $dynamicAnchor 标识一组可能的模式（包括默认的占位模式），$dynamicRef 可解析到这些模式之一。
• $dynamicRef 按 JSON Schema 规范，从模式入口点到引用路径上遇到的第一个匹配 $dynamicAnchor 进行解析。

示例包含在下方的 Schema Object 示例 部分，并且在 Learn OpenAPI 网站的 “动态引用” 页面上有更多信息。

Schema Object 的 enum 关键字不允许为各个值关联描述或其它信息。

实现 MAY 支持识别一种模式：将 oneOf 或 anyOf 中的每个子模式写为包含 const 关键字及诸如 title 或 description 等注释，从而作为带有附加信息的枚举类型。此模式在 JSON Schema 所要求行为之外的具体行为由实现定义。

xml 字段在将 JSON 定义转换为 XML 时允许额外定义。XML Object 包含有关可用选项的更多信息。

type: string
format: email

type: object
required:
  - name
properties:
  name:
    type: string
  address:
    $ref: '#/components/schemas/Address'
  age:
    type: integer
    format: int32
    minimum: 0

用于简单的字符串到字符串的映射：

type: object
additionalProperties:
  type: string

用于字符串到模型的映射：

type: object
additionalProperties:
  $ref: '#/components/schemas/ComplexModel'

oneOf:
  - const: RGB
    title: Red, Green, Blue
    description: Specify colors with the red, green, and blue additive color model
  - const: CMYK
    title: Cyan, Magenta, Yellow, Black
    description: Specify colors with the cyan, magenta, yellow, and black subtractive color model

type: object
properties:
  id:
    type: integer
    format: int64
  name:
    type: string
required:
  - name
examples:
  - name: Puma
    id: 1

components:
  schemas:
    ErrorModel:
      type: object
      required:
        - message
        - code
      properties:
        message:
          type: string
        code:
          type: integer
          minimum: 100
          maximum: 600
    ExtendedErrorModel:
      allOf:
        - $ref: '#/components/schemas/ErrorModel'
        - type: object
          required:
            - rootCause
          properties:
            rootCause:
              type: string

下面示例描述了一个 Pet 模型，该模型可表示猫或狗，区分依据为 petType 属性。每种宠物类型在基础 Pet 模型之外有额外属性。若实例缺少 petType 属性，或该属性值既不是 cat 也不是 dog，则该实例无效。

components:
  schemas:
    Pet:
      type: object
      properties:
        name:
          type: string
      required:
        - name
        - petType
      oneOf:
        - $ref: '#/components/schemas/Cat'
        - $ref: '#/components/schemas/Dog'
    Cat:
      description: A pet cat
      type: object
      properties:
        petType:
          const: 'cat'
        huntingSkill:
          type: string
          description: The measured skill for hunting
          enum:
            - clueless
            - lazy
            - adventurous
            - aggressive
      required:
        - huntingSkill
    Dog:
      description: A pet dog
      type: object
      properties:
        petType:
          const: 'dog'
        packSize:
          type: integer
          format: int32
          description: the size of the pack the dog is from
          default: 0
          minimum: 0
      required:
        - packSize

下面的示例在上一节示例的基础上，为 Pet 模式添加了一个 Discriminator Object。注意 Discriminator Object 仅为 API 使用者提供提示，并不会改变模式的验证结果。

components:
  schemas:
    Pet:
      type: object
      discriminator:
        propertyName: petType
        mapping:
          cat: '#/components/schemas/Cat'
          dog: '#/components/schemas/Dog'
      properties:
        name:
          type: string
      required:
        - name
        - petType
      oneOf:
        - $ref: '#/components/schemas/Cat'
        - $ref: '#/components/schemas/Dog'
    Cat:
      description: A pet cat
      type: object
      properties:
        petType:
          const: 'cat'
        huntingSkill:
          type: string
          description: The measured skill for hunting
          enum:
            - clueless
            - lazy
            - adventurous
            - aggressive
      required:
        - huntingSkill
    Dog:
      description: A pet dog
      type: object
      properties:
        petType:
          const: 'dog'
        packSize:
          type: integer
          format: int32
          description: the size of the pack the dog is from
          default: 0
          minimum: 0
      required:
        - petType
        - packSize

也可以使用 allOf 描述多态模型。以下示例使用 allOf 和 Discriminator Object 来描述一个多态的 Pet 模型。

components:
  schemas:
    Pet:
      type: object
      discriminator:
        propertyName: petType
      properties:
        name:
          type: string
        petType:
          type: string
      required:
        - name
        - petType
    Cat: # "Cat" will be used as the discriminating value
      description: A representation of a cat
      allOf:
        - $ref: '#/components/schemas/Pet'
        - type: object
          properties:
            huntingSkill:
              type: string
              description: The measured skill for hunting
              enum:
                - clueless
                - lazy
                - adventurous
                - aggressive
          required:
            - huntingSkill
    Dog: # "Dog" will be used as the discriminating value
      description: A representation of a dog
      allOf:
        - $ref: '#/components/schemas/Pet'
        - type: object
          properties:
            packSize:
              type: integer
              format: int32
              description: the size of the pack the dog is from
              default: 0
              minimum: 0
          required:
            - packSize

components:
  schemas:
    genericArrayComponent:
      $id: fully_generic_array
      type: array
      items:
        $dynamicRef: '#generic-array'
      $defs:
        allowAll:
          $dynamicAnchor: generic-array
    numberArray:
      $id: array_of_numbers
      $ref: fully_generic_array
      $defs:
        numbersOnly:
          $dynamicAnchor: generic-array
          type: number
    stringArray:
      $id: array_of_strings
      $ref: fully_generic_array
      $defs:
        stringsOnly:
          $dynamicAnchor: generic-array
          type: string
    objWithTypedArray:
      $id: obj_with_typed_array
      type: object
      required:
      - dataType
      - data
      properties:
        dataType:
          enum:
          - string
          - number
      oneOf:
      - properties:
          dataType:
            const: string
          data:
            $ref: array_of_strings
      - properties:
          dataType:
            const: number
          data:
            $ref: array_of_numbers