Fix, clarify, and simplify content type schemas

This fixes OAI#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.

versions/3.1.0.md

@@ -1433,10 +1433,7 @@ application/json:
 
 ##### Considerations for File Uploads
 
-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 use the `contentEncoding` JSON Schema keyword rather than the `format` keyword.  This keyword supports all encodings defined in [RFC4648](https://tools.ietf.org/html/rfc4648), including "base64" and "base64url", as well as "quoted-printable" from [RFC2045](https://tools.ietf.org/html/rfc2045#section-6.7).
-
-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.
+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).
 
 Examples:
 
@@ -1458,12 +1455,15 @@ Binary content transferred with base64 encoding:
 
 ```yaml
 content:
-    image/png:
+    text/plain:
         schema:
             type: string
+            contentMediaType: image/png
             contentEncoding: base64
 ```
 
+Note that the `Content-Type` is `text/plain`, since from an HTTP perspectve, base64-encoded data is simply text.  The `contentMediaType` and `contentEncoding` fields inform the application how to encode and decode the resource from and to its actual media type.
+
 These examples apply to either input payloads of file uploads or response payloads.
 
 A `requestBody` for submitting a file in a `POST` operation may look like the following example:
@@ -1496,10 +1496,11 @@ requestBody:
           # The property name 'file' will be used for all files.
           file:
             type: array
