From 9307120e5eae34be4408f846544b3f2e1697f0b5 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 659234f72f..6e41ebe98f 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 53dbc0ea659f3a37435b48a1ce6f1718f84eaa1f 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 6e41ebe98f..d19bea0330 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 dab97eda06f85f9d794852c340cd4d6af51b2a21 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 d19bea0330..99154905bc 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 2e3592339930a34bdf06cc6f7b990db542b52caa 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 99154905bc..8584a34d7a 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 bd97d2e0b6375ee476aef381e03ae681e227bd2b 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 8584a34d7a..da5374a3c3 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.