diff --git a/versions/3.1.0.md b/versions/3.1.0.md
index b890a4d22f..09ecb3bea3 100644
--- a/versions/3.1.0.md
+++ b/versions/3.1.0.md
@@ -147,12 +147,14 @@ Primitive data types in the OAS are based on the types supported by the [JSON Sc
Note that `integer` as a type is also supported and is defined as a JSON number without a fraction or exponent part.
Models are defined using the [Schema Object](#schemaObject), which is a superset of JSON Schema Specification Draft 2019-09.
-Primitives have an optional modifier property: `format`.
-OAS uses several known formats to define in fine detail the data type being used.
+Primitives have an optional modifier property: `format`, which is defined by JSON Schema.
+OAS uses several known additional formats to define in fine detail the data type being used.
However, to support documentation needs, the `format` property is an open `string`-valued property, and can have any value.
-Formats such as `"email"`, `"uuid"`, and so on, MAY be used even though undefined by this specification.
+Additional formats MAY be used even though undefined by either JSON Schema or this specification.
Types that are not accompanied by a `format` property follow the type definition in the JSON Schema. Tools that do not recognize a specific `format` MAY default back to the `type` alone, as if the `format` is not specified.
+Note that by default, JSON Schema validators will not attempt to validate the `format` keyword. https://json-schema.org/draft/2019-09/release-notes.html#format-vocabulary
+
The formats defined by the OAS are:
[`type`](#dataTypes) | [`format`](#dataTypeFormat) | Comments
@@ -161,15 +163,8 @@ The formats defined by the OAS are:
`integer` | `int64` | signed 64 bits (a.k.a long)
`number` | `float` | |
`number` | `double` | |
-`string` | | |
-`string` | `byte` | base64 encoded characters
-`string` | `binary` | any sequence of octets
-`boolean` | | |
-`string` | `date` | As defined by `full-date` - [RFC3339](https://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14)
-`string` | `date-time` | As defined by `date-time` - [RFC3339](https://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14)
`string` | `password` | A hint to UIs to obscure input.
-
### Rich Text Formatting
Throughout the specification `description` fields are noted as supporting CommonMark markdown formatting.
Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by [CommonMark 0.27](https://spec.commonmark.org/0.27/). Tooling MAY choose to ignore some CommonMark features to address security concerns.
@@ -1447,20 +1442,35 @@ 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. Specifically:
+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.
+
+Examples:
+
+Content transferred in binary (octet-stream) SHOULD omit `schema`, as no JSON Schema type is suitable:
```yaml
-# content transferred with base64 encoding
-schema:
- type: string
- format: base64
+# a PNG image as a binary file:
+content:
+ image/png: {}
```
```yaml
-# content transferred in binary (octet-stream):
-schema:
- type: string
- format: binary
+# an arbitrary binary file:
+content:
+ application/octet-stream: {}
+```
+
+Binary content transferred with base64 encoding:
+
+```yaml
+content:
+ image/png:
+ schema:
+ type: string
+ contentEncoding: base64
```
These examples apply to either input payloads of file uploads or response payloads.
@@ -1470,11 +1480,7 @@ A `requestBody` for submitting a file in a `POST` operation may look like the fo
```yaml
requestBody:
content:
- application/octet-stream:
- schema:
- # a binary file of any type
- type: string
- format: binary
+ application/octet-stream: {}
```
In addition, specific media types MAY be specified:
@@ -1484,14 +1490,8 @@ In addition, specific media types MAY be specified:
requestBody:
content:
# a binary file of type png or jpeg
- 'image/jpeg':
- schema:
- type: string
- format: binary
- 'image/png':
- schema:
- type: string
- format: binary
+ image/jpeg: {}
+ image/png: {}
```
To upload multiple files, a `multipart` media type MUST be used:
@@ -1506,9 +1506,7 @@ requestBody:
file:
type: array
items:
- type: string
- format: binary
-
+ contentMediaType: application/octet-stream
```
##### Support for x-www-form-urlencoded Request Bodies
@@ -1546,8 +1544,10 @@ 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 `format: binary` or `format: base64` (aka a file object), the default Content-Type is `application/octet-stream`
+* 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.
Examples:
@@ -1566,9 +1566,8 @@ requestBody:
type: object
properties: {}
profileImage:
- # default Content-Type for string/binary is `application/octet-stream`
- type: string
- format: binary
+ # Content-Type with contentMediaType is the contentMediaType (image/png here)
+ contentMediaType: image/png
children:
# default Content-Type for arrays is based on the `inner` type (text/plain here)
type: array
@@ -1578,7 +1577,8 @@ requestBody:
# default Content-Type for arrays is based on the `inner` type (object shown, so `application/json` in this example)
type: array
items:
- type: '#/components/schemas/Address'
+ type: object
+ $ref: '#/components/schemas/Address'
```
An `encoding` attribute is introduced to give you control over the serialization of parts of `multipart` request bodies. This attribute is _only_ applicable to `multipart` and `application/x-www-form-urlencoded` request bodies.
@@ -1590,7 +1590,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: for `string` with `format` being `binary` – `application/octet-stream`; 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: 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.
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.
@@ -1621,9 +1621,8 @@ requestBody:
type: object
properties: {}
profileImage:
- # default is application/octet-stream, need to declare an image type only!
type: string
- format: binary
+ contentMediaType: image/jpeg
encoding:
historyMetadata:
# require XML Content-Type in utf-8 encoding