diff --git a/versions/3.1.0.md b/versions/3.1.0.md
index dbdecaa4ea..b98a559b20 100644
--- a/versions/3.1.0.md
+++ b/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
---|:---:|---
-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.
+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.
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`.
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.
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