conflicting order of operations when applying Content-Encoding and Content-Type headers

[karenetheridge]

The specification describes how to handle requests/responses with both a Content-Type and Content-Encoding header:

" JSON Schema offers a contentEncoding keyword, which may be used to specify the Content-Encoding for the schema. ... The encoding specified by the contentEncoding keyword is independent of an encoding specified by the Content-Type header in the request or response or metadata of a multipart body – when both are present, the encoding specified in the contentEncoding is applied first and then the encoding specified in the Content-Type header."
--- https://spec.openapis.org/oas/v3.1.0#considerations-for-file-uploads

(emphasis mine)

However, this ordering is backwards with how an openapi validator would operate: the contentEncoding keyword is hidden inside the schema, at a lower level than the media-type property.

The way around this would be for the validator to peek inside the schema to see if there is a contentEncoding keyword at the top level, and use it to decode the content first before then using the media-type decoder. That's pretty ugly IMO; schemas ought to be opaque. It would be better for this data to be brought up into the media-type object itself, or simply automatically decode the content according to the Content-Encoding header before applying the media-type in the Content-Type header (is it really a desired feature that the openapi document must specify the Content-Encoding that is used? what if multiple different encodings are supported, e.g. gzip compression and brotli compression - how would that be indicated?)

In practice, how is a desired content encoding indicated in a document in order to enable proper validation of the request/response body content? I didn't find any hints on the Swagger site.

[handrews]

@karenetheridge There are some confusing typos in this area (really I need to go back over the whole thing, it was changed close to the end of the 3.1 process and we went through several revisions trying to get it right). See #2476 and #2477 for more info that might help.

Note that:

• JSON Schema contentEncoding is about string-encoding binary data (e.g. quoted-printable, base64, base64url, hex, etc.)
• HTTP Content-Encoding is about managing the size of the payload (e.g. gzip, compress, etc.)

Somewhere in the text, there's a stray Content-Type that should be one of the encodings, but I don't recall which one.

[handrews]

We should probably clarify this in a patch release. And also find that stray Content-Type error I mentioned above.

[karenetheridge]

I've just run into this again, as I'm trying to describe and validate requests with Content-Encoding: gzip and Content-Type: application/json. Obviously we need to gunzip the body first before we can start to access its json-encoded content.

[handrews]

PRs merged for 3.1.1 and 3.2.0 - closing!