Skip to content

Commit 10f1810

Browse files
committed
The "?" is not part of individual parameter serializations
We say that the example table is "as would be shown with the `example` or `examples` keywords", but then we include the `?` which is not correct for a single parameter with `in: query`. Even with `in: querystring`, it would not be correct because the parameter describes the `application/x-www-form-urlencoded` document, which does not include the `?` delimiter.
1 parent b3dd05f commit 10f1810

File tree

1 file changed

+6
-6
lines changed

1 file changed

+6
-6
lines changed

src/oas.md

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1218,7 +1218,7 @@ The following table shows examples, as would be shown with the `example` or `exa
12181218
* The behavior of combinations marked _n/a_ is undefined
12191219
* The `undefined` column replaces the `empty` column in previous versions of this specification in order to better align with [RFC6570](https://www.rfc-editor.org/rfc/rfc6570.html#section-2.3) terminology, which describes certain values including but not limited to `null` as "undefined" values with special handling; notably, the empty string is _not_ undefined
12201220
* For `form` and the non-RFC6570 query string styles `spaceDelimited`, `pipeDelimited`, and `deepObject`, each example is shown prefixed with `?` as if it were the only query parameter; see [Appendix C](#appendix-c-using-rfc6570-based-serialization) for more information on constructing query strings from multiple parameters, and [Appendix D](#appendix-d-serializing-headers-and-cookies) for warnings regarding `form` and cookie parameters
1221-
* Note that the `?` prefix is not appropriate for serializing `application/x-www-form-urlencoded` HTTP message bodies, and MUST be stripped or (if constructing the string manually) not added when used in that context; see the [Encoding Object](#encoding-object) for more information
1221+
* Note that the `?` prefix is not included in the serialization of each parameter, as it is not a part of any single `in: "query"` parameter, but rather a part of the generic URI syntax. When using these fields in the [Encoding Object](#encoding-object) to serialized `application/x-www-form-urlencoded` HTTP message content, the `?` MUST NOT be included.
12221222
* The examples are percent-encoded as required by RFC6570 and RFC3986; see [Appendix E](#appendix-e-percent-encoding-and-form-media-types) for a thorough discussion of percent-encoding concerns, including why unencoded `|` (`%7C`), `[` (`%5B`), and `]` (`%5D`) seem to work in some environments despite not being compliant.
12231223

12241224
| [`style`](#style-values) | `explode` | `undefined` | `string` | `array` | `object` |
@@ -1229,14 +1229,14 @@ The following table shows examples, as would be shown with the `example` or `exa
12291229
| label | true | . | .blue | .blue.black.brown | .R=100.G=200.B=150 |
12301230
| simple | false | _empty_ | blue | blue,black,brown | R,100,G,200,B,150 |
12311231
| simple | true | _empty_ | blue | blue,black,brown | R=100,G=200,B=150 |
1232-
| form | false | <span style="white-space: nowrap;">?color=</span> | <span style="white-space: nowrap;">?color=blue</span> | <span style="white-space: nowrap;">?color=blue,black,brown</span> | <span style="white-space: nowrap;">?color=R,100,G,200,B,150</span> |
1233-
| form | true | <span style="white-space: nowrap;">?color=</span> | <span style="white-space: nowrap;">?color=blue</span> | <span style="white-space: nowrap;">?color=blue&color=black&color=brown</span> | <span style="white-space: nowrap;">?R=100&G=200&B=150</span> |
1234-
| spaceDelimited</span> | false | _n/a_ | _n/a_ | <span style="white-space: nowrap;">?color=blue%20black%20brown</span> | <span style="white-space: nowrap;">?color=R%20100%20G%20200%20B%20150</span> |
1232+
| form | false | <span style="white-space: nowrap;">color=</span> | <span style="white-space: nowrap;">color=blue</span> | <span style="white-space: nowrap;">color=blue,black,brown</span> | <span style="white-space: nowrap;">color=R,100,G,200,B,150</span> |
1233+
| form | true | <span style="white-space: nowrap;">color=</span> | <span style="white-space: nowrap;">color=blue</span> | <span style="white-space: nowrap;">color=blue&color=black&color=brown</span> | <span style="white-space: nowrap;">R=100&G=200&B=150</span> |
1234+
| spaceDelimited</span> | false | _n/a_ | _n/a_ | <span style="white-space: nowrap;">color=blue%20black%20brown</span> | <span style="white-space: nowrap;">color=R%20100%20G%20200%20B%20150</span> |
12351235
| spaceDelimited | true | _n/a_ | _n/a_ | _n/a_ | _n/a_ |
1236-
| pipeDelimited | false | _n/a_ | _n/a_ | <span style="white-space: nowrap;">?color=blue%7Cblack%7Cbrown</span> | <span style="white-space: nowrap;">?color=R%7C100%7CG%7C200%7CB%7C150</span> |
1236+
| pipeDelimited | false | _n/a_ | _n/a_ | <span style="white-space: nowrap;">color=blue%7Cblack%7Cbrown</span> | <span style="white-space: nowrap;">color=R%7C100%7CG%7C200%7CB%7C150</span> |
12371237
| pipeDelimited | true | _n/a_ | _n/a_ | _n/a_ | _n/a_ |
12381238
| deepObject | false | _n/a_ | _n/a_ | _n/a_ | _n/a_ |
1239-
| deepObject | true | _n/a_ | _n/a_ | _n/a_ | <span style="white-space: nowrap;">?color%5BR%5D=100&color%5BG%5D=200&color%5BB%5D=150</span> |
1239+
| deepObject | true | _n/a_ | _n/a_ | _n/a_ | <span style="white-space: nowrap;">color%5BR%5D=100&color%5BG%5D=200&color%5BB%5D=150</span> |
12401240

12411241
##### Parameter Object Examples
12421242

0 commit comments

Comments
 (0)