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

user_4175822 0
Viewed 924

In a schema in the 3 below contexts, what is the correct way to describe a default, example, or enum value for a binary schema?

type: string
format: binary

In openapi contexts, the above schema can be used as payload definition when sending multipart/form-data or application/octet-stream content media types.

Does the answer differ if one is using openapi(3.0.2 vs 3.1.0) vs json schema? I have read the below specs but they lack examples for these use cases.

openapi 3.1.0

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

Is format: binary no longer valid? I read 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. So it sounds like contentEncoding: binary should be used in 3.1.0 in place of format: binary Does contentEncoding only apply to type: string schemas?

openapi 3.0.2

json schema 2020-12!

openapi jsonschema json
1 Answers

format: binary had limitations when you needed to specify both the media type and the encoding. Specifically, this example from 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

Note how it says that you "need to declare an image type only" because format: binary just indicates application/octet-stream (the universal media type that encompasses everything).

In OAS 3.1, the corresponding example is follows, sadly with an error- the comment about application-level encoded resources being text/plain is incorrect. I seem to have missed that when I put this example in, my apologies- it is correct elsewhere in the spec:

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

These examples are slightly different as the OAS 3.1 shows a base64 encoding, which would have been format: byte. The exact OAS 3.1 analogue would be:

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

without a type (because binary data, while valid in a multipart form submission which is what this is from, is not part of the JSON type system).

It is slightly confusing because the Encoding Object overlaps the JSON Schema keyword functionality a bit, which is the result of OAS and JSON Schema independently trying to solve the same problem. OAS 3.1 specifies that if the Encoding Object is used, then JSON Schema's contentMediaType SHALL be ignored. But you might still see both if the JSON Schema is intended for use both inside of and outside of OpenAPI.

JSON Schema's examples, enum, and const keywords take literal values. As base64-encoded binaries are simply strings, they can be used with these keywords in the normal way.

However, unencoded binary cannot be embedded in JSON or YAML as a literal value. The JSON Schema keywords were primarily designed for the JSON data model.

However, OpenAPI's Example Object (which is outside of the schema object) allows for an external reference to other media types. There are not currently any such external reference keywords for JSON Schema, but the could be added as an extension vocabulary, meaning it is not necessary to wait for a new draft of JSON Schema or a new version of the OpenAPI Specification to do this.

examples and default are annotation keywords, and the default extension keyword behavior is to be an annotation, so there's not much you'd need to do to add them. const and enum would be a bit more challenging as JSON Schema does not expect to load other media types for validation. But enum has never supported unencoded binary data in OAS, nor did example or default in the OAS 3.0 Schema Object, so these are not new restrictions.

user_158454640
Related