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

Question

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

type: string
format: binary

在openapi上下文中，当发送多部分/表单数据或应用程序/八位字节流内容媒体类型时，上述模式可用作有效负载定义。

如果使用openapi（3.0.2 vs 3.1.0）vs json模式，答案是否不同？我已经阅读了下面的规范，但它们缺少这些用例的示例。

https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#considerations-用于文件上载

格式：二进制不再有效吗？与3.0规范相比，format关键字对模式的内容编码没有影响。JSON模式提供了一个contentEncoding关键字，可用于指定模式的内容编码 听起来像是3.1.0中应该使用二进制编码来代替格式：二进制编码。内容编码只适用于类型：字符串模式吗？

• https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.2.md#considerations-用于文件上传
• https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.2.md#data-类型

• 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

请注意，它如何表示“只需要声明图像类型”，因为格式：二进制仅表示应用程序/八位字节流（包含所有内容的通用媒体类型）。

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

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编码，它将是格式：byte。确切的OAS 3.1模拟将是：

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

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

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

JSON模式的示例、枚举和常量关键字采用文字值。由于base64编码的二进制文件只是字符串，因此它们可以正常地与这些关键字一起使用。

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

然而，OpenAPI的示例对象（位于模式对象之外）允许对其他媒体类型进行外部引用。目前，JSON模式没有任何此类外部参考关键字，但可以将添加为扩展词汇表，这意味着无需等待JSON模式的新草案或OpenAPI规范的新版本来完成此操作。

示例和默认值都是注释关键字，默认扩展关键字行为是注释，因此添加它们不需要做太多工作<代码>常量和枚举将更具挑战性，因为JSON模式预计不会加载其他媒体类型进行验证。但是，枚举在OAS中从未支持未编码的二进制数据，OAS 3.0模式对象中的示例或默认值也不支持，因此这些不是新的限制。