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
* Directly address `style` delimiters in parameter values
by explaining that we don't define how to handle them.
* Explicitly set `explode: false` in an example as the default
with `style: form` is `explode: true`; the `explode: true`
example was also left explicit to reduce confusion.
* Tidy up overly conversational (e.g. "our document") language
that I'd meant to revisit but forgot about.
* Include the Header Object as one of the places where the
`style` keyword is used (even if it is the simplest case)
* Fix a missing space before an RFC reference.
Copy file name to clipboardExpand all lines: versions/3.0.4.md
+11-5Lines changed: 11 additions & 5 deletions
Original file line number
Diff line number
Diff line change
@@ -1127,6 +1127,10 @@ In order to support common ways of serializing simple parameters, a set of `styl
1127
1127
1128
1128
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.
1129
1129
1130
+
Note that parameter data can contain characters used as delimiters by certain `style` and `explode` configurations.
1131
+
For example, when using `style: "simple"`, the arrays `["monospace", "serif", "Arial,Helvetica,sans-serif"]` and `["monospace", "serif", "Arial", "Helvetica", "sans-serif"]` would both be encoded as `"monospace,serif,Arial,Helvetica,sans-serif"`.
1132
+
API providers SHOULD document how users are expected to handle such values, as the OpenAPI Specification does not address this sort of scenario.
1133
+
1130
1134
##### Style Examples
1131
1135
1132
1136
Assume a parameter named `color` has one of the following values:
@@ -3789,7 +3793,7 @@ security:
3789
3793
3790
3794
See [Resolving Implicit Connections](#resolving-implicit-connections) for more information.
3791
3795
3792
-
First, our [entry document](#openapi-description-structure) is where parsing begins. It defines the `MySecurity` security scheme to be JWT-based, and it defines a Path Item as a reference to a component in another document:
3796
+
First, the [entry document](#openapi-description-structure) is where parsing begins. It defines the `MySecurity` security scheme to be JWT-based, and it defines a Path Item as a reference to a component in another document:
3793
3797
3794
3798
```HTTP
3795
3799
GET /api/description/openapi HTTP/1.1
@@ -3832,7 +3836,7 @@ paths:
3832
3836
$ref: 'other#/components/pathItems/Foo'
3833
3837
```
3834
3838
3835
-
Next, we have our referenced document, `other`. The fact that we don't use file extensions gives the client the flexibility to choose an acceptable format on a resource-by-resource basis, assuming both representations are available:
3839
+
This entry document references another document, `other`, without using a file extension. This gives the client the flexibility to choose an acceptable format on a resource-by-resource basis, assuming both representations are available:
3836
3840
3837
3841
```HTTP
3838
3842
GET /api/description/other HTTP/1.1
@@ -3985,11 +3989,12 @@ Requiring input as pre-formatted, schema-validated strings also improves round-t
3985
3989
3986
3990
## Appendix C: Using RFC6570 Implementations
3987
3991
3988
-
Serialization is defined in terms of [RFC6570](https://www.rfc-editor.org/rfc/rfc6570) URI Templates in two scenarios:
3992
+
Serialization is defined in terms of [RFC6570](https://www.rfc-editor.org/rfc/rfc6570) URI Templates in three scenarios:
3989
3993
3990
3994
| Object | Condition |
3991
3995
| ---- | ---- |
3992
3996
| [Parameter Object](#parameter-object) | When `schema` is present |
3997
+
| [Header Object](#header-object) | When `schema` is present |
3993
3998
| [Encoding Object](#encoding-object) | When encoding for `application/x-www-form-urlencoded` and any of `style`, `explode`, or `allowReserved` are used |
3994
3999
3995
4000
Implementations of this specification MAY use an implementation of RFC6570 to perform variable expansion, however, some caveats apply.
@@ -4032,7 +4037,7 @@ parameters:
4032
4037
This example is equivalent to RFC6570's `{?foo*,bar}`, and **_NOT_** `{?foo*}{&bar}`. The latter is problematic because if `foo` is not defined, the result will be an invalid URI.
4033
4038
The `&` prefix operator has no equivalent in the Parameter Object.
4034
4039
4035
-
Note that RFC6570 does not specify behavior for compound values beyond the single level addressed by `explode`. The results of using objects or arrays where no behavior is clearly specified for them is implementation-defined.
4040
+
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.
4036
4041
4037
4042
### Non-RFC6570 Field Values and Combinations
4038
4043
@@ -4114,6 +4119,7 @@ parameters:
4114
4119
- name: words
4115
4120
in: query
4116
4121
style: spaceDelimited
4122
+
explode: false
4117
4123
schema:
4118
4124
type: array
4119
4125
items:
@@ -4321,7 +4327,7 @@ However, care must be taken to use `form-urlencoded` decoding if `+` represents
4321
4327
4322
4328
### Percent-Encoding and Illegal or Reserved Delimiters
4323
4329
4324
-
The `[`, `]`, `|`, and space characters, which are used as delimiters for the `deepObject`, `pipeDelimited`, and `spaceDelimited` styles, respectively, all MUST be percent-encoded to comply with[[RFC3986]].
4330
+
The `[`, `]`, `|`, and space characters, which are used as delimiters for the `deepObject`, `pipeDelimited`, and `spaceDelimited` styles, respectively, all MUST be percent-encoded to comply with[[RFC3986]].
4325
4331
This requires users to pre-encode the character(s) in some other way in parameter names and values to distinguish them from the delimiter usage when using one of these styles.
4326
4332
4327
4333
The space character is always illegal and encoded in some way by all implementations of all versions of the relevant standards.
0 commit comments