Skip to content

Commit ba08a1a

Browse files
committed
Minor param serialization and wording fixes
* 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) * Minor grammar fix. * Fix a missing space before an RFC reference.
1 parent 5c60e5b commit ba08a1a

File tree

1 file changed

+7
-5
lines changed

1 file changed

+7
-5
lines changed

versions/3.1.1.md

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3990,7 +3990,7 @@ security:
39903990

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

3993-
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:
3993+
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:
39943994

39953995
```HTTP
39963996
GET /api/description/openapi HTTP/1.1
@@ -4033,7 +4033,7 @@ paths:
40334033
$ref: 'other#/components/pathItems/Foo'
40344034
```
40354035

4036-
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:
4036+
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:
40374037

40384038
```HTTP
40394039
GET /api/description/other HTTP/1.1
@@ -4190,11 +4190,12 @@ Requiring input as pre-formatted, schema-validated strings also improves round-t
41904190

41914191
## Appendix C: Using RFC6570-Based Serialization
41924192

4193-
Serialization is defined in terms of [RFC6570](https://www.rfc-editor.org/rfc/rfc6570) URI Templates in two scenarios:
4193+
Serialization is defined in terms of [RFC6570](https://www.rfc-editor.org/rfc/rfc6570) URI Templates in three scenarios:
41944194

41954195
| Object | Condition |
41964196
| ---- | ---- |
41974197
| [Parameter Object](#parameter-object) | When `schema` is present |
4198+
| [Header Object](#header-object) | When `schema` is present |
41984199
| [Encoding Object](#encoding-object) | When encoding for `application/x-www-form-urlencoded` and any of `style`, `explode`, or `allowReserved` are used |
41994200

42004201
Implementations of this specification MAY use an implementation of RFC6570 to perform variable expansion, however, some caveats apply.
@@ -4241,7 +4242,7 @@ parameters:
42414242
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.
42424243
The `&` prefix operator has no equivalent in the Parameter Object.
42434244

4244-
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.
4245+
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.
42454246

42464247
### Delimiters in Parameter Values
42474248

@@ -4332,6 +4333,7 @@ parameters:
43324333
- name: words
43334334
in: query
43344335
style: spaceDelimited
4336+
explode: false
43354337
schema:
43364338
type: array
43374339
items:
@@ -4540,7 +4542,7 @@ However, care must be taken to use `form-urlencoded` decoding if `+` represents
45404542

45414543
### Percent-Encoding and Illegal or Reserved Delimiters
45424544

4543-
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]].
4545+
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]].
45444546
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.
45454547

45464548
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)