[oas3] base64 vs byte

[jwalton]

The spec makes numerous references to {format: base64} (here and here for example). However this format is not defined in either the wright-00 JSON-schema spec, nor in the OAS3 defined data types.

[handrews]

@jwalton format is extensible and OpenAPI defines numerous extensions including base64, although per #1310 and #1544, base64 should be handled differently in the long run with newer versions of JSON Schema.

But as far as the JSON Schema spec goes, what OpenAPI is doing with formats is valid.

[jwalton]

Oh, it's valid, it's just that the defined data types section defines {format: 'byte'} as "base64 encoded characters". It seems weird to define our own special name for base64 and then not use it. :P

[darrelmiller]

As per @tsc meeting we are going make a decision between have a byte format or a base64 but not both. Some historical spelunking will be done by @webron before making the call.

[jwalton]

FWIW, my vote is for base64. It much more clearly conveys the intent.

[ralfhandl]

I also prefer base64

[handrews]

In OAS 3.1, this can now be handled properly from the JSON Schema perspective. Specifically:

type: string
contentEncoding: base64

is a base64-endcode string (where base64 is per RFC 4648). You can use any RFC 4648 or RFC 2045 encoding, so base64url or quoted-printable are also valid.

If you are encoding a specific media type, such as a PNG file:

type: string
contentEncoding: base64
contentMediaType: image/png

Note that the content* keywords are informational, and are not validated during JSON Schema validation.

For binary transfer, use

type: string
contentMediaType: application/octet-stream

or some other media type.

---

we should probably deprecate "format": "base64" and "format": "binary" in OAS 3.1 although I don't feel strongly about it. Well... I have lots of strong feelings about format but that's a rant for another time.

[handrews]

For OAS 3.1.0, since we're now dropping the byte/base64 format in favor of contentEncoding, this is no longer a concern.

If there's going to be an OAS 3.0.4, then this should be clarified with a PR to the appropriate branch.

[handrews]

For OAS 3.1.0 this is resolved with #2200.

@OAI/tsc is there likely to be a 3.0.4 where we would fix the examples of base64 vs byte? If not, we can close this.

[MikeRalphson]

My appetite for a 3.0.4 is... limited.

[MikeRalphson]

As above, I believe we can close this.