3.1.1: port the undisputed parts of #2140

Author: ralfhandl

versions/3.1.1.md

@@ -518,7 +518,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. Use `demo` for a free sandbox environment."
         },
         "port": {
           "enum": ["8443", "443"],
@@ -541,7 +541,7 @@ 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. Use `demo` for a free sandbox environment.
       port:
         enum:
           - '8443'
@@ -561,7 +561,7 @@ An object representing a Server Variable for server URL template substitution.
 | Field Name | Type | Description |
 | ---- | :----: | ---- |
 | <a name="server-variable-enum"></a>enum | [`string`] | An enumeration of string values to be used if the substitution options are from a limited set. The array MUST NOT be empty. |
-| <a name="server-variable-default"></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](#schema-object) treatment of default values, because in those cases parameter values are optional. If the [`enum`](#server-variable-enum) is defined, the value MUST exist in the enum's values. |
+| <a name="server-variable-default"></a>default | `string` | **REQUIRED**. The default value to use for substitution, which SHALL be sent if an alternate value is _not_ supplied. If the [`enum`](#server-variable-enum) is defined, the value MUST exist in the enum's values. Note that this behavior is different from the [Schema Object](#schema-object)'s `default` keyword, which documents the receiver's behavior rather than inserting the value into the data. |
 | <a name="server-variable-description"></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](#specification-extensions).