Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Encoding Obj contentType takes a media range (3.0.4) #3813

Closed
wants to merge 1 commit into from
Closed

Encoding Obj contentType takes a media range (3.0.4) #3813

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 12 additions & 1 deletion versions/3.0.4.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1601,14 +1601,25 @@ 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: 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.
<a name="encodingContentType"></a>contentType | `string` | The Content-Type for encoding a specific property. The value is a media type or [media type range](https://tools.ietf.org/html/rfc7231#appendix-D). Default value depends on the property type as shown in the table below.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<a name="encodingContentType"></a>contentType | `string` | The Content-Type for encoding a specific property. The value is a media type or [media type range](https://tools.ietf.org/html/rfc7231#appendix-D). Default value depends on the property type as shown in the table below.
<a name="encodingContentType"></a>contentType | `string` | The Content-Type for encoding a specific property. The value is a comma-separated list of [media type ranges](https://tools.ietf.org/html/rfc7231#appendix-D). Default value depends on the property type as shown in the table below.

Note: rule media-range is only a single thingy, and it includes non-wildcard type "/" subtype as an alternative.

We can't take away the "list of" in a patch version.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ralfhandl there is no intention to take away anything. This is what we thought made sense in a TDC call, so either it was supposed to be "list of media-ranges" or something else.

I think perhaps what we want is list of media-ranges-without-parameters, because that's what the previous awkward wording (aside from the "the two types" part) described.

<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`.
<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`.
<a name="encodingAllowReserved"></a>allowReserved | `boolean` | Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-2.2) `:/?#[]@!$&'()*+,;=` to be included without percent-encoding. The default value is `false`. This property SHALL be ignored if the request body media type is not `application/x-www-form-urlencoded`.

This object MAY be extended with [Specification Extensions](#specificationExtensions).

###### Default Values for `contentType`

The default values for `contentType` are as follows:

Property Type | Property Format | Default `contentType`
------------- | --------------- | ---------------------
`string` | `binary` | `application/octet-stream`
`string`, `number`, `integer`, or `boolean` | _n/a_ | `text/plain`
`object` | _n/a_ | `application/json`
`array` | _n/a_ | according to the `type` and `format` of the `items` schema

##### Encoding Object Example

`multipart/form-data` allows for binary parts:
Expand Down