json - 在 json 模式中，描述二进制模式的默认值、示例或枚举值的正确方法是什么？

Question

在以下 3 个上下文中的架构中，描述二进制架构的默认值、示例或枚举值的正确方法是什么？

type: string
format: binary

在 openapi 上下文中，在发送 multipart/form-data 或 application/octet-stream 内容媒体类型时，上述模式可以用作有效负载定义。

如果使用 openapi(3.0.2 vs 3.1.0) 与 json 架构，答案是否有所不同？ 我已阅读以下规范，但缺少这些用例的示例。

openapi 3.1.0

https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#considerations-for-file-uploads

格式:二进制不再有效吗？ 我读 与 3.0 规范相比，format 关键字对模式的内容编码没有影响。 JSON Schema 提供了一个 contentEncoding 关键字，可用于指定 schema 的 Content-Encoding。 所以听起来应该在 3.1.0 中使用 contentEncoding:binary 代替 format:binary contentEncoding 是否仅适用于 type: string 模式？

openapi 3.0.2

• https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.2.md#considerations-for-file-uploads
• https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.2.md#data-types

json 架构 2020-12!

• https://json-schema.org/understanding-json-schema/reference/non_json_data.html

Answer 1

当您需要指定媒体类型和编码时，

格式:二进制有局限性。具体来说，这个来自 OAS 3.0.2 的示例:

requestBody:
  content:
    multipart/form-data:
      schema:
        type: object
        properties:
          profileImage:
            # default is application/octet-stream, need to declare an image type only!
            type: string
            format: binary

注意它是如何说你“只需要声明一个图像类型”，因为format:binary只是表示application/octet-stream(通用媒体类型，包含一切)。

在 OAS 3.1 中，相应的示例如下，遗憾的是有一个错误 - 关于应用程序级编码资源为 text/plain 的注释不正确。我似乎错过了，当我把这个例子放进去时，我很抱歉——它在规范的其他地方是正确的:

requestBody:
  content:
    multipart/form-data:
      schema:
        type: object
        properties:
          profileImage:
            # Content-Type for application-level encoded resource is `text/plain`
            type: string
            contentMediaType: image/png
            contentEncoding: base64

这些示例略有不同，因为 OAS 3.1 显示的是 base64 编码，其格式为 format: byte。确切的 OAS 3.1 类似物是:

requestBody:
  content:
    multipart/form-data:
      schema:
        type: object
        properties:
          profileImage:
            contentMediaType: image/png

没有类型(因为二进制数据虽然在多部分表单提交中有效，但它不是 JSON 类型系统的一部分)。

这有点令人困惑，因为编码对象与 JSON Schema 关键字功能有一点重叠，这是 OAS 和 JSON Schema 独立尝试解决同一问题的结果。 OAS 3.1 规定，如果使用编码对象，则 JSON 模式的 contentMediaType 应被忽略。但如果 JSON 架构旨在在 OpenAPI 内部和外部使用，您可能仍然会看到这两种情况。

---

JSON Schema 的 examples、enum 和 const 关键字采用文字值。由于 Base64 编码的二进制文件只是字符串，因此它们可以以正常方式与这些关键字一起使用。

但是，未编码二进制文件无法作为文字值嵌入到 JSON 或 YAML 中。 JSON Schema 关键字主要是为 JSON 数据模型设计的。

但是，OpenAPI 的 Example Object (位于模式对象之外)允许对其他媒体类型的外部引用。目前 JSON Schema 没有任何此类外部引用关键字，但可以将其添加为扩展词汇表，这意味着无需等待 JSON Schema 的新草案或 OpenAPI 规范的新版本来执行此操作。

examples 和 default 是注释关键字，默认扩展关键字行为是注释，因此您无需执行太多操作即可添加它们。 const 和 enum 会更具挑战性，因为 JSON Schema 不希望加载其他媒体类型进行验证。但是enum在OAS中从来不支持未编码的二进制数据，在OAS 3.0 Schema Object中example或default也不支持，所以这些并不是新的限制.