Fixes to parameter and requestBody
MODIFY
versions/3.0.md
versions/3.0.md
@@ -752,19 +752,19 @@ Field Name | Type | Description
<a name="parameterDescription"></a>description | `string` | A brief description of the parameter. This could contain examples of use. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation.
<a name="parameterRequired"></a>required | `boolean` | Determines whether this parameter is mandatory. If the parameter is [`in`](#parameterIn) "path", this property is **required** and its value MUST be `true`. Otherwise, the property MAY be included and its default value is `false`.
<a name="parameterDeprecated"></a> deprecated | `boolean` | Specifies that a parameter is deprecated and should be transitioned out of usage.
-<a name="parameterAllowEmptyValue"/>allowEmptyValue | `boolean` | Sets the ability to pass empty-valued parameters. This is valid only for `query` parameters and allows you to send a parameter with a name only or an empty value. Default value is `false`.
+<a name="parameterAllowEmptyValue"/>allowEmptyValue | `boolean` | Sets the ability to pass empty-valued parameters. This is valid only for `query` parameters and allows sending a parameter with an empty value. Default value is `false`. If [`style`](# @parameterStyle) is used, if behavior is `n/a`, the value of `allowEmptyValue` SHALL be ignored.
The rules for serialization of the parameter are specified in one of two ways.
-For simpler scenarios, a `Style` and `Schema` can be used to describe the structure and syntax of the parameter.
+For simpler scenarios, a [`style`](#parameterStyle) and [`schema`](#parameterSchema) can be used to describe the structure and syntax of the parameter.
Field Name | Type | Description
---|:---:|---
-<a name="parameterStyle"></a>style | `string` | Describes how the parameter value will be serialized depending on type of the parameter value.
+<a name="parameterStyle"></a>style | `string` | Describes how the parameter value will be serialized depending on type of the parameter value. Default values (based on value of `in`): for `query` - `form`; for `path` - `simple`; for `header` - `simple`; for `cookie` - `form`.
<a name="parameterExplode"></a>explode | `boolean` | When this is true, parameter values of type `array` or `object` generate seperate parameters for each value of the array, or key-value-pair of the map. For other types of parameters this property has no effect. The default value is false.
<a name="parameterAllowReserved"></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. This property only applies to parameters with an `in` value of `query`. The default value is `false`.
<a name="parameterSchema"></a>schema | [Schema Object](#schemaObject) | The schema defining the type used for the parameter.
-For more complex scenarios a `content` object can be used to define the media-type and schema of the parameter.
+For more complex scenarios a [`content`](#paramterContent) object can be used to define the media-type and schema of the parameter.
Field Name | Type | Description
---|:---:|---
@@ -776,8 +776,8 @@ In order to support common ways of serializing simple parameters, a set of `styl
----------- | ------ | -------- | --------
matrix | `primitive`, `array`, `object` | `path` | Path-style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.7)
label | `primitive`, `array`, `object` | `path` | Label style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.5)
-form | `primitive`, `array`, `object` | `query`| Form style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.8)
-commaDelimited | `array` | `query`, `path` | Comma seperated array values. This option replaces `collectionFormat` equal to `csv`.
+form | `primitive`, `array`, `object` | `query`, `cookie` | Form style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.8). This option replaces `collectionFormat` equal to `csv`.
+simple | `array` | `path`, `header` | Simple style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.2).
spaceDelimited | `array` | `query` | Space seperated array values. This option replaces `collectionFormat` equal to `ssv`.
pipeDelimited | `array` | `query` | Pipe seperated array values. This option replaces `collectionFormat` equal to `pipes`.
deepObject | `object` | `query` | Provides a simple way of rendering nested objects using form parameters.
@@ -802,7 +802,8 @@ label | false | . | .blue | .blue.black.brown | .R.100.G.200.B.150
label | true | . | .blue | .blue.black.brown | .R=100.G=200.B=150
form | false | color= | color=blue | color=blue,black,brown | color=R,100,G,200,B,150
form | true | color= | color=blue | color=blue&color=black&color=brown | R=100&G=200&B=150
-commaDelimited | false | n/a | n/a | blue,black,brown | R,100,G,200,B,150
+simple | false | n/a | blue | blue,black,brown | R,100,G,200,B,150
+simple | true | n/a | n/a | blue,black,brown | R=100,G=200,B=150
spaceDelimited | false | n/a | n/a | blue%20black%20brown | R%20100%20G%20200%20B%20150
pipeDelimited | false | n/a | n/a | blue\|black\|brown | R\|100\|G\|200|G\|150
deepObject | true | n/a | n/a | n/a | color[R]=100&color[G]=200&color[B]=150
@@ -896,6 +897,28 @@ style: form
explode: true
```
+A free-form query parameter, allowing undefined parameters of a specific type:
+```json
+{
+ "in": "query",
+ "name": "freeForm",
+ "type": "object",
+ "additionalProperties": {
+ "type": "integer"
+ },
+ "style": "form"
+}
+```
+
+```yaml
+in: query
+name: freeForm
+type: object
+additionalProperties:
+ type: integer
+style: form
+```
+
#### <a name="requestBodyObject"></a>Request Body Object
Describes a single request body.
@@ -1176,7 +1199,7 @@ requestBody:
Note that in the above example, the contents in the `requestBody` must be stringified per RFC1866 when being passed to the server. In addition, the `address` field complex object will be strigified as well.
-When passing complex objects in the `x-www-form-urlencoded` content type, the default serialization strategy of such properties is described in the `parameterContent` section as `deepObject`.
+When passing complex objects in the `x-www-form-urlencoded` content type, the default serialization strategy of such properties is described in the `parameterContent` section as `form`.
##### Special Considerations for `mutlipart` content
@@ -1239,10 +1262,10 @@ A single encoding definition applied to a single schema property
##### Fixed Fields
Field Name | Type | Description
---|:---:|---
-<a name="contentType"></a>contentType | `string` | **Required.** The content-type to use for encoding a specific property.
-<a name="headers"></a>Headers | `object` | A string map allowing additional information to be provided as headers, for example `Content-Disposition`. Note `Content-Type` is described separately and will be ignored from this section.
-<a name="style"></a>Style | `string` | The content-type to use for encoding a specific property. See (#parameterContent) for details on the `style` property
-<a name="explode"></a>explode | `boolean` | When this is true, property values of type `array` or `object` generate seperate parameters for each value of the array, or key-value-pair of the map. For other types of properties this property has no effect. The default value is false.
+<a name="encodingContentType"></a>contentType | `string` | The content-type to use 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 - `plain/text`; for `object` - `application/json`; for `array` - the default is defined based on the inner type.
+<a name="encodingHeaders"></a>Headers | `object` | A string map allowing additional information to be provided as headers, for example `Content-Disposition`. Note `Content-Type` is described separately and will be ignored from this section.
+<a name="encodingStyle"></a>style | `string` | The content-type to use for encoding a specific property. See (#parameterContent) for details on the [`style`](#parameterStyle) property. The behavior follows the same values allowed for `query` parameters, including default values.
+<a name="encodingExplode"></a>explode | `boolean` | When this is true, property values of type `array` or `object` generate seperate parameters for each value of the array, or key-value-pair of the map. For other types of properties this property has no effect. The default value is false.
This object can be extended with [Specification Extensions](#specificationExtensions).

Fixes to parameter and requestBody