From 3ee24a75ae974393a464bbe491abed0255bb3c3e Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Wed, 11 Sep 2024 09:01:42 -0700 Subject: [PATCH 1/2] 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. --- versions/3.0.4.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/versions/3.0.4.md b/versions/3.0.4.md index 46005e9eb7..e5f112c268 100644 --- a/versions/3.0.4.md +++ b/versions/3.0.4.md @@ -3789,7 +3789,7 @@ security: See [Resolving Implicit Connections](#resolving-implicit-connections) for more information. -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: +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: ```HTTP GET /api/description/openapi HTTP/1.1 @@ -3832,7 +3832,7 @@ paths: $ref: 'other#/components/pathItems/Foo' ``` -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: +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: ```HTTP GET /api/description/other HTTP/1.1 @@ -3985,11 +3985,12 @@ Requiring input as pre-formatted, schema-validated strings also improves round-t ## Appendix C: Using RFC6570 Implementations -Serialization is defined in terms of [RFC6570](https://www.rfc-editor.org/rfc/rfc6570) URI Templates in two scenarios: +Serialization is defined in terms of [RFC6570](https://www.rfc-editor.org/rfc/rfc6570) URI Templates in three scenarios: | Object | Condition | | ---- | ---- | | [Parameter Object](#parameter-object) | When `schema` is present | +| [Header Object](#header-object) | When `schema` is present | | [Encoding Object](#encoding-object) | When encoding for `application/x-www-form-urlencoded` and any of `style`, `explode`, or `allowReserved` are used | Implementations of this specification MAY use an implementation of RFC6570 to perform variable expansion, however, some caveats apply. @@ -4032,7 +4033,7 @@ parameters: 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. The `&` prefix operator has no equivalent in the Parameter Object. -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. +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. ### Non-RFC6570 Field Values and Combinations @@ -4114,6 +4115,7 @@ parameters: - name: words in: query style: spaceDelimited + explode: false schema: type: array items: @@ -4321,7 +4323,7 @@ However, care must be taken to use `form-urlencoded` decoding if `+` represents ### Percent-Encoding and Illegal or Reserved Delimiters -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]]. +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]]. 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. The space character is always illegal and encoded in some way by all implementations of all versions of the relevant standards. From af8f02c52cea1d8e0dc1cf326d2e2629d7f0711e Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Wed, 11 Sep 2024 20:11:02 -0700 Subject: [PATCH 2/2] Don't use both bold and italics Style guide conformance. --- versions/3.0.4.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.0.4.md b/versions/3.0.4.md index e5f112c268..b2d9e4cccb 100644 --- a/versions/3.0.4.md +++ b/versions/3.0.4.md @@ -4030,7 +4030,7 @@ parameters: type: string ``` -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. +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. The `&` prefix operator has no equivalent in the Parameter Object. 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.