Clarify server variables (Addresses #1675) #2140
Conversation
…e it clear that the API consumer, not the server, and not an unpecified poltergeist, is responsible for variable interpolation in all cases. The default value of a server variable is to by handled by the consumer (a.k.a. client), who will substitute that value into the URL template unless the client has a some alternative value assigned by user input, configuration, hard-coding, or whatever.
| <a name="serverDescription"></a>description | `string` | An optional string describing the host designated by the URL. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. | ||
| <a name="serverVariables"></a>variables | Map[`string`, [Server Variable Object](#serverVariableObject)] | A map between a variable name and its value. The value is used for substitution in the server's URL template. | ||
| <a name="serverVariables"></a>variables | Map[`string`, [Server Variable Object](#serverVariableObject)] | A map between a server variable name and a Server Variable Object. Each server variable name SHOULD be referenced by a variable expression in the `url`. |
There was a problem hiding this comment.
... not disallowing unused server variables. But server variables don't serve any purpose unless they're used. In an editor, a warning on an unused server variable might alert the user to an oversight, so I thought it'd be useful to note this here, with the SHOULD clause.
There was a problem hiding this comment.
I'd rather not include the last sentence. I don't want to set the precedent that everywhere we have something that can be used we have to state where it can be used.
| An object representing a Server Variable for server URL template substitution. | ||
| An object representing a Server Variable for URL template substitution in a containing [Server Object](#serverObject). | ||
|
|
||
| To form an addressable server URL, the API consumer MUST substitute a valid value for each variable expression in the Server Object's `url` template. The API consumer MAY assign Server Variable values from user input, configuration settings, or any other source. If the API consumer does not have an assigned value for a given server variable, it MUST substitute the provided `default` value. |
There was a problem hiding this comment.
Up-front summary of the basic workings.
There was a problem hiding this comment.
The second paragraph is great content for a best practices documentation. I don't believe the spec the right place to include detailed usage guidance. We need to limit the text to constraints that tooling must/should respect.
| <a name="serverVariableEnum"></a>enum | [`string`] | An enumeration of string values to be used if the substitution options are from a limited set. The array SHOULD NOT be empty. | ||
| <a name="serverVariableDefault"></a>default | `string` | **REQUIRED**. The default value to use for substitution, which SHALL be sent if an alternate value is _not_ supplied. Note this behavior is different than the [Schema Object's](#schemaObject) treatment of default values, because in those cases parameter values are optional. If the [`enum`](#serverVariableEnum) is defined, the value SHOULD exist in the enum's values. | ||
| <a name="serverVariableEnum"></a>enum | [`string`] | Optionally specifies an enumeration of valid string values for this variable. The array SHOULD NOT be empty. If `enum` is specified, the API consumer MUST assign one of enumerated values to the server variable. | ||
| <a name="serverVariableDefault"></a>default | `string` | **REQUIRED**. The default value for the server variable. If [`enum`](#serverVariableEnum) is defined, the `default` value SHOULD exist in the enum's values. If the API consumer does not have an assigned alternative value, it MUST substitute the `default` value. Note that this behavior is different from the [Schema Object's](#schemaObject) treatment of default values. Schema defaults can be resolved by the server, and MAY be omitted from the request; but Server Variables MUST be resolved to an assigned or default value by the client, to assemble a final URL for the API request. |
There was a problem hiding this comment.
The last half of this paragraph, starting with "Note that this behavior..." is a rewrite of the recently added clarification. If anyone feels strongly about it, I am open to any of the following:
- Leave it as-is.
- Move it to the Server Variable Object intro section, appended to the other intro text, just before the Fixed Fields table. That would keep this
defaultfield description short and sweet. - Remove it, as we have already clarified the behavior in other places.
I'm almost completely neutral on this.
Option 1 bothers me slightly because the field description is a little on the long side.
Option 2 bothers me slightly because the clarification is moved away from the default keyword itself, where it would do the most good.
Option 3 bothers me slightly because, while the comparison to JSON Schema's default wasn't what I needed, it probably is exactly what someone else needs in order to understand how this works.
My state of botheredness is in perfect equilibrium, therefore I'm completely neutral.
There was a problem hiding this comment.
If you don't feel strongly, I would go with Option 3. More words without more clarity is usually a net-negative.
| @@ -317,15 +317,15 @@ url: https://www.apache.org/licenses/LICENSE-2.0.html | |||
|
|
|||
| #### <a name="serverObject"></a>Server Object | |||
|
|
|||
| An object representing a Server. | |||
| An object representing a single server or a group of servers sharing a common URL structure. | |||
There was a problem hiding this comment.
In this case Server Object represents a logical origin server, not whether there is one more physical machines. Saying that server could mean one or more is not really adding any clarity in my opinion. Once server variables are resolved it only points to one logical server.
|
|
||
| ##### Fixed Fields | ||
|
|
||
| Field Name | Type | Description | ||
| ---|:---:|--- | ||
| <a name="serverUrl"></a>url | `string` | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the OpenAPI document is being served. Variable substitutions will be made when a variable is named in `{`brackets`}`. | ||
| <a name="serverUrl"></a>url | `string` | **REQUIRED**. A URL to the target host. This URL may include variable expressions, delimited by `{`curly braces`}`. Each variable expression MUST correspond to a [Server Variable Object](#serverVariableObject) named in the `variables` field, and the API consumer MUST replace each variable expression with a with a valid value, as specified by the corresponding Server Variable Object. The URL MAY be relative, to indicate that the host location is relative to the location where the OpenAPI document is being served. |
There was a problem hiding this comment.
We should not talk about how to resolve relative URLs here. We have a dedicated paragraph for that. We could link to it.
|
Closing the PR as this branch has been released and we're deleting it. If needed, please resubmit the PR against the latest dev branch. |
3.0.4: port the undisputed parts of #2140
3.1.1: port the undisputed parts of #2140
This is to address the points of confusion I described in #1675.
Hopefully this makes it clear that the API consumer, not the server, and not an unspecified poltergeist, is responsible for server variable interpolation in all cases. The default value of a server variable is to be handled by the consumer (a.k.a. client), who will substitute that value into the URL template unless the client has some alternative value assigned by user input, configuration, hard-coding, or whatever.
Some notes:
I used the term "variable expressions" for the curly brace-delimited references in a server URL template. I didn't call them "template expressions," which is the recently introduced term used for similar placeholders in Paths Object keys. I thought it might be confusing to have the same term used in both contexts, with different rules and different substitution mechanisms. But I don't mind changing it to "template expressions" if others would prefer that.
I assume that any variable expression occurring in a Server Object
urlMUST be defined in thevariablesmap of that Server Object. If that wasn't then intent, or if there's a real concern about breakage in this 3.0.3 patch release, please speak up.Part of my reasoning is that the Server Object's
defaultfield is required. I assume that's intended to make sure the client always has a default server, which it can derive by substituting all of the default values of all server variables into the server URL template. If the template includes variable expressions that don't resolve to a defined Server Variable, then the client can be stuck with a URL that is unusable without some external configuration or user input. It defeats the default server guarantee.