Skip to content

Commit 99e5ce0

Browse files
committed
Clarify template variable uniqueness
This clarifies that variables in both path and server URL templates MUST be unique. This is justified as compatible with our minor release policy on the following grounds: * Due to Parameter Object `name` + `in` constraints and the Server Object's `variables` field being a map, each variable can only map to one paramater or server variable (although the "one" paramater might be defined separately yet uniquely for each Operation). * The Path Templating section uses the phrase "Each template expression in the path MUST correspond to ***a*** path parameter" (emphasis added). * The Parameter Object uses similar language in the other direction: "If in is "path", the name field MUST correspond to ***a*** template expression". * The word "a" is interpreted to mean an unknown but unique thing in both directions. * The Server Object's `url` template has always been assumed to function in an analogous way to path templating.
1 parent b19e612 commit 99e5ce0

File tree

1 file changed

+5
-1
lines changed

1 file changed

+5
-1
lines changed

src/oas.md

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,8 @@ sub-delims = "!" / "$" / "&" / "'" / "(" / ")"
6262

6363
Here, `pchar`, `unreserved`, `pct-encoded` and `sub-delims` definitions are taken from [RFC 3986](https://tools.ietf.org/html/rfc3986). The `path-template` is directly derived from [RFC 3986, section 3.3](https://datatracker.ietf.org/doc/html/rfc3986#section-3.3).
6464

65+
Each template expression MUST NOT appear more than once in a single path template.
66+
6567
See also [Appendix C: Using RFC6570-Based Serialization](#appendix-c-using-rfc6570-based-serialization) for additional guidance.
6668

6769
### Media Types
@@ -596,6 +598,8 @@ iprivate = %xE000-F8FF / %xF0000-FFFFD / %x100000-10FFFD
596598

597599
Here, `literals`, `pct-encoded`, `ucschar` and `iprivate` definitions are taken from [RFC 6570](https://www.rfc-editor.org/rfc/rfc6570), incorporating the corrections specified in [Errata 6937](https://www.rfc-editor.org/errata/eid6937) for `literals`.
598600

601+
Each server variable MUST NOT appear more than once in the URL template.
602+
599603
See the [Paths Object](#paths-object) for guidance on constructing full request URLs.
600604

601605
##### Fixed Fields
@@ -967,7 +971,7 @@ These fields MAY be used with either `content` or `schema`.
967971

968972
| Field Name | Type | Description |
969973
| ---- | :----: | ---- |
970-
| <a name="parameter-name"></a>name | `string` | **REQUIRED**. The name of the parameter. Parameter names are _case sensitive_. <ul><li>If [`in`](#parameter-in) is `"path"`, the `name` field MUST correspond to a template expression occurring within the [path](#paths-path) field in the [Paths Object](#paths-object). See [Path Templating](#path-templating) for further information.<li>If [`in`](#parameter-in) is `"header"` and the `name` field is `"Accept"`, `"Content-Type"` or `"Authorization"`, the parameter definition SHALL be ignored.<li>If `in` is `"querystring"`, or for [certain combinations](#style-examples) of [`style`](#parameter-style) and [`explode`](#parameter-explode), the value of `name` is not used in the parameter serialization.<li>For all other cases, the `name` corresponds to the parameter name used by the [`in`](#parameter-in) field.</ul> |
974+
| <a name="parameter-name"></a>name | `string` | **REQUIRED**. The name of the parameter. Parameter names are _case sensitive_. <ul><li>If [`in`](#parameter-in) is `"path"`, the `name` field MUST correspond to a single template expression occurring within the [path](#paths-path) field in the [Paths Object](#paths-object). See [Path Templating](#path-templating) for further information.<li>If [`in`](#parameter-in) is `"header"` and the `name` field is `"Accept"`, `"Content-Type"` or `"Authorization"`, the parameter definition SHALL be ignored.<li>If `in` is `"querystring"`, or for [certain combinations](#style-examples) of [`style`](#parameter-style) and [`explode`](#parameter-explode), the value of `name` is not used in the parameter serialization.<li>For all other cases, the `name` corresponds to the parameter name used by the [`in`](#parameter-in) field.</ul> |
971975
| <a name="parameter-in"></a>in | `string` | **REQUIRED**. The ___location of the parameter. Possible values are `"query"`, `"querystring"`, `"header"`, `"path"` or `"cookie"`. |
972976
| <a name="parameter-description"></a>description | `string` | A brief description of the parameter. This could contain examples of use. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. |
973977
| <a name="parameter-required"></a>required | `boolean` | Determines whether this parameter is mandatory. If the [parameter ___location](#parameter-in) is `"path"`, this field is **REQUIRED** and its value MUST be `true`. Otherwise, the field MAY be included and its default value is `false`. |

0 commit comments

Comments
 (0)