在 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

格式：二进制不再有效吗？我读 In contrast with the 3.0 specification, the format keyword has no effect on the content-encoding of the schema. JSON Schema offers a contentEncoding keyword, which may be used to specify the Content-Encoding for the schema. 所以听起来应该在 3.1.0 中使用 contentEncoding: binary 代替 format: binary contentEncoding 是否仅适用于 type: string 模式？

openapi 3.0.2

json 架构 2020-12！

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

Answer 1

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

format: binary 有限制。具体来说，这个来自 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

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

有点混乱，因为编码对象与 JSON Schema 关键字功能有点重叠，这是 OAS 和 JSON Schema 独立尝试解决相同问题的结果。 OAS 3.1 指定如果使用编码对象，则 JSON 架构的 contentMediaType 应被忽略。但是如果 JSON Schema 打算在 OpenAPI 内部和外部使用，您可能仍然会看到两者。

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

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

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

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

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

In a json schema, what is the correct way to describe a default, example, or enum value for a binary schema?

json

jsonschema

openapi

openapi 3.1.0

openapi 3.0.2

json 架构 2020-12！