openapi 3.1 - changes for binary data

[chrisradek]

Open API 3.1 uses different fields to describe binary data than Open API 3.0.

Open API 3.0

Open API 3.0: working with binary data
Open API 3.0 uses 2 formats to work with binary data using the string type:

• binary for unencoded binary data
• byte for binary data embedded in a text-only format (e.g. application/json).
  Note: byte represents base64 encoded characters.

Open API 3.1

Open API 3.1: working with binary data
Open API 3.1 ignores format for binary data.

For unencoded binary data, the type is also omitted and only contentMediaType is required (even this can be omitted in some cases)

For encoded data, format is effectively replaced with contentEncoding which explicitly states how the content within the text is encoded (e.g. base64).

Example table taken from above spec link:

Keyword	Unencoded	Encoded
type	omit	string
contentMediaType	application/octet-stream	application/octet-stream
contentEncoding	omit	base64 or base64url

For multipart media types, it's recommended not to specify the contentMediaType since there will be either an implied or explicit contentType that takes precedence. contentEncoding is still relevant.
Open API 3.1: Table showing default contentType based on type/contentEncoding pairs
More details around file uploads can be found here: Open API 3.1: considerations for file uploads

Other considerations

Open API 3.1 allows specifying contentEncodings other than base64/base64url. The contentEncoding and contentMediaType JsonSchema decorators should support customizing these values.

[markcowl]

est: 5