From fb5f5a497b847a93cb3f60317be3b2d25387bd27 Mon Sep 17 00:00:00 2001 From: Karen Etheridge Date: Tue, 28 Oct 2025 12:34:04 -0700 Subject: [PATCH 1/5] fixes to examples of template expansion of undefined (null) values RFC6570 section 3.2.1 says: "A variable that is undefined (Section 2.3) has no value and is ignored by the expansion process. If all of the variables in an expression are undefined, then the expression's expansion is the empty string." ..therefore the provided examples for the "matrix" and "label" styles are incorrect -- the full expansion is the empty string, with no leader/prefix. --- src/oas.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/src/oas.md b/src/oas.md index 1440db924e..6e17d0c759 100644 --- a/src/oas.md +++ b/src/oas.md @@ -1253,6 +1253,7 @@ The following section illustrates these rules. Assume a parameter named `color` has one of the following values: ```js + undefined -> null string -> "blue" array -> ["blue", "black", "brown"] object -> { "R": 100, "G": 200, "B": 150 } @@ -1268,10 +1269,10 @@ The following table shows serialized examples, as would be shown with the `examp | [`style`](#style-values) | `explode` | `undefined` | `string` | `array` | `object` | | ---- | ---- | ---- | ---- | ---- | ---- | -| matrix | false | ;color | ;color=blue | ;color=blue,black,brown | ;color=R,100,G,200,B,150 | -| matrix | true | ;color | ;color=blue | ;color=blue;color=black;color=brown | ;R=100;G=200;B=150 | -| label | false | . | .blue | .blue,black,brown | .R,100,G,200,B,150 | -| label | true | . | .blue | .blue.black.brown | .R=100.G=200.B=150 | +| matrix | false | _empty_ | ;color=blue | ;color=blue,black,brown | ;color=R,100,G,200,B,150 | +| matrix | true | _empty_ | ;color=blue | ;color=blue;color=black;color=brown | ;R=100;G=200;B=150 | +| label | false | _empty_ | .blue | .blue,black,brown | .R,100,G,200,B,150 | +| label | true | _empty_ | .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 | From 40e4da0c9231f7a5fa53e2b21f141c568723cdb7 Mon Sep 17 00:00:00 2001 From: Karen Etheridge Date: Tue, 28 Oct 2025 12:36:57 -0700 Subject: [PATCH 2/5] provide an example of a prohibited use of "/" in the template --- src/oas.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/oas.md b/src/oas.md index 6e17d0c759..e3d300d798 100644 --- a/src/oas.md +++ b/src/oas.md @@ -43,6 +43,8 @@ Path templating refers to the usage of template expressions, delimited by curly Each template expression in the path MUST correspond to a path parameter that is included in the [Path Item](#path-item-object) itself and/or in each of the Path Item's [Operations](#operation-object). An exception is if the path item is empty, for example due to ACL constraints, matching path parameters are not required. The value for these path parameters MUST NOT contain any unescaped "generic syntax" characters described by [RFC3986](https://tools.ietf.org/html/rfc3986#section-3): forward slashes (`/`), question marks (`?`), or hashes (`#`). +This means that when matching templates to request URLs, no values that include a forward slash are matched. +For example, the template `/foo/{bar}` cannot match the URI path "/foo/alpha/beta" because the value of the template variable "bar" would have to be "alpha/beta". See [URL Percent-Encoding](#url-percent-encoding) for additional guidance on escaping characters. ### Media Types From 7829aed240a9bb0eae50beefff392e9bf5dc48f6 Mon Sep 17 00:00:00 2001 From: Karen Etheridge Date: Tue, 28 Oct 2025 12:37:55 -0700 Subject: [PATCH 3/5] punctuation --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index e3d300d798..4f9a7377e9 100644 --- a/src/oas.md +++ b/src/oas.md @@ -2544,7 +2544,7 @@ The unescaped, percent-decoded path template in the above examples would be `/2. Runtime expressions allow defining values based on information that will only be available within the HTTP message in an actual API call. This mechanism is used by [Link Objects](#link-object) and [Callback Objects](#callback-object). -The runtime expression is defined by the following [ABNF](https://tools.ietf.org/html/rfc5234) syntax +The runtime expression is defined by the following [ABNF](https://tools.ietf.org/html/rfc5234) syntax: ```abnf expression = "$url" / "$method" / "$statusCode" / "$request." source / "$response." source From d17c1f8764438d711c02b38b9d783ebdbf94cc4d Mon Sep 17 00:00:00 2001 From: Karen Etheridge Date: Tue, 28 Oct 2025 12:38:31 -0700 Subject: [PATCH 4/5] remove invalid example Expansions using "style": "simple", "explode": true do not include the parameter name in the expansion. --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index 4f9a7377e9..adb486016f 100644 --- a/src/oas.md +++ b/src/oas.md @@ -1238,7 +1238,7 @@ The rules in this section apply to both the Parameter and [Header](#header-objec When showing serialized examples using the `example` field or [Example Objects](#example-object), 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. +In cases where the parameter name is an inherent part of constructing the serialization, such as the `name=value` pairs produced by the combination of `style: "form", explode: false`, 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"` produce a leading delimiter of either `?` or `&` depending on the exact syntax used. From b044e33b76ab9fc8d7c535db96fa338dfd28817f Mon Sep 17 00:00:00 2001 From: Karen Etheridge Date: Tue, 28 Oct 2025 12:40:35 -0700 Subject: [PATCH 5/5] clarify wording --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index adb486016f..b81e67fe8b 100644 --- a/src/oas.md +++ b/src/oas.md @@ -1261,7 +1261,7 @@ Assume a parameter named `color` has one of the following values: object -> { "R": 100, "G": 200, "B": 150 } ``` -The following table shows serialized 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 `example` or `examples` keywords, of the different serializations for the value of each supported type. * The value _empty_ denotes the empty string, and is unrelated to the `allowEmptyValue` field. * The behavior of combinations marked _n/a_ is undefined.