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