From 2c30d42b427fab25a99c308c195374dfc4ff8f76 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Wed, 13 Nov 2019 13:37:36 -0800 Subject: [PATCH 01/10] Update "format" and "content*" for new JSON Schema This removes OAS formats and examples that are now superfluous as they are part of the 2019-09 JSON Schema draft. Similarly it deprecates the "byte" and "binary" formats in favor of JSON Schema's "contentEncoding" and "contentMediaType" keywords, and updates various related exapmles and other guidance. It also removes confusingly blank rows in the OAS format table. --- versions/3.1.0.md | 49 +++++++++++++++++++++++++++-------------------- 1 file changed, 28 insertions(+), 21 deletions(-) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index b890a4d22f..89f8d610b9 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -147,10 +147,10 @@ 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. The formats defined by the OAS are: @@ -161,14 +161,14 @@ 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. +`string` | `byte` | base64 encoded characters **Deprecated** +`string` | `binary` | any sequence of octets **Deprecated** +Use of `byte` or `binary` is discouraged, and later versions of this specification may remove them from this list. They SHOULD be replaced with the JSON Schema keywords `contentEncoding` or `contentMediaType` as follows: + +* replace `"format": "byte"` with `"contentEncoding": "base64"` or `"contentEncoding": "base64url"` +* replace `"format": "binary"` with `"contentMediaType": "application/octet-stream"` or an appropriate specific media type ### Rich Text Formatting Throughout the specification `description` fields are noted as supporting CommonMark markdown formatting. @@ -1453,14 +1453,14 @@ In contrast with the 2.0 specification, `file` input/output content in OpenAPI i # content transferred with base64 encoding schema: type: string - format: base64 + contentEncoding: base64 ``` ```yaml # content transferred in binary (octet-stream): schema: type: string - format: binary + contentMediaType: application/octet-stream ``` These examples apply to either input payloads of file uploads or response payloads. @@ -1474,7 +1474,7 @@ requestBody: schema: # a binary file of any type type: string - format: binary + contentMediaType: application/octet-stream ``` In addition, specific media types MAY be specified: @@ -1487,11 +1487,11 @@ requestBody: 'image/jpeg': schema: type: string - format: binary + contentMediaType: image/jpeg 'image/png': schema: type: string - format: binary + contentMediaType: image/png ``` To upload multiple files, a `multipart` media type MUST be used: @@ -1507,7 +1507,7 @@ requestBody: type: array items: type: string - format: binary + contentMediaType: application/octet-stream ``` @@ -1546,7 +1546,9 @@ 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 `contentMediaType`, the Content-Type is the value from `contentMediaType` +* If the property is a `type: string` with a `contentEncoding` of `base64` or `base64url`, but does _not_ have a `contentMediaType`, the default Content-Type is `application/octet-stream` +* **Deprecated:** 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` Examples: @@ -1566,9 +1568,9 @@ requestBody: type: object properties: {} profileImage: - # default Content-Type for string/binary is `application/octet-stream` + # Content-Type for string/contentMediaType is the contentMediaType (image/png here) type: string - format: binary + contentMediaType: image/png children: # default Content-Type for arrays is based on the `inner` type (text/plain here) type: array @@ -1590,7 +1592,13 @@ 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: + +* for `type` with a `contentMediaType`, the default value is the value from `contentMediaType` +* 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 +* **Deprecated:** for `string` with `format` being `binary` – `application/octet-stream` + 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 +1629,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 From bee097486732ad6ddc2d72035935c6680d803e05 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Wed, 8 Apr 2020 14:01:30 -0700 Subject: [PATCH 02/10] "format" is an annotation --- versions/3.1.0.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index 89f8d610b9..260f85f983 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -153,6 +153,8 @@ However, to support documentation needs, the `format` property is an open `strin 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 MUST NOT attempt to validate the `format` keyword. It is primarily treated as an annotation that informs applications of the intended nature of the data. For historical reasons, it is possible to configure JSON Schema validators to validate "format", but this is not consistently implemented and SHOULD NOT be relied upon in any environment where an unknown validator or unknown validator configuration might be used. + The formats defined by the OAS are: [`type`](#dataTypes) | [`format`](#dataTypeFormat) | Comments From 9135acd7cfe0743c85d187416cf7020dd2d22d4a Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Thu, 9 Apr 2020 09:39:20 -0700 Subject: [PATCH 03/10] Fix broken table, type, in Encoding Object Broke some things while updating for "content*" --- versions/3.1.0.md | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index 260f85f983..a6eb2eb4b3 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -1594,13 +1594,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 `type` with a `contentMediaType`, the default value is the value from `contentMediaType` -* 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 -* **Deprecated:** for `string` with `format` being `binary` – `application/octet-stream` - +contentType | `string` | The Content-Type for encoding a specific property. Default value depends on the property type: for `string` with a `contentMediaType` - `contentMediaType`; 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; **Deprecated:** for `string` with `format` being `binary` – `application/octet-stream`. 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. From 25d808efff86ca6baaec136e51c8fa8c0e9b2f9d Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Thu, 9 Apr 2020 10:18:59 -0700 Subject: [PATCH 04/10] Fix format of `format` Backticks, not double quotes. --- versions/3.1.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index a6eb2eb4b3..9177bb9911 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -153,7 +153,7 @@ However, to support documentation needs, the `format` property is an open `strin 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 MUST NOT attempt to validate the `format` keyword. It is primarily treated as an annotation that informs applications of the intended nature of the data. For historical reasons, it is possible to configure JSON Schema validators to validate "format", but this is not consistently implemented and SHOULD NOT be relied upon in any environment where an unknown validator or unknown validator configuration might be used. +Note that by default, JSON Schema validators MUST NOT attempt to validate the `format` keyword. It is primarily treated as an annotation that informs applications of the intended nature of the data. For historical reasons, it is possible to configure JSON Schema validators to validate `format`, but this is not consistently implemented and SHOULD NOT be relied upon in any environment where an unknown validator or unknown validator configuration might be used. The formats defined by the OAS are: From dcf9878c541d9c207e11d8aca90943e3bef75420 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Thu, 14 May 2020 18:30:50 -0700 Subject: [PATCH 05/10] Remove unneeded detail on "format" This was just duplicating info from the JSON Schema spec. Co-authored-by: Darrel --- versions/3.1.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index 9177bb9911..0ad07bbb04 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -153,7 +153,7 @@ However, to support documentation needs, the `format` property is an open `strin 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 MUST NOT attempt to validate the `format` keyword. It is primarily treated as an annotation that informs applications of the intended nature of the data. For historical reasons, it is possible to configure JSON Schema validators to validate `format`, but this is not consistently implemented and SHOULD NOT be relied upon in any environment where an unknown validator or unknown validator configuration might be used. +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: From 7f49b70963ac6000ca232e454cbbe9a16f3ed5ea Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Thu, 14 May 2020 18:35:34 -0700 Subject: [PATCH 06/10] Remove "byte" and "binary" formats altogether. Instead of just deprecating. The "content*" keywords now cover these use cases. --- versions/3.1.0.md | 10 +--------- 1 file changed, 1 insertion(+), 9 deletions(-) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index 0ad07bbb04..e7c8a0907e 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -164,13 +164,6 @@ The formats defined by the OAS are: `number` | `float` | | `number` | `double` | | `string` | `password` | A hint to UIs to obscure input. -`string` | `byte` | base64 encoded characters **Deprecated** -`string` | `binary` | any sequence of octets **Deprecated** - -Use of `byte` or `binary` is discouraged, and later versions of this specification may remove them from this list. They SHOULD be replaced with the JSON Schema keywords `contentEncoding` or `contentMediaType` as follows: - -* replace `"format": "byte"` with `"contentEncoding": "base64"` or `"contentEncoding": "base64url"` -* replace `"format": "binary"` with `"contentMediaType": "application/octet-stream"` or an appropriate specific media type ### Rich Text Formatting Throughout the specification `description` fields are noted as supporting CommonMark markdown formatting. @@ -1550,7 +1543,6 @@ When passing in `multipart` types, boundaries MAY be used to separate sections o * 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 `contentMediaType`, the Content-Type is the value from `contentMediaType` * If the property is a `type: string` with a `contentEncoding` of `base64` or `base64url`, but does _not_ have a `contentMediaType`, the default Content-Type is `application/octet-stream` -* **Deprecated:** 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` Examples: @@ -1594,7 +1586,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 a `contentMediaType` - `contentMediaType`; 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; **Deprecated:** for `string` with `format` being `binary` – `application/octet-stream`. +contentType | `string` | The Content-Type for encoding a specific property. Default value depends on the property type: for `string` with a `contentMediaType` - `contentMediaType`; 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. From e673a5b3bdc9cfeb1181799e9e5cc819c193fab1 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Fri, 15 May 2020 23:47:57 -0700 Subject: [PATCH 07/10] Harmonize JSON Schema content* + Media Type Object Includes harmonizing with the Encoding Object. In general, OpenAPI objects set the media type, although there is a case for `contentMediaType` with multipart/form-data. Otherwise, `contentEncoding` replaces the now-removed custom formats. A possibly controversial change is to indicate unencoded binary data by omitting `type` (or omitting the schema altogether), as binary data does not conform to JSON string requirements. This could still be done with `type: string` if that is preferred. It's going to be a bit weird either way. I can add wording in the next JSON Schema draft to clarify whichever approach makes more sense. --- versions/3.1.0.md | 64 +++++++++++++++++++++++++---------------------- 1 file changed, 34 insertions(+), 30 deletions(-) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index e7c8a0907e..1efc4bfe87 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -1442,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 - contentEncoding: base64 +# a PNG image as a binary file: +content: + image/png: {} ``` ```yaml -# content transferred in binary (octet-stream): -schema: - type: string - contentMediaType: application/octet-stream +# an arbitray binary file: +content: + application/octet-stream: {} +``` + +Binary content transferred wiht base64 encoding: + +```yaml +content: + image/png: + schema: + type: string + contentEncoding: base64 ``` These examples apply to either input payloads of file uploads or response payloads. @@ -1465,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 - contentMediaType: application/octet-stream + application/octet-stream: {} ``` In addition, specific media types MAY be specified: @@ -1479,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 - contentMediaType: image/jpeg - 'image/png': - schema: - type: string - contentMediaType: image/png + image/jpeg: {} + image/png: {} ``` To upload multiple files, a `multipart` media type MUST be used: @@ -1500,10 +1505,8 @@ requestBody: # The property name 'file' will be used for all files. file: type: array - items: - type: string + items: {} contentMediaType: application/octet-stream - ``` ##### Support for x-www-form-urlencoded Request Bodies @@ -1541,9 +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 a `contentMediaType`, the Content-Type is the value from `contentMediaType` -* If the property is a `type: string` with a `contentEncoding` of `base64` or `base64url`, but does _not_ have a `contentMediaType`, the default Content-Type is `application/octet-stream` +* If the property is a `type: string` with a `contentEncoding` of `base64` or `base64url`, 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: @@ -1562,8 +1566,7 @@ requestBody: type: object properties: {} profileImage: - # Content-Type for string/contentMediaType is the contentMediaType (image/png here) - type: string + # 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) @@ -1574,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. From 3c0a0679928786376eae2d13462c0c7de2cecee3 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Thu, 28 May 2020 09:12:47 -0700 Subject: [PATCH 08/10] Fix typos from review --- versions/3.1.0.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index 1efc4bfe87..18ab1d0326 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -1458,12 +1458,12 @@ content: ``` ```yaml -# an arbitray binary file: +# an arbitrary binary file: content: application/octet-stream: {} ``` -Binary content transferred wiht base64 encoding: +Binary content transferred with base64 encoding: ```yaml content: From 8105a915bec4c7e95451fa29abee9ed1f2aa7e3f Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Thu, 28 May 2020 09:14:19 -0700 Subject: [PATCH 09/10] Remove stray {} --- versions/3.1.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index 18ab1d0326..72d03ee2da 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -1505,7 +1505,7 @@ requestBody: # The property name 'file' will be used for all files. file: type: array - items: {} + items: contentMediaType: application/octet-stream ``` From b48c032e5a94a738ba27a815b96d3ca59105673a Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Thu, 28 May 2020 09:24:17 -0700 Subject: [PATCH 10/10] Fix inconsistencies contentMediaType and Encoding Object --- versions/3.1.0.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index 72d03ee2da..09ecb3bea3 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -1544,7 +1544,7 @@ 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` of `base64` or `base64url`, 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. @@ -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 a `contentMediaType` - `contentMediaType`; 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.