Fixed server templates and all things relative
MODIFY
versions/3.0.md
versions/3.0.md
@@ -34,6 +34,8 @@ Additional utilities can also take advantage of the resulting files, such as tes
- [Contact Object](#contactObject)
- [License Object](#licenseObject)
- [Server Object](#serverObject)
+ - [Server Variables Object](#serverVariablesObject)
+ - [Server Variable Object](#serverVariableObject)
- [Components Object](#componentsObject)
- [Paths Object](#pathsObject)
- [Path Item Object](#pathItemObject)
@@ -159,12 +161,12 @@ date | `string` | `date` | As defined by `full-date` - [RFC3339](http://xml2rfc.
dateTime | `string` | `date-time` | As defined by `date-time` - [RFC3339](http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14)
password | `string` | `password` | Used to hint UIs the input needs to be obscured.
-### <a name="relativeReferences"></a>Relative References In URLs
+### <a name="relativeReferences"></a>Relative References in URLs
Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC 3986](https://tools.ietf.org/html/rfc3986#section-4.2).
-Relative references are resolved using the URLs defined in the [Servers array](#servers) as a Base URI.
+Relative references are resolved using the URLs defined in the [`Server Object`](#serverObject) as a Base URI.
-Relative references used in $ref are processed as per [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03), i.e. using the URL of the current document as the base URI.
+Relative references used in `$ref` are processed as per [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03), i.e. using the URL of the current document as the base URI. See also the [Reference Object](#referenceObject).
### Schema
@@ -317,9 +319,9 @@ An object representing a Server.
Field Name | Type | Description
---|:---:|---
-<a name="serverUrlTemplate"></a>url | `string` | A absolute URL to the target host. This URL supports template variables and may be relative, to indicate that the host location is relative to the location where the OpenAPI Specification is being served. Templates are _optional_ and specified by the [Host Template Parameter](#hostTemplateParameter) syntax. Template substitutions will be made when a variable is named in `{`brackets`}`.
-<a name="hostDescription"></a>description | `string` | An optional string describing the host designated by the URL.
-<a name="hostTemplates"></a>templates | [Templates Object](#hostTemplatesObject) | An object holding templates for substitution in the URL template
+<a name="serverUrl"></a>url | `string` | 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 definition is being served. Variable substitutions will be made when a variable is named in `{`brackets`}`.
+<a name="serverDescription"></a>description | `string` | An optional string describing the host designated by the URL.
+<a name="serverVariables"></a>variables | [Server Variables Object](#serverVariablesObject) | An object holding variables for substitution in the URL template.
This object can be extended with [Specification Extensions](#specificationExtensions).
@@ -344,13 +346,13 @@ servers:
description: Production server
```
-The following shows how templates can be used for a server configuration:
+The following shows how variables can be used for a server configuration:
```yaml
servers:
- url: https://{username}.gigantic-server.com:{port}/{basePath}
description: The production API server
- templates:
+ variables:
username:
# note! no enum here means it is an open value
default: demo
@@ -365,26 +367,26 @@ servers:
default: v2
```
-#### <a name="hostTemplatesObject"></a>Host Templates Object
+#### <a name="serverVariablesObject"></a>Server Variables Object
##### Patterned Fields
Field Pattern | Type | Description
---|:---:|---
-<a name="variable"></a> [variable name] | [Host Template Parameter](#hostTemplateParameter) | A parameter to be used for substitution in the URL template.
+<a name="serverVariablesName"></a> {name} | [Server Variable Object](#serverVariableObject) | A variable to be used for substitution in a Server's URL template.
This object can be extended with [Specification Extensions](#specificationExtensions).
-#### <a name="hostTemplateParameter"></a>Host Template
+#### <a name="serverVariableObject"></a>Server Variable Object
-An object representing a Host URL template
+An object representing a Server Variable for server URL template substituion.
Field Name | Type | Description
---|:---:|---
-enum | [Possible Values] | An enumeration of primitive type values to be used if the substitution options are from a limited set.
-default | [Default Value] | **Required.** The default value to use for substitution if an alternate value is not specified, and will be sent if an alternative value is _not_ supplied.
-description | `string` | An optional description for the template parameter
+<a name="serverVariableEnum"></a>enum | [ `primitive` ] | An enumeration of primitive type values to be used if the substitution options are from a limited set.
+<a name="serverVariableDefault"></a>default | `primitive` | **Required.** The default value to use for substitution if an alternate value is not specified, and will be sent if an alternative value is _not_ supplied. Unlike the [Schema Object's](#schemaObject) `default`, this value MUST be provided by the consumer.
+<a name="serverVariableDescription"></a>description | `string` | An optional description for the server variable.
This object can be extended with [Specification Extensions](#specificationExtensions).
@@ -580,8 +582,7 @@ components:
#### <a name="pathsObject"></a>Paths Object
Holds the relative paths to the individual endpoints and their operations.
-The path is appended to the URL from the [`Server Object`](#serverObject) in order to construct
-the full URL. The Paths MAY be empty, due to [ACL constraints](#securityFiltering).
+The path is appended to the URL from the [`Server Object`](#serverObject) in order to construct the full URL. The Paths MAY be empty, due to [ACL constraints](#securityFiltering).
##### Patterned Fields

Fixed server templates and all things relative