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).