Skip to content

Commit 9dbb82b

Browse files
committed
Clarify constraints on Parameter Object fields
This makes the relational requirements of `content` vs `schema` and associated fields more clear. The mutual exclusivity requirement is moved up to the top of the Fixed Fields section, and each table table is given a subsection clarifying its meaning. This makes it easier to follow the multi-table format, which is unusual within the OAS. The commentary on `example` and `examples` is moved to the section on `schema` and related parameters as it appears to only apply in that case.
1 parent dad5a79 commit 9dbb82b

File tree

1 file changed

+13
-4
lines changed

1 file changed

+13
-4
lines changed

versions/3.0.4.md

Lines changed: 13 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1014,6 +1014,14 @@ There are four possible parameter locations specified by the `in` field:
10141014

10151015

10161016
##### Fixed Fields
1017+
1018+
The rules for serialization of the parameter are specified in one of two ways.
1019+
Parameter Objects MUST include either a `content` field or a `schema` field, but not both.
1020+
1021+
###### Common Fixed Fields
1022+
1023+
These fields MAY be used with either `content` or `schema`.
1024+
10171025
Field Name | Type | Description
10181026
---|:---:|---
10191027
<a name="parameterName"></a>name | `string` | **REQUIRED**. The name of the parameter. Parameter names are *case sensitive*. <ul><li>If [`in`](#parameterIn) is `"path"`, the `name` field MUST correspond to a template expression occurring within the [path](#pathsPath) field in the [Paths Object](#pathsObject). See [Path Templating](#pathTemplating) for further information.<li>If [`in`](#parameterIn) is `"header"` and the `name` field is `"Accept"`, `"Content-Type"` or `"Authorization"`, the parameter definition SHALL be ignored.<li>For all other cases, the `name` corresponds to the parameter name used by the [`in`](#parameterIn) property.</ul>
@@ -1023,8 +1031,10 @@ Field Name | Type | Description
10231031
<a name="parameterDeprecated"></a> deprecated | `boolean` | Specifies that a parameter is deprecated and SHOULD be transitioned out of usage. Default value is `false`.
10241032
<a name="parameterAllowEmptyValue"></a> 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.
10251033

1026-
The rules for serialization of the parameter are specified in one of two ways.
1034+
###### Fixed Fields for use with `schema`
1035+
10271036
For simpler scenarios, a [`schema`](#parameterSchema) and [`style`](#parameterStyle) can describe the structure and syntax of the parameter.
1037+
When `example` or `examples` are provided in conjunction with the `schema` object, the example MUST follow the prescribed serialization strategy for the parameter.
10281038

10291039
Field Name | Type | Description
10301040
---|:---:|---
@@ -1035,10 +1045,9 @@ Field Name | Type | Description
10351045
<a name="parameterExample"></a>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.
10361046
<a name="parameterExamples"></a>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.
10371047

1038-
For more complex scenarios, the [`content`](#parameterContent) property can define the media type and schema of the parameter.
1039-
A parameter MUST contain either a `schema` property, or a `content` property, but not both.
1040-
When `example` or `examples` are provided in conjunction with the `schema` object, the example MUST follow the prescribed serialization strategy for the parameter.
1048+
###### Fixed Fields and considerations for use with `content`
10411049

1050+
For more complex scenarios, the [`content`](#parameterContent) property can define the media type and schema of the parameter, as well as give examples of it use.
10421051

10431052
Field Name | Type | Description
10441053
---|:---:|---

0 commit comments

Comments
 (0)