diff --git a/versions/3.0.md b/versions/3.0.md
index 7e245009a9..044452942a 100644
--- a/versions/3.0.md
+++ b/versions/3.0.md
@@ -753,15 +753,15 @@ Field Name | Type | Description
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.
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`.
deprecated | `boolean` | Specifies that a parameter is deprecated and should be transitioned out of usage.
-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`.
+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
---|:---:|---
-style | `string` | Describes how the parameter value will be serialized depending on type of the parameter value.
-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.
+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`.
+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. When [`style`](#parameterStyle) is `form`, the default value is `true`. For all other styles, the default value is `false`.
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`.
schema | [Schema Object](#schemaObject) | The schema defining the type used for the parameter.
examples | [Examples Array](#examplesArray) | Examples of the content type. Each example in the Examples Array must be in the correct format as specified parameter encoding. The `examples` object is mutually exclusive to the `example` object. Furthermore, if referencing a `schema` which contains an example, the `examples` value will _override_ the example provided by the schema.
@@ -772,6 +772,7 @@ and schema of the parameter. This option is mutually exclusive with the simple
above. When `example` or `examples` are provided in conjunction with the `schema` object,
the example must follow the prescribed serialization strategy for the parameter.
+
Field Name | Type | Description
---|:---:|---
content | [Content Object](#contentObject) | The content of the request body.
@@ -782,8 +783,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` with a `csv` value.
+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.
@@ -808,7 +809,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 | blue | 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
@@ -902,6 +904,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
+```
+
#### Request Body Object
Describes a single request body.
@@ -1176,7 +1200,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 +1263,10 @@ A single encoding definition applied to a single schema property
##### Fixed Fields
Field Name | Type | Description
---|:---:|---
-contentType | `string` | **Required.** The content-type to use for encoding a specific property.
-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.
-Style | `string` | The content-type to use for encoding a specific property. See (#parameterContent) for details on the `style` property
-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.
+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.
+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.
+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.
+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. When [`style`](#encodingStyle) is `form`, the default value is `true`. For all other styles, the default value is `false`.
This object can be extended with [Specification Extensions](#specificationExtensions).