Skip to content

Commit 96ebfa8

Browse files
committed
Minor param serialization and wording fixes
* 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.
1 parent d1ba364 commit 96ebfa8

File tree

1 file changed

+11
-5
lines changed

1 file changed

+11
-5
lines changed

versions/3.0.4.md

Lines changed: 11 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1127,6 +1127,10 @@ In order to support common ways of serializing simple parameters, a set of `styl
11271127

11281128
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.
11291129

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+
11301134
##### Style Examples
11311135

11321136
Assume a parameter named `color` has one of the following values:
@@ -3789,7 +3793,7 @@ security:
37893793

37903794
See [Resolving Implicit Connections](#resolving-implicit-connections) for more information.
37913795

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:
37933797

37943798
```HTTP
37953799
GET /api/description/openapi HTTP/1.1
@@ -3832,7 +3836,7 @@ paths:
38323836
$ref: 'other#/components/pathItems/Foo'
38333837
```
38343838

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:
38363840

38373841
```HTTP
38383842
GET /api/description/other HTTP/1.1
@@ -3985,11 +3989,12 @@ Requiring input as pre-formatted, schema-validated strings also improves round-t
39853989

39863990
## Appendix C: Using RFC6570 Implementations
39873991

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:
39893993

39903994
| Object | Condition |
39913995
| ---- | ---- |
39923996
| [Parameter Object](#parameter-object) | When `schema` is present |
3997+
| [Header Object](#header-object) | When `schema` is present |
39933998
| [Encoding Object](#encoding-object) | When encoding for `application/x-www-form-urlencoded` and any of `style`, `explode`, or `allowReserved` are used |
39943999

39954000
Implementations of this specification MAY use an implementation of RFC6570 to perform variable expansion, however, some caveats apply.
@@ -4032,7 +4037,7 @@ parameters:
40324037
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.
40334038
The `&` prefix operator has no equivalent in the Parameter Object.
40344039

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.
40364041

40374042
### Non-RFC6570 Field Values and Combinations
40384043

@@ -4114,6 +4119,7 @@ parameters:
41144119
- name: words
41154120
in: query
41164121
style: spaceDelimited
4122+
explode: false
41174123
schema:
41184124
type: array
41194125
items:
@@ -4321,7 +4327,7 @@ However, care must be taken to use `form-urlencoded` decoding if `+` represents
43214327

43224328
### Percent-Encoding and Illegal or Reserved Delimiters
43234329

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]].
43254331
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.
43264332

43274333
The space character is always illegal and encoded in some way by all implementations of all versions of the relevant standards.

0 commit comments

Comments
 (0)