v3.3: edits to parameter sections #5122
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -769,14 +769,15 @@ See [Appendix E](#appendix-e-percent-encoding-and-form-media-types) for a detail | |
| There are five possible parameter locations specified by the `in` field: | ||
|
|
||
| * path - Used together with [Path Templating](#path-templating), where the parameter value is actually part of the operation's URL. This does not include the host or base path of the API. For example, in `/items/{itemId}`, the path parameter is `itemId`. | ||
| * query - Parameters that are appended to the URL with the `?` character (or to existing query parameters with the `&` character), as described by [RFC3986 section 3.4](https://datatracker.ietf.org/doc/html/rfc3986#section-3.4); | ||
| MUST NOT appear in the same operation (or in the operation's path-item) as an `in: "querystring"` parameter. | ||
| * querystring - A parameter that treats the entire URL query string as a value which MUST be specified using the `content` field, most often with media type `application/x-www-form-urlencoded` using [Encoding Objects](#encoding-object) in the same way as with request bodies of that media type; MUST NOT appear more than once, and MUST NOT appear in the same operation (or in the operation's path-item) as any `in: "query"` parameters. | ||
| * header - Custom headers that are expected as part of the request. Note that [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#section-5.1) states header names are case-insensitive. | ||
| * cookie - Used to pass a specific cookie value to the API. | ||
|
|
||
| #### Fixed Fields | ||
|
|
||
| The rules for serialization and deserialization of the parameter are specified in one of two ways. | ||
|
Member
There was a problem hiding this comment. I think in other places we have used "serialization and parsing" or "parsing and serialization." Do you think "deserialization" is a better term here? Is there a distinction between that and "parsing"? I have no idea what the answer is, I either copied "parsing" or picked it without much thought, so I'm open to changing it as long as we're consistent. |
||
| Parameter Objects MUST include either a `content` field or a `schema` field, but not both. | ||
| See [Appendix B](#appendix-b-data-type-conversion) for a discussion of converting values of various types to string representations. | ||
|
|
||
|
|
@@ -820,7 +821,7 @@ In these cases, implementations MUST pass values through unchanged rather than a | |
| | <a name="parameter-style"></a>style | `string` | Describes how the parameter value will be serialized depending on the type of the parameter value. Default values (based on value of `in`): for `"query"` - `"form"`; for `"path"` - `"simple"`; for `"header"` - `"simple"`; for `"cookie"` - `"form"` (for compatibility reasons; note that `style: "cookie"` SHOULD be used with `in: "cookie"`; see [Appendix D](#appendix-d-serializing-headers-and-cookies) for details). | | ||
| | <a name="parameter-explode"></a>explode | `boolean` | When this is true, parameter values of type `array` or `object` generate separate parameters for each value of the array or key-value pair of the map. For other types of parameters, or when [`style`](#parameter-style) is `"deepObject"`, this field has no effect. When `style` is `"form"` or `"cookie"`, the default value is `true`. For all other styles, the default value is `false`. | | ||
| | <a name="parameter-allow-reserved"></a>allowReserved | `boolean` | When this is true, parameter values are serialized using reserved expansion, as defined by [RFC6570](https://datatracker.ietf.org/doc/html/rfc6570#section-3.2.3), which allows [RFC3986's reserved character set](https://datatracker.ietf.org/doc/html/rfc3986#section-2.2), as well as percent-encoded triples, to pass through unchanged, while still percent-encoding all other disallowed characters (including `%` outside of percent-encoded triples). Applications are still responsible for percent-encoding reserved characters that are not allowed by the rules of the `in` destination or media type, or are [not allowed in the path by this specification](#path-templating); see [URL Percent-Encoding](#url-percent-encoding) for details. The default value is `false`. This field only applies to `in` and `style` values that automatically percent-encode. | | ||
| | <a name="parameter-schema"></a>schema | [Schema Object](#schema-object) | The schema defining the type and other constraints used for the parameter. | | ||
|
|
||
| See also [Appendix C: Using RFC6570-Based Serialization](#appendix-c-using-rfc6570-based-serialization) for additional guidance. | ||
|
|
||
|
|
@@ -923,15 +924,15 @@ The following table shows serialized examples, as would be shown with the `seria | |
| | label | true | _empty_ | .blue | .blue.black.brown | .R=100.G=200.B=150 | | ||
| | simple | false | _empty_ | blue | blue,black,brown | R,100,G,200,B,150 | | ||
| | simple | true | _empty_ | 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 | | ||
| | spaceDelimited | false | _n/a_ | _n/a_ | color=blue%20black%20brown | color=R%20100%20G%20200%20B%20150 | | ||
|
Comment on lines
-926
to
+929
Member
There was a problem hiding this comment. My recollection is that we need these because otherwise the text will wrap at |
||
| | spaceDelimited | true | _n/a_ | _n/a_ | _n/a_ | _n/a_ | | ||
| | pipeDelimited | false | _n/a_ | _n/a_ | color=blue%7Cblack%7Cbrown | color=R%7C100%7CG%7C200%7CB%7C150 | | ||
| | pipeDelimited | true | _n/a_ | _n/a_ | _n/a_ | _n/a_ | | ||
| | deepObject | _n/a_ | _n/a_ | _n/a_ | _n/a_ | color%5BR%5D=100&color%5BG%5D=200&color%5BB%5D=150 | | ||
| | cookie | false | color= | color=blue | color=blue,black,brown | color=R,100,G,200,B,150 | | ||
| | cookie | true | color= | color=blue | color=blue; color=black; color=brown | R=100; G=200; B=150 | | ||
|
|
||
| #### Extending Support for Querystring Formats | ||
|
|
||
|
|
@@ -1070,7 +1071,7 @@ examples: | |
| dataValue: | ||
| page: 4 | ||
| pageSize: 50 | ||
| serializedValue: page=4&pageSize=50 | ||
| ``` | ||
|
|
||
| A complex parameter using `content` to define serialization, with multiple levels and types of examples shown to make the example usage options clear — note that `dataValue` is the same at both levels and does not need to be shown in both places in normal usage, but `serializedValue` is different: | ||
|
|
@@ -3072,7 +3073,7 @@ Serializing data into such formats requires either examining the schema-validate | |
|
|
||
| When inspecting schemas, given a starting point schema, implementations MUST examine that schema and all schemas that can be reached from it by following only `$ref` and `allOf` keywords. | ||
| These schemas are guaranteed to apply to any instance. | ||
| When searching schemas for `type`, if the `type` keyword's value is a list of types and the serialized value can be successfully parsed as more than one of the types in the list, and no other findable `type` keyword disambiguates the actual required type, the behavior is implementation-defined and must be documented. | ||
|
Member
There was a problem hiding this comment. There was a debate in the Thursday meeting over documentation requirements like this, which I had put in a lot of places, and the consensus was not to include it. So I had to take it out, and we can only have language like this if we want to re-open that discussion in the Thursday call. |
||
| Schema Objects that do not contain `type` MUST be considered to allow all types, regardless of which other keywords are present (e.g. `maximum` applies to numbers, but _does not_ require the instance to be a number). | ||
|
|
||
| Implementations MAY inspect subschemas or possible reference targets of other keywords such as `oneOf` or `$dynamicRef`, but MUST NOT attempt to resolve ambiguities. | ||
|
|
@@ -4909,7 +4910,7 @@ parameters: | |
| type: string | ||
| ``` | ||
|
|
||
| This example is equivalent to RFC6570's `{?foo*,bar}`, and **NOT** `{?foo*}{&bar}`. The latter is problematic because if `foo` is not defined (or the object has no properties), the result will be an invalid URI. | ||
|
Member
There was a problem hiding this comment. I remember wrestling with whether to get into this when I wrote this part. RFC6570's actual requirements are even more complex:
I think I decided to not get into it here because of this normative reference in the Parameter Object section:
Perhaps a more general "see RFC6570 §3.2 for details on what is considered undefined" rather than trying to enumerate the conditions would be better? I do like the idea of making some note here that "undefined" is a complex concept. |
||
| The `&` prefix operator has no equivalent in the Parameter Object. | ||
|
|
||
| Note that RFC6570 does not specify behavior for compound values beyond the single level addressed by `explode`. The result of using objects or arrays where no behavior is clearly specified for them is implementation-defined. | ||
|
|
@@ -4964,9 +4965,9 @@ parameters: | |
| type: object | ||
| additionalProperties: | ||
| type: string | ||
|
Member
There was a problem hiding this comment. Here I was trying to be unambiguous about the |
||
| - name: words | ||
| in: query | ||
| explode: false | ||
| schema: | ||
| type: array | ||
| items: | ||
|
|
@@ -4994,16 +4995,14 @@ To do that, we'll add `allowReserved: true` to `formulas`, and change to `style: | |
| parameters: | ||
| - name: formulas | ||
| in: query | ||
| allowReserved: true | ||
| schema: | ||
| type: object | ||
| additionalProperties: | ||
| type: string | ||
| - name: words | ||
| in: query | ||
| style: spaceDelimited | ||
|
Comment on lines
-5001
to
-5006
Member
There was a problem hiding this comment. Likewise here I was trying to show the explicit lack of difference between |
||
| schema: | ||
| type: array | ||
| items: | ||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Why the RFC3986 reference? That section does define the query component, but only vaguely alludes to key-value pairs and does not mention the
&character at all. Technically RFC6570 is the most relevant specification defining the query string as produced byin: query, although not as produces byin: querystring, for which WHATWG URL is more relevant.