Merge remote-tracking branch 'refs/remotes/origin/OpenAPI.next' into dm/final-review

Author: darrelmiller

versions/3.0.md

@@ -51,7 +51,6 @@ Additional utilities can also take advantage of the resulting files, such as tes
 		- [Examples Object](#examplesObject)
 		- [Links Object](#linksObject)
 		- [Link Object](#linkObject)
-		- [Variable Substitution](#variableSubstitution)
 		- [Link Parameters Object](#linkParametersObject)
 		- [Header Object](#headerObject)
 		- [Tag Object](#tagObject)
@@ -1877,7 +1876,7 @@ Field Pattern | Type | Description
 The link SHALL reference a single Link Object, or a JSON Reference to a single link object.
 
 
-### <a name="#linkObject"></a>Link Object
+#### <a name="#linkObject"></a>Link Object
 The `Link Object` is responsible for defining a possible operation based on a single response.
 
 Field Name  |  Type  | Description
@@ -1894,13 +1893,13 @@ Locating a linked resource MAY be performed by either a `href` or `operationId`.
 In the case of an `operationId`, it MUST be unique and resolved in the scope of the OAS document.
 Because of the potential for name clashes, consider the `href` syntax as the preferred method for specifications with external references.
 
-#### <a name="responsePayload"></a>Response Payload Values
+##### <a name="responsePayload"></a>Response Payload Values
 
 Payload values are only available in parsable response payloads which match the advertised media type and for media types that can be referenced using a JSON Pointer fragment Id.
 In all cases, if a value does _not_ exist, the parameter will be considered a `null` value (as opposed to an empty value) and _not_ passed as a parameter to the linked resource.
 In cases where a value is required, and a parameter is not supplied, the client MAY choose to not follow the link definition. 
 
-### Example
+##### Example
 
 Response payload:
 ```json
@@ -1939,7 +1938,7 @@ color: ["red", "green", "blue"]
 The variables generated can be used in locations prescribed by the definition.
 
 
-### <a name="variableSubstitution"></a>Variable Substitution
+##### <a name="variableSubstitution"></a>Variable Substitution
 In all cases, _variables_ from request and responses may be substituted for link generation.
 The table below provides examples of variable expressions and examples of their use in a value:
 
@@ -1975,7 +1974,7 @@ The variable expression is defined by the following [ABNF](https://tools.ietf.or
 The `name` identifier is case-sensitive, whereas `token` is not. 
 
 
-### Request Parameter Example
+##### Request Parameter Example
 Computing a link from a request operation like such:
 
 ```yaml
@@ -2015,7 +2014,7 @@ For a `id` value of `10101110`, the generated link would be:
 href: '/users/10101110/department'
 ```
 
-### Response Payload Example
+##### Response Payload Example
 
 ```yaml
 Addresses:
@@ -2047,7 +2046,7 @@ href: 'http://colors.my-server.com/colors/blue'
 As with all links, it at the the clients' discretion to follow them, and permissions and the ability to make a successful call to that link is not guaranteed solely by the existence of a relationship.
 
 
-### Example
+##### Example
 
 The example below shows how relationships in the BitBucket API can be represented with the link schema. This example uses `operationId` values to link responses to possible operations.
 
@@ -2260,7 +2259,7 @@ components:
 ```
 
 
-### <a name="linkParametersObject"></a>Link Parameters Object
+#### <a name="linkParametersObject"></a>Link Parameters Object
 Using the `operationId` to reference an operation in the definition has many benefits, including the ability to define media type options, security requirements, response and error payloads.
 Many operations require parameters to be passed, and these MAY be dynamic depending on the response itself.