You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
Copy file name to clipboardExpand all lines: versions/3.0.4.md
+13-4Lines changed: 13 additions & 4 deletions
Original file line number
Diff line number
Diff line change
@@ -1014,6 +1014,14 @@ There are four possible parameter locations specified by the `in` field:
1014
1014
1015
1015
1016
1016
##### 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
+
1017
1025
Field Name | Type | Description
1018
1026
---|:---:|---
1019
1027
<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
1023
1031
<a name="parameterDeprecated"></a> deprecated | `boolean` | Specifies that a parameter is deprecated and SHOULD be transitioned out of usage. Default value is `false`.
1024
1032
<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.
1025
1033
1026
-
The rules for serialization of the parameter are specified in one of two ways.
1034
+
###### Fixed Fields for use with `schema`
1035
+
1027
1036
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.
1028
1038
1029
1039
Field Name | Type | Description
1030
1040
---|:---:|---
@@ -1035,10 +1045,9 @@ Field Name | Type | Description
1035
1045
<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.
1036
1046
<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.
1037
1047
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`
1041
1049
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.
0 commit comments