Fixes OAI#1675. Clarifies the language around server variables to make 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.

Author: tedepstein

versions/3.0.3.md

@@ -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.
 
 ##### 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.
 <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`.
 
 This object MAY be extended with [Specification Extensions](#specificationExtensions).
 
@@ -387,7 +387,7 @@ The following shows how variables can be used for a server configuration:
       "variables": {
         "username": {
           "default": "demo",
-          "description": "this value is assigned by the service provider, in this example `gigantic-server.com`"
+          "description": "A user-specific subdomain provisioned for each account. Use `demo` for a free sandbox environment."
         },
         "port": {
           "enum": [
@@ -413,7 +413,9 @@ servers:
     username:
       # note! no enum here means it is an open value
       default: demo
-      description: this value is assigned by the service provider, in this example `gigantic-server.com`
+      description: |
+        A user-specific subdomain provisioned for each account.
+        Use `demo` for a free sandbox environment.
     port:
       enum:
         - '8443'
@@ -427,14 +429,16 @@ servers:
 
 #### <a name="serverVariableObject"></a>Server Variable Object
 
-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.
 
 ##### Fixed Fields
 
 Field Name | Type | Description
 ---|:---:|---
-<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`] | 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 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.
 <a name="serverVariableDescription"></a>description | `string` | An optional description for the server variable. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
 
 This object MAY be extended with [Specification Extensions](#specificationExtensions).