Skip to content

v3.1: parameter style amendments #5093

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Nov 2, 2025
+10 −7
Merged

v3.1: parameter style amendments #5093

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
fb5f5a4
fixes to examples of template expansion of undefined (null) values
karenetheridge Oct 28, 2025
40e4da0
provide an example of a prohibited use of "/" in the template
karenetheridge Oct 28, 2025
7829aed
punctuation
karenetheridge Oct 28, 2025
d17c1f8
remove invalid example
karenetheridge Oct 28, 2025
b044e33
clarify wording
karenetheridge Oct 28, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 10 additions & 7 deletions src/oas.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -1236,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.
Expand All @@ -1253,12 +1255,13 @@ 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 }
```

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.
Expand All @@ -1268,10 +1271,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 | <span style="white-space: nowrap;">color=</span> | <span style="white-space: nowrap;">color=blue</span> | <span style="white-space: nowrap;">color=blue,black,brown</span> | <span style="white-space: nowrap;">color=R,100,G,200,B,150</span> |
Expand Down Expand Up @@ -2541,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
Expand Down