Fix, clarify, and simplify content type schemas

[handrews]

This fixes #2349, which caught that an encoded PNG image
is encoded into a text media type.

In the process I realized some other errors, and simplified things.

• HTTP Content-Type is always handled by OAS
  • Media Type Object key in most cases
  • Encoding object (possibly inferred from schema) in multipart/form-data
• HTTP-level Content-Encoding is always handled by the OAS Header Object
• JSON Schema "content*" is used for embedding one media type into another
  • the encoded resource is of media type text/plain
  • "contentMediaType" is the embedded media type after decoding
  • "contentEncoding" is how to encode/decode binary to/from text

This removes any chance of "contentMediaType" conflicting with
the Media Type Object key or with contentType in the Encoding Object,
as they now always do different things.

Likewise, the HTTP Content-Encoding header (with values like
gzip, deflate, etc.) does different things than "contentEncoding"
(which has values like base64, base64url, quoted-printable, etc.).

The deprecated part header Content-Transfer-Encoding is likewise
handled in the Encoding Object, but is probably never used.

[darrelmiller]

I believe this should stay as image/png to convey the semantics of the HTTP payload.

[handrews]

@darrelmiller I don't remember why I did that, but I'll take your word for it. I am having a difficult time finding a reference (which I was hoping would remind me why I thought this was correct). But yeah, the JSON Schema provides all of the processing information and the logical output is image/png so that makes sense. And of course the text that asserted this should indeed be removed. Lemme do that right now...

[darrelmiller]

Believe this text should be removed.

[handrews]

@darrelmiller I have changed this paragraph to explain why there is a redundancy, but if you feel the new text is more confusing than helpful, I'm happy to remove it.

[mkistler]

I thought that we agreed in the 1/28 TSC meeting that when type is string the default Content-Type should be application/octet-stream.

[mkistler]

I've read through this PR and it left some questions unanswered in my mind.

I think the basic issue to be addressed is: Now that full JSON Schema is allowed in OpenAPI 3.1, what does it mean for the JSON Schema contentMediaType and contentEncoding keywords to be present in a request body schema?

I think the 3.1.0 spec already covers contentMediaType with this statement:

JSON Schema also offers a contentMediaType keyword. However, when the media type is already specified by the Media Type Object's key, or by the contentType field of an Encoding Object, the contentMediaType keyword SHALL be ignored if present.

Though that statement is buried in the section titled "Considerations for File Uploads" and should be moved to the general section on the Media type object.

Regarding contentEncoding, I don't think this is properly addressed for the "root" schema of a request body content entry. In particular, what I think should be said is:

• If the “root” schema of a request body content entry contains a contentEncoding, then:
  • If no Content-encoding header parameter is defined for the operation, the allowed encodings for the content entry are defined by the contentEncoding in the schema
  • If a Content-encoding header parameter is defined, the allowed encodings for the content entry are defined by the intersection of the allowable values for the Content-encoding header and the contentEncoding in the schema

This is just my take but I suppose other approaches could be taken, such as simply ignoring Content-encoding for a "root" schema of a request body content entry, but whatever is decided, I think it should be clearly stated in the spec.

[darrelmiller]

Content-Encoding header overrides the JSON schema contentEncoding.

[mkistler]

Here is my proposed rewording to clarify the priority of Content-Encoding headers (in various places) and the JSON Schema contentEncoding:

Suggested change

	In contrast with the 2.0 specification, `file` input/output content in OpenAPI is described with the same semantics as any other schema type. In contrast with the 3.0 specification, such schemas either omit the `type` (in place of `format: binary`), or use `contentMediaType` and `contentEncoding` with `type: string`. The `contentEncoding` keyword supports all encodings defined in [RFC4648](https://tools.ietf.org/html/rfc4648), including "base64" (which replaces `format: byte`) and "base64url", as well as "quoted-printable" from [RFC2045](https://tools.ietf.org/html/rfc2045#section-6.7).
	In contrast with the 2.0 specification, `file` input/output content in OpenAPI is described with the same semantics as any other schema type.
	In contrast with the 3.0 specification, the `format` keyword has no effect on the content-encoding of the schema. The Content-Encoding for the schema can be specified explicitly with the `Content-Encoding` parameter of the operation, for schemas in request bodies, or in a `Content-Encoding` header in the `headers` of the response, for response schemas, or in a `Content-Encoding` header in the `headers` of an Encoding object associated with a request or response body property. JSON Schema also offers a `contentEncoding` keyword, which may be used to specify the `Content-Encoding` for the schema, but `contentEncoding` SHALL be ignored if a `Content-Encoding` header is defined. The `contentEncoding` keyword supports all encodings defined in [RFC4648](https://tools.ietf.org/html/rfc4648), including "base64" (which replaces `format: byte`) and "base64url", as well as "quoted-printable" from [RFC2045](https://tools.ietf.org/html/rfc2045#section-6.7). When not explicitly specified, the content-encoding
	JSON Schema also offers a `contentMediaType` keyword. However, when the media type is already specified by the Media Type Object's key, or by the `contentType` field of an [Encoding Object](#encodingObject), the `contentMediaType` keyword SHALL be ignored if present.

[handrews]

@mkistler the Content-Encoding HTTP header and contentEncoding JSON Schema keyword are unrelated. The HTTP header is for things like gzip that the HTTP client and server will encode/decode automatically. The JSON Schema keyword is for when both HTTP and the media type think that something is text, but the application needs to be informed that some specific piece of text needs to be encoded/decoded in a particular way.

[handrews]

You could in fact have a gzipped payload that includes a base64-encoded PNG file. That would use both the header and the keyword.

[mkistler]

@handrews I struggling to understand this all. Do you mean to say that contentEncoding keyword has no effect whatsoever on the value that should/will be passed in the Content-Encoding header? If that is the case then it certainly will confuse some readers (like me 😄).

In the example you give, how would this look in the API doc? Maybe:

  /v1/photos:
    post:
      parameters:
        - name: Content-Encoding
           in: header
           schema:
             type: string
             enum:
               - gzip
        requestBody:
          content:
            image/png:
              schema:
                contentEncoding: base64

And the http request would specify:

• Content-type: image/png
• Content-encoding: gzip
• a gzipped, base64-encoded image/png

Is that right?

If I've got this right, then I think you are saying that both the encoding specified in the Content-Encoding header and the encoding specified in the contentEncoding keyword are applied to the request body (or whichever element they pertain to).

If that's right, I'll make a stab at rewording my suggestion to describe this.

[handrews]

@mkistler yeah this is the challenge of combining multiple standards that were made in different contexts at different times.

If you go back to MIME, there is a Content-Transfer-Encoding header, which is where values such as base64 from RFC 4648 (or its predecessors) are used. Perhaps we should have used mediaEncoding or something like that in JSON Schema (the naming of that keyword has a slightly convoluted history that partially predates me), but we didn't. I might have only learned about HTTP Content-Encoding while researching this PR, come to think of it.

I believe that what you have for the HTTP request is correct. At this stage with the modifications y'all have made recently, I'm a little unclear on where we ended up on type being absent vs "type": "string", but what you have (with type absent) is what I would have written. And is compatible with the latest JSON Schema draft which notes that an application MAY apply a JSON Schema to other media types, including binary media types, and notes that many keywords have no sensible meaning with binary types.