From 90a9ab974435a1139dbbc9b4344ea289a118c3d2 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 021f5fa011..64dbf4a493 100644 --- a/src/oas.md +++ b/src/oas.md @@ -898,6 +898,7 @@ See the [Header Object](#header-object) for special rules for showing examples o 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 + undefined -> null string -> "blue" array -> ["blue", "black", "brown"] object -> { "R": 100, "G": 200, "B": 150 } @@ -913,10 +914,10 @@ The following table shows serialized examples, as would be shown with the `seria | [`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 657e32e95ae1f4122e0b9b5023da9cc1910e2de0 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 | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src/oas.md b/src/oas.md index 64dbf4a493..2f4e6d1a53 100644 --- a/src/oas.md +++ b/src/oas.md @@ -519,6 +519,9 @@ 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. The path templating is defined by the following [ABNF](https://tools.ietf.org/html/rfc5234) syntax From facfec37a7316159ab9b06da5ede9b964219bcac 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 | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/oas.md b/src/oas.md index 2f4e6d1a53..46b76da897 100644 --- a/src/oas.md +++ b/src/oas.md @@ -353,7 +353,7 @@ servers: An object representing a Server Variable for server URL template substitution. -The server URL templating is defined by the following [ABNF](https://tools.ietf.org/html/rfc5234) syntax. +The server URL templating is defined by the following [ABNF](https://tools.ietf.org/html/rfc5234) syntax: ```abnf server-url-template = 1*( literals / server-variable ) @@ -524,7 +524,7 @@ For example, the template `/foo/{bar}` cannot match the URI path "/foo/alpha/bet See [URL Percent-Encoding](#url-percent-encoding) for additional guidance on escaping characters. -The path templating is defined by the following [ABNF](https://tools.ietf.org/html/rfc5234) syntax +The path templating is defined by the following [ABNF](https://tools.ietf.org/html/rfc5234) syntax: ```abnf path-template = "/" *( path-segment "/" ) [ path-segment ] @@ -2615,7 +2615,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 39ef8583d7c572299d62aa58a6a771c6ebcc2521 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 46b76da897..013e68af34 100644 --- a/src/oas.md +++ b/src/oas.md @@ -885,7 +885,7 @@ The rules in this section apply to both the Parameter and [Header](#header-objec 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. +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 e21a0f9a4e9573b0bdb7a920e201158947fb6f4a 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 013e68af34..199b928753 100644 --- a/src/oas.md +++ b/src/oas.md @@ -907,7 +907,7 @@ Assume a parameter named `color` has one of the following values, where the valu object -> { "R": 100, "G": 200, "B": 150 } ``` -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 following table shows serialized examples, as would be shown with the `serializedValue` field of an Example Object, 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.