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
The rules for this have not been clear, and are not always intuitive.
This states and explains them directly and ensures that the
Style Examples table matches the rules.
Copy file name to clipboardExpand all lines: src/oas.md
+22-9Lines changed: 22 additions & 9 deletions
Original file line number
Diff line number
Diff line change
@@ -1026,23 +1026,36 @@ In order to support common ways of serializing simple parameters, a set of `styl
1026
1026
1027
1027
See [Appendix E](#appendix-e-percent-encoding-and-form-media-types) for a discussion of percent-encoding, including when delimiters need to be percent-encoded and options for handling collisions with percent-encoded data.
1028
1028
1029
+
##### Serialization and Examples
1030
+
1031
+
When showing serialized examples, such as with the [Example Object's](#example-object) `serializedValue` or `externalSerializedValue` fields, in most cases the value to show is the value, with all relevant percent-encoding or other encoding/escaping mechanisms, and also including any delimiters produced by the `style` and `explode` configuration.
1032
+
1033
+
For query parameters (`in: "query"` and `in: "querystring"`) and cookies (`in: "cookie"`), the parameter names MUST also be shown, as they are determined in part by `style` and `explode` rather than only by `name`, and the leading `?` or `&` delimiter MUST NOT be shown, as it is not used in all scenarios.
1034
+
1035
+
In particular, these fields are also used in the [Encoding Object](#encoding-object) for `application/x-www-form-urlencoded` request bodies which do not use a leading `?` as that delimiter is part of the URI syntax.
1036
+
Within URIs, whether each parameter is preceded by the `?` or a `&` is determined by its position relative to other parameters, and may not always be the same for a Parameter Object that is referenced by multiple Operations.
1037
+
For cookies, neither the `?` nor `&` delimiter is correct (see [Appendix D: Serializing Headers and Cookies](#appendix-d-serializing-headers-and-cookies) for more details).
1038
+
1039
+
Note that RFC6570 form expansion implementations will include either a leading `?` or `&` delimiter, depending on which type of form expansion is used, so in some scenarios it is necessary to strip off or change the leading delimiter.
1040
+
1041
+
The following section illustrates these rules.
1042
+
1029
1043
##### Style Examples
1030
1044
1031
-
Assume a parameter named `color` has one of the following values:
1045
+
Assume a parameter named `color` has one of the following values, where the value to the right of the `->` is what would be shown in the `dataValue` field of an Example Object:
1032
1046
1033
1047
```js
1034
1048
string -> "blue"
1035
1049
array -> ["blue", "black", "brown"]
1036
1050
object -> { "R": 100, "G": 200, "B": 150 }
1037
1051
```
1038
1052
1039
-
The following table shows examples, as would be shown with the `example` or `examples` keywords, of the different serializations for each value.
1053
+
The following table shows serialized examples, as would be shown with the `serializedValue` field of an Example Object, of the different serializations for each value.
1040
1054
1041
1055
* The value _empty_ denotes the empty string, and is unrelated to the `allowEmptyValue` field
1042
1056
* The behavior of combinations marked _n/a_ is undefined
1043
1057
* 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
1044
-
* 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
1045
-
* 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
1058
+
* For `form` and the non-RFC6570 query string styles `spaceDelimited`, `pipeDelimited`, and `deepObject`, 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
1046
1059
* 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.
0 commit comments