diff --git a/versions/3.2.0.md b/versions/3.2.0.md index 5037aeb318..cfb5555e37 100644 --- a/versions/3.2.0.md +++ b/versions/3.2.0.md @@ -1053,6 +1053,14 @@ There are four possible parameter locations specified by the `in` field: ##### Fixed Fields + +The rules for serialization of the parameter are specified in one of two ways. +Parameter Objects MUST include either a `content` field or a `schema` field, but not both. + +###### Common Fixed Fields + +These fields MAY be used with either `content` or `schema`. + Field Name | Type | Description ---|:---:|--- name | `string` | **REQUIRED**. The name of the parameter. Parameter names are *case sensitive*. @@ -1062,8 +1070,10 @@ Field Name | Type | Description deprecated | `boolean` | Specifies that a parameter is deprecated and SHOULD be transitioned out of usage. 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, and if behavior is `n/a` (cannot be serialized), the value of `allowEmptyValue` SHALL be ignored. Use of this property is NOT RECOMMENDED, as it is likely to be removed in a later revision. -The rules for serialization of the parameter are specified in one of two ways. +###### Fixed Fields for use with `schema` + For simpler scenarios, a [`schema`](#parameterSchema) and [`style`](#parameterStyle) can describe the structure and syntax of the parameter. +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 ---|:---:|--- @@ -1074,10 +1084,9 @@ Field Name | Type | Description example | Any | Example of the parameter's potential value. The example SHOULD match the specified schema and encoding properties if present. The `example` field is mutually exclusive of the `examples` field. Furthermore, if referencing a `schema` that contains an example, the `example` value SHALL _override_ the example provided by the schema. To represent examples of media types that cannot naturally be represented in JSON or YAML, a string value can contain the example with escaping where necessary. examples | Map[ `string`, [Example Object](#exampleObject) \| [Reference Object](#referenceObject)] | Examples of the parameter's potential value. Each example SHOULD contain a value in the correct format as specified in the parameter encoding. The `examples` field is mutually exclusive of the `example` field. Furthermore, if referencing a `schema` that contains an example, the `examples` value SHALL _override_ the example provided by the schema. -For more complex scenarios, the [`content`](#parameterContent) property can define the media type and schema of the parameter. -A parameter MUST contain either a `schema` property, or a `content` property, but not both. -When `example` or `examples` are provided in conjunction with the `schema` object, the example MUST follow the prescribed serialization strategy for the parameter. +###### Fixed Fields and considerations for use with `content` +For more complex scenarios, the [`content`](#parameterContent) property can define the media type and schema of the parameter, as well as give examples of its use. Field Name | Type | Description ---|:---:|---