From d2a6d082793583fbdb43e09d4fcfeba607285cfb Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Fri, 11 Jul 2025 16:58:05 -0700 Subject: [PATCH 1/2] Explain Param and Header example serialization The rules for this have not been clear, and are not always intuitive. This states and explains them directly and ensures that the Style Examples table matches the rules. Unlike past efforts, this provides a rule system regarding what is and is not included, based on a combination of what is produced by RFC6570 (or the nearest RFC6570 equivalent), modified by removing leading delimiters that are not correct for our usage due to differences from the assuptions made by RFC6570. This also shows some uses of the new Example Object fields, including some that would be redundant but are included to clarify the different options; the redundancy is noted in the text. --- src/oas.md | 36 +++++++++++++++++++++++++++--------- 1 file changed, 27 insertions(+), 9 deletions(-) diff --git a/src/oas.md b/src/oas.md index 985304f993..d5998deb40 100644 --- a/src/oas.md +++ b/src/oas.md @@ -1030,9 +1030,28 @@ In order to support common ways of serializing simple parameters, a set of `styl 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. +##### Serialization and Examples + +The rules in this section apply to both the Parameter and [Header](#header-object) Objects, both of which use the same mechanisms. + +When showing serialized examples, such as with the [Example Object's](#example-object) `serializedValue` or `externalValue` fields, in most cases the value to show is just the value, with all relevant percent-encoding or other encoding/escaping applied, and also including any delimiters produced by the `style` and `explode` configuration. + +In cases where the name is an inherent part of constructing the serialization, such as the `name=value` pairs produced by `style: "form"` or the combination of `style: "simple", explode: true`, the name and any delimiter between the name and value MUST be included. + +The `matrix` and `label` styles produce a leading delimiter which is always a valid part of the serialization and MUST be included. +The RFC6570 operators corresponding to `style: "form"` produces a leading delimiter of either `?` or `&` depending on the exact syntax used. +As the suitability of either delimiter depends on where in the query string the parameter occurs, as well as whether it is in a URI or in `application/x-www-form-urlencoded` content, this leading delimiter MUST NOT be included in examples of individual parameters or media type documents. +For `in: "cookie", style: "form"`, neither the `&` nor `?` delimiters are ever correct; see [Appendix D: Serializing Headers and Cookies](#appendix-d-serializing-headers-and-cookies) for more details. + +For headers, the header name MUST NOT be included as part of the serialization, as it is never part of the RFC6570-derived result. +However, names produced by `style: "simple", explode: "true"` are included as they appear within the header value, not as separate headers. +See the [Header Object](#header-object) for special rules for showing examples of the `Set-Cookie` response header, which violates the normal rules for multiple header values. + +The following section illustrates these rules. + ##### Style Examples -Assume a parameter named `color` has one of the following values: +Assume a parameter named `color` has one of the following values, where the value to the right of the `->` is what would be shown in the `dataValue` field of an Example Object: ```js string -> "blue" @@ -1040,13 +1059,12 @@ Assume a parameter named `color` has one of the following values: object -> { "R": 100, "G": 200, "B": 150 } ``` -The following table shows examples, as would be shown with the `example` or `examples` keywords, of the different serializations for each value. +The following table shows serialized examples, as would be shown with the `serializedValue` field of an Example Object, of the different serializations for each value. * The value _empty_ denotes the empty string, and is unrelated to the `allowEmptyValue` field * The behavior of combinations marked _n/a_ is undefined * The `undefined` column replaces the `empty` column in previous versions of this specification in order to better align with [RFC6570](https://www.rfc-editor.org/rfc/rfc6570.html#section-2.3) terminology, which describes certain values including but not limited to `null` as "undefined" values with special handling; notably, the empty string is _not_ undefined -* For `form` and the non-RFC6570 query string styles `spaceDelimited`, `pipeDelimited`, and `deepObject`, each example is shown prefixed with `?` as if it were the only query parameter; see [Appendix C](#appendix-c-using-rfc6570-based-serialization) for more information on constructing query strings from multiple parameters, and [Appendix D](#appendix-d-serializing-headers-and-cookies) for warnings regarding `form` and cookie parameters -* Note that the `?` prefix is not appropriate for serializing `application/x-www-form-urlencoded` HTTP message bodies, and MUST be stripped or (if constructing the string manually) not added when used in that context; see the [Encoding Object](#encoding-object) for more information +* For `form` and the non-RFC6570 query string styles `spaceDelimited`, `pipeDelimited`, and `deepObject`, see [Appendix C](#appendix-c-using-rfc6570-based-serialization) for more information on constructing query strings from multiple parameters, and [Appendix D](#appendix-d-serializing-headers-and-cookies) for warnings regarding `form` and cookie parameters * The examples are percent-encoded as required by RFC6570 and RFC3986; see [Appendix E](#appendix-e-percent-encoding-and-form-media-types) for a thorough discussion of percent-encoding concerns, including why unencoded `|` (`%7C`), `[` (`%5B`), and `]` (`%5D`) seem to work in some environments despite not being compliant. | [`style`](#style-values) | `explode` | `undefined` | `string` | `array` | `object` | @@ -1057,14 +1075,14 @@ The following table shows examples, as would be shown with the `example` or `exa | label | true | . | .blue | .blue.black.brown | .R=100.G=200.B=150 | | simple | false | _empty_ | blue | blue,black,brown | R,100,G,200,B,150 | | simple | true | _empty_ | blue | blue,black,brown | R=100,G=200,B=150 | -| form | false | ?color= | ?color=blue | ?color=blue,black,brown | ?color=R,100,G,200,B,150 | -| form | true | ?color= | ?color=blue | ?color=blue&color=black&color=brown | ?R=100&G=200&B=150 | -| spaceDelimited | false | _n/a_ | _n/a_ | ?color=blue%20black%20brown | ?color=R%20100%20G%20200%20B%20150 | +| form | false | color= | color=blue | color=blue,black,brown | color=R,100,G,200,B,150 | +| form | true | color= | color=blue | color=blue&color=black&color=brown | R=100&G=200&B=150 | +| spaceDelimited | false | _n/a_ | _n/a_ | color=blue%20black%20brown | color=R%20100%20G%20200%20B%20150 | | spaceDelimited | true | _n/a_ | _n/a_ | _n/a_ | _n/a_ | -| pipeDelimited | false | _n/a_ | _n/a_ | ?color=blue%7Cblack%7Cbrown | ?color=R%7C100%7CG%7C200%7CB%7C150 | +| pipeDelimited | false | _n/a_ | _n/a_ | color=blue%7Cblack%7Cbrown | color=R%7C100%7CG%7C200%7CB%7C150 | | pipeDelimited | true | _n/a_ | _n/a_ | _n/a_ | _n/a_ | | deepObject | false | _n/a_ | _n/a_ | _n/a_ | _n/a_ | -| deepObject | true | _n/a_ | _n/a_ | _n/a_ | ?color%5BR%5D=100&color%5BG%5D=200&color%5BB%5D=150 | +| deepObject | true | _n/a_ | _n/a_ | _n/a_ | color%5BR%5D=100&color%5BG%5D=200&color%5BB%5D=150 | ##### Extending Support for Querystring Formats From af2a5a83269aa036e95bf5f00848f1cf08f54e3d Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Sun, 20 Jul 2025 08:32:17 -0700 Subject: [PATCH 2/2] Fix grammar Co-authored-by: Ralf Handl --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index d5998deb40..19d1727401 100644 --- a/src/oas.md +++ b/src/oas.md @@ -1039,7 +1039,7 @@ When showing serialized examples, such as with the [Example Object's](#example-o In cases where the name is an inherent part of constructing the serialization, such as the `name=value` pairs produced by `style: "form"` or the combination of `style: "simple", explode: true`, the name and any delimiter between the name and value MUST be included. The `matrix` and `label` styles produce a leading delimiter which is always a valid part of the serialization and MUST be included. -The RFC6570 operators corresponding to `style: "form"` produces a leading delimiter of either `?` or `&` depending on the exact syntax used. +The RFC6570 operators corresponding to `style: "form"` produce a leading delimiter of either `?` or `&` depending on the exact syntax used. As the suitability of either delimiter depends on where in the query string the parameter occurs, as well as whether it is in a URI or in `application/x-www-form-urlencoded` content, this leading delimiter MUST NOT be included in examples of individual parameters or media type documents. For `in: "cookie", style: "form"`, neither the `&` nor `?` delimiters are ever correct; see [Appendix D: Serializing Headers and Cookies](#appendix-d-serializing-headers-and-cookies) for more details.