Skip to content

Commit 3ee24a7

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 d1ba364 commit 3ee24a7

File tree

1 file changed

+7
-5
lines changed

1 file changed

+7
-5
lines changed

versions/3.0.4.md

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

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

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:
3792+
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:
37933793

37943794
```HTTP
37953795
GET /api/description/openapi HTTP/1.1
@@ -3832,7 +3832,7 @@ paths:
38323832
$ref: 'other#/components/pathItems/Foo'
38333833
```
38343834

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:
3835+
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:
38363836

38373837
```HTTP
38383838
GET /api/description/other HTTP/1.1
@@ -3985,11 +3985,12 @@ Requiring input as pre-formatted, schema-validated strings also improves round-t
39853985

39863986
## Appendix C: Using RFC6570 Implementations
39873987

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

39903990
| Object | Condition |
39913991
| ---- | ---- |
39923992
| [Parameter Object](#parameter-object) | When `schema` is present |
3993+
| [Header Object](#header-object) | When `schema` is present |
39933994
| [Encoding Object](#encoding-object) | When encoding for `application/x-www-form-urlencoded` and any of `style`, `explode`, or `allowReserved` are used |
39943995

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

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.
4036+
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.
40364037

40374038
### Non-RFC6570 Field Values and Combinations
40384039

@@ -4114,6 +4115,7 @@ parameters:
41144115
- name: words
41154116
in: query
41164117
style: spaceDelimited
4118+
explode: false
41174119
schema:
41184120
type: array
41194121
items:
@@ -4321,7 +4323,7 @@ However, care must be taken to use `form-urlencoded` decoding if `+` represents
43214323

43224324
### Percent-Encoding and Illegal or Reserved Delimiters
43234325

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]].
4326+
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]].
43254327
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.
43264328

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