Merge pull request OAI#944 from OAI/server-template

Updated server templates, all things relative

Author: webron

versions/3.0.md

@@ -31,9 +31,11 @@ Additional utilities can also take advantage of the resulting files, such as tes
 	- [Schema](#schema)
 		- [OpenAPI Object](#oasObject)
 		- [Info Object](#infoObject)
-			- [Contact Object](#contactObject)
-			- [License Object](#licenseObject)
+		- [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)
@@ -162,9 +164,9 @@ password | `string` | `password` | Used to hint UIs the input needs to be obscur
 ### <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