Fix, clarify, and simplify content type schemas

versions/3.1.0.md

@@ -1433,14 +1433,15 @@ 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).
+In contrast with the 2.0 specification, `file` input/output content in OpenAPI is described with the same semantics as any other schema type.
 
-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 3.0 specification, the `format` keyword has no effect on the content-encoding of the schema. JSON Schema offers a `contentEncoding` keyword, which may be used to specify the `Content-Encoding` for the schema. The `contentEncoding` 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). 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.
+
+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.
 
 Examples:
 
-Content transferred in binary (octet-stream) SHOULD omit `schema`, as no JSON Schema type is suitable:
+Content transferred in binary (octet-stream) MAY omit `schema`:
 
 ```yaml
 # a PNG image as a binary file:
@@ -1461,9 +1462,12 @@ content:
  image/png:
  schema:
  type: string
+ contentMediaType: image/png
  contentEncoding: base64
 ```
 
+Note that the `Content-Type` remains `image/png`, describing the semantics of the payload. The JSON Schema `type` and `contentEncoding` fields explain that the payload is transferred as text. The JSON Schema `contentMediaType` is technically redundant, but can be used by JSON Schema tools that may not be aware of the OpenAPI context.
+
 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 +1500,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
@@ -1536,9 +1541,8 @@ When passing in `multipart` types, boundaries MAY be used to separate sections o
 * 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
 
-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.
+Per the JSON Schema specification, `contentMediaType` without `contentEncoding` present is treated as if `contentEncoding: identity` were present. While useful for embedding text documents such as `text/html` into JSON strings, it is not useful for a `multipart/form-data` part, as it just causes the document to be treated as `text/plain` instead of its actual media type. Use the Encoding Object without `contentMediaType` if no `contentEncoding` is required.
 
 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: base64
  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: for `object` - `application/json`;  for `array` – the default is defined based on the inner type; for all other cases the default is `application/octet-stream`. 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