Merge pull request OAI#881 from OAI/dm/relative-url

Added clarification on the use of relative references in URLs

Author: darrelmiller

versions/3.0.md

@@ -26,6 +26,7 @@ Additional utilities can also take advantage of the resulting files, such as tes
 	- [Format](#format)
 	- [File Structure](#file-structure)
 	- [Data Types](#data-types)
+  - [Relative References In Urls](#relativeReferences)
 	- [Schema](#schema)
 		- [OpenAPI Object](#openapi-object)
 		- [Info Object](#info-object)
@@ -167,6 +168,13 @@ 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
+
+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 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.     
+
 ### Schema
 
 #### <a name="oasObject"></a>OpenAPI Object
@@ -315,7 +323,7 @@ An object representing a Server.
 
 Field Name | Type | Description
 ---|:---:|---
-<a name="serverUrlTemplate"></a>url | `string` | A 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="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