Merge pull request #884 from OAI/parameter_requestBody

webron · web-flow · commit d78e003a44a7 · 2017-02-22T11:10:08.000-08:00
Updates to parameter and requestBody
diff --git a/versions/3.0.md b/versions/3.0.md
@@ -753,15 +753,15 @@ 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="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="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. When [`style`](#parameterStyle) is `form`, the default value is `true`. For all other styles, 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.
 <a name="parameterExamples"></a>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
 ---|:---:|---
 <a name="parameterContent"></a>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
+```
+
 #### <a name="requestBodyObject"></a>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
 ---|:---:|---
-<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. 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). 
 