-            items:
-              contentMediaType: application/octet-stream
+            items: {}
 ```
 
+As seen in the section on `multipart/form-data` below, the empty schema for `items` indicates a media type of `application/octet-stream`.
+
 ##### Support for x-www-form-urlencoded Request Bodies
 
 To submit content using form url encoding via [RFC1866](https://tools.ietf.org/html/rfc1866), the following
@@ -1531,14 +1532,17 @@ It is common to use `multipart/form-data` as a `Content-Type` when transferring
 
 In a `multipart/form-data` request body, each schema property, or each element of a schema array property, takes a section in the payload with an internal header as defined by [RFC 7578](https://tools.ietf.org/html/rfc7578). The serialization strategy for each property of a `multipart/form-data` request body can be specified in an associated [`Encoding Object`](#encodingObject).
 
+As with HTTP request/response bodies in general, the schema of each part applies to the resource separately from any automatic HTTP encoding headers for that part.  The headers can be described in the Encoding Object.
+
 When passing in `multipart` types, boundaries MAY be used to separate sections of the content being transferred — thus, the following default `Content-Type`s are defined for `multipart`:
 
 * If the property is a primitive, or an array of primitive values, the default Content-Type is `text/plain`
 * If the property is complex, or an array of complex values, the default Content-Type is `application/json`
-* If the property is a `type: string` with a `contentEncoding`, the default Content-Type is `application/octet-stream`
-* If the JSON Schema keyword `contentMediaType` is used and no Encoding Object is present, then the Content-Type is that which is specified by `contentMediaType`, however if an Encoding Object is present, then `contentMediaType` SHALL be ignored
+* If the property is a `type: string` with a `contentMediaType`, the default Content-Type is `text/plain`, and the media type of the embedded resource is specified in `contentMediaType`, with any encoding specified in `contentEncoding`
 
-As with non-multipart request or response bodies, when using `contentMediaType` to specify a binary Content-Type without also using `contentEncoding`, the JSON Schema `type` keyword is omitted.
+In the last case, `multipart/form-data` libraries see the part as text, and the application encodes and decodes the underlying media type specified in `contentMediaType` to and from `text/plain` using the encoding specified in `contentEncoding`.
+
+As specified by JSON Schema, `contentMediaType` and `contentEncoding` are ignored unless the instance (meaning the multipart part) is a string in the JSON Schema data model.  As with non-multipart request or response bodies, when a part has a binary `Content-Type`, the JSON Schema `type` keyword is omitted in any corresponding Schema Object.
 
 Examples:
 
@@ -1557,15 +1561,17 @@ requestBody:
             type: object
             properties: {}
           profileImage:
-            # Content-Type with contentMediaType is the contentMediaType (image/png here)
+            # Content-Type for application-level encoded resource is `text/plain`
+            type: string
             contentMediaType: image/png
+            contentEncoding: base64url
           children:
-            # default Content-Type for arrays is based on the `inner` type (text/plain here)
+            # default Content-Type for arrays is based on the **inner** type (`text/plain` here)
             type: array
             items:
               type: string
           addresses:
-            # default Content-Type for arrays is based on the `inner` type (object shown, so `application/json` in this example)
+            # default Content-Type for arrays is based on the **inner** type (object shown, so `application/json` in this example)
             type: array
             items:
               type: object
@@ -1581,7 +1587,7 @@ A single encoding definition applied to a single schema property.
 ##### Fixed Fields
 Field Name | Type | Description
 ---|:---:|---
-<a name="encodingContentType"></a>contentType | `string` | The Content-Type for encoding a specific property. Default value depends on the property type: when `type` is absent and `contentMediaType` is present - the value of `contentMediaType`; when both `type` and `contentMediaType` are absent - `application/octet-stream`; for `string` with a `contentEncoding` - `application/octet-string`; for other primitive types – `text/plain`; for `object` - `application/json`; for `array` – the default is defined based on the inner type. The value can be a specific media type (e.g. `application/json`), a wildcard media type (e.g. `image/*`), or a comma-separated list of the two types.
+<a name="encodingContentType"></a>contentType | `string` | The Content-Type for encoding a specific property. Default value depends on the property type: when `type` is absent - `application/octet-stream`; for primitive types including `string` with a `contentEncoding` - `text/plain`; for `object` - `application/json`; when `type` is `string` with a `contentMediaType`, the default Content-Type is `text/plain`, and the media type of the embedded resource is specified in `contentMediaType`, with any encoding specified in `contentEncoding`; for `array` – the default is defined based on the inner type. The value can be a specific media type (e.g. `application/json`), a wildcard media type (e.g. `image/*`), or a comma-separated list of the two types.
 <a name="encodingHeaders"></a>headers | Map[`string`, [Header Object](#headerObject) \| [Reference Object](#referenceObject)] | A map allowing additional information to be provided as headers, for example `Content-Disposition`.  `Content-Type` is described separately and SHALL be ignored in this section. This property SHALL be ignored if the request body media type is not a `multipart`.
 <a name="encodingStyle"></a>style | `string` | Describes how a specific property value will be serialized depending on its type.  See [Parameter Object](#parameterObject) for details on the [`style`](#parameterStyle) property. The behavior follows the same values as `query` parameters, including default values. This property SHALL be ignored if the request body media type is not `application/x-www-form-urlencoded` or `multipart/form-data`. If a value is explicitly defined, then the value of [`contentType`](#encodingContentType) (implicit or explicit) SHALL be ignored.
 <a name="encodingExplode"></a>explode | `boolean` | When this is true, property values of type `array` or `object` generate separate parameters for each value of the array, or key-value-pair of the map.  For other types of properties this property has no effect. When [`style`](#encodingStyle) is `form`, the default value is `true`. For all other styles, the default value is `false`. This property SHALL be ignored if the request body media type is not `application/x-www-form-urlencoded` or `multipart/form-data`. If a value is explicitly defined, then the value of [`contentType`](#encodingContentType) (implicit or explicit) SHALL be ignored.
@@ -1594,7 +1600,7 @@ This object MAY be extended with [Specification Extensions](#specificationExtens
 ```yaml
 requestBody:
   content:
-    multipart/mixed:
+    multipart/form-data:
       schema:
         type: object
         properties:
@@ -1611,9 +1617,7 @@ requestBody:
             description: metadata in XML format
             type: object
             properties: {}
-          profileImage:
-            type: string
-            contentMediaType: image/jpeg
+          profileImage: {}
       encoding:
         historyMetadata:
           # require XML Content-Type in utf-8 encoding