Fixes to callback objects, components and references

Author: darrelmiller

versions/3.0.md

@@ -392,10 +392,10 @@ Field Pattern | Type | Description
 <a name="componentsParameters"></a> parameters | Map[`string`, [Parameter Object](#parameterObject)] | An object to hold reusable [Parameter Objects](#parameterObject).
 <a name="componentsExamples"></a> examples | Map[`string`, [Example Object](#exampleObject)] | An object to hold reusable [Example Objects](#exampleObject).
 <a name="componentsRequestBodies"></a> requestBodies | Map[`string`, [RequestBody Object](#requestBodyObject)] | An object to hold reusable [RequestBody objects](#requestBodyObject).
-<a name="componentsResponseHeaders"></a> responseHeaders | Map[`string`, [Response Header object](#headersObject)] | An object to hold reusable [Response Headers objects](#headersObject).
+<a name="componentsHeaders"></a> headers | Map[`string`, [Header object](#headerObject)] | An object to hold reusable [Header objects](#headerObject).
 <a name="componentsSecurityDefinitions"></a> securityDefinitions| Map[`string`, [Security Scheme object](#securitySchemeObject)] | An object to hold reusable [Security Scheme objects](#securitySchemeObject).
 <a name="componentsLinks"></a> links | Map[`string`, [Link Object](#linkObject)] | An object to hold reusable [Link Objects](#linkObject).
-<a name="componentsCallbacks"></a> callbacks | Map[`string`, [Callbacks Object](#callbacksObject)] | An object to hold reusable [Callbacks Objects](#callbacksObject).
+<a name="componentsCallbacks"></a> callbacks | Map[`string`, [Callback Object](#callbackObject)] | An object to hold reusable [Callback Object](#callbackObject).
 
 All the fixed fields declared above are objects that MUST use keys that match the regular expression: `[a-zA-Z0-9.\-_]+`.
 
@@ -915,8 +915,8 @@ Field Name | Type | Description
 <a name="parameterExplode"></a>explode | `boolean` | When this is true, parameter values of type `array` or `object` generate separate parameters for each value of the array, or key-value-pair of the map.  For other types of parameters this property has no effect. When [`style`](#parameterStyle) is `form`, the default value is `true`. For all other styles, the default value is `false`.
 <a name="parameterAllowReserved"></a>allowReserved | `boolean` | Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-2.2) `:/?#[]@!$&'()*+,;=` to be included without percent-encoding. This property only applies to parameters with an `in` value of `query`. The default value is `false`.
 <a name="parameterSchema"></a>schema | [Schema Object](#schemaObject) | The schema defining the type used for the parameter.
-<a name="parameterExamples"></a>examples | [[Example Object](#exampleObject)] | Examples of the content type.  Each example in the Examples array SHOULD be in the correct format as specified parameter encoding.  The `examples` object is mutually exclusive to the `example` object.  Furthermore, if referencing a `schema` which contains an example, the `examples` value SHALL _override_ the example provided by the schema.
-<a name="parameterExample"></a>example | [Example Object](#exampleObject) | Example of the content type.  The example object SHOULD be in the correct format as specified in the parameter encoding.  The `example` object is mutually exclusive to the `examples` object.  Furthermore, if referencing a `schema` which contains an example, the `example` value SHALL _override_ the example provided by the the schema.
+<a name="parameterExamples"></a>examples | [[Example Object](#exampleObject) <span>&#124;</span> [Reference Object](#referenceObject)] | Examples of the content type.  Each example in the Examples array SHOULD be in the correct format as specified parameter encoding.  The `examples` object is mutually exclusive to the `example` object.  Furthermore, if referencing a `schema` which contains an example, the `examples` value SHALL _override_ the example provided by the schema.
+<a name="parameterExample"></a>example | [Example Object](#exampleObject) <span>&#124;</span> [Reference Object](#referenceObject) | Example of the content type.  The example object SHOULD be in the correct format as specified in the parameter encoding.  The `example` object is mutually exclusive to the `examples` object.  Furthermore, if referencing a `schema` which contains an example, the `example` value SHALL _override_ the example provided by the the schema.
 
 For more complex scenarios a `content` object can be used to define the media-type 
 and schema of the parameter.  This option is mutually exclusive with the simple scenario
@@ -1244,8 +1244,8 @@ Each content type object provides schema and examples for a the media type ident
 Field Name | Type | Description
 ---|:---:|---
 <a name="contentTypeSchema"></a>schema | [Schema Object](#schemaObject) | The schema defining the type used for the request body.
-<a name="contentTypeExamples"></a>examples | [Examples Array](#examplesArray) | Examples of the content type.  Each example in the Examples array SHOULD be in the correct format as specified in the _content_ type.  The `examples` object is mutually exclusive to the `example` object.  Furthermore, if referencing a `schema` which contains an example, the `examples` value SHALL _override_ the example provided by the schema.
-<a name="contentTypeExample"></a>example | [Example Object](#exampleObject) | Example of the content type.  The example object SHOULD be in the correct format as specified in the _content_ type.  The `example` object is mutually exclusive to the `examples` object.  Furthermore, if referencing a `schema` which contains an example, the `example` value SHALL _override_ the the example provided by the schema.
+<a name="contentTypeExamples"></a>examples | [[Example Object](#exampleObject) <span>&#124;</span> [Reference Object](#referenceObject)] | Examples of the content type.  Each example in the Examples array SHOULD be in the correct format as specified in the _content_ type.  The `examples` object is mutually exclusive to the `example` object.  Furthermore, if referencing a `schema` which contains an example, the `examples` value SHALL _override_ the example provided by the schema.
+<a name="contentTypeExample"></a>example | [Example Object](#exampleObject) <span>&#124;</span> [Reference Object](#referenceObject) | Example of the content type.  The example object SHOULD be in the correct format as specified in the _content_ type.  The `example` object is mutually exclusive to the `examples` object.  Furthermore, if referencing a `schema` which contains an example, the `example` value SHALL _override_ the the example provided by the schema.
 
 ##### Patterned Fields
 Field Pattern | Type | Description
@@ -1672,24 +1672,36 @@ description: object created
 #### <a name="callbacksObject"></a>Callbacks Object
 
 A map of possible out-of band callbacks related to the parent operation.
-Each value in the map is an [Operation Object](#operationObject) that describes a request that may be initiated by the API provider and the expected responses.
+Each value in the map is an [Callback Object](#callbackObject) that describes a request that may be initiated by the API provider and the expected responses.
 The key value used to identify the callback object is an expression, evaluated at runtime, that identifies a URL to use for the callback operation.
 
 ##### Patterned Fields
 Field Pattern | Type | Description
 ---|:---:|---
-<a name="callbackName"></a>Callback name | [Callback Operation Object](#operationObject) <span>&#124;</span> [Operation Object](#operationObject) | An Operation Object used to define a callback request and expected responses
+<a name="callbackName"></a>{name} | [Callback Object](#callbackObject) <span>&#124;</span> [Reference Object](#ReferenceObject) | A Callback Object used to define a callback request and expected responses
+
+This object can be extended with [Specification Extensions](#specificationExtensions). 
+
+#### <a name="callbackObject"></a>Callback Object
+
+A map of possible out-of band callbacks related to the parent operation.
+Each value in the map is a [Path Item Object](#pathItemObject) that describes a set of requests that may be initiated by the API provider and the expected responses.
+The key value used to identify the callback object is an expression, evaluated at runtime, that identifies a URL to use for the callback operation.
+
+##### Patterned Fields
+Field Pattern | Type | Description
+---|:---:|---
+<a name="callbackExpression"></a>{expression} | [Path Item Object](#pathItemObject) | An Path Item Object used to define a callback request and expected responses
 
 This object can be extended with [Specification Extensions](#specificationExtensions). 
 
 ##### Key Expression
 
-The key used to identify the callback object is a variable expression that can be evaluated in the context of a runtime HTTP request/response to identify the URL to be used for the callback request.
+The key used to identify the Path Item Object is a variable expression that can be evaluated in the context of a runtime HTTP request/response to identify the URL to be used for the callback request.
 A simple example might be `$request.body#/url`.
 However, using [variable substition](#variableSubstition) syntax the complete HTTP message can be accessed.
 This includes accessing any part of a body that can be accessed using a JSON Pointer [RFC6901](https://tools.ietf.org/html/rfc6901). 
 
-
 For example, given the following HTTP request:
 
 ```http
@@ -1748,12 +1760,12 @@ myWebhook:
 
 
 #### <a name="headersObject"></a>Headers Object
-Lists the headers that can be sent as part of a response. Note that [RFC 7230](https://tools.ietf.org/html/rfc7230#page-22) states header names are case insensitive.
+Lists the headers that can be sent in a response or forwarded via a link. Note that [RFC 7230](https://tools.ietf.org/html/rfc7230#page-22) states header names are case insensitive.
 
 ##### Patterned Fields
 Field Pattern | Type | Description
 ---|:---:|---
-<a name="headersName"></a>{name} | [Header Object](#headerObject) | The name of the property corresponds to the name of the header. The value describes the type of the header.
+<a name="headersName"></a>{name} | [Header Object](#headerObject)  <span>&#124;</span> [Reference Object](#referenceObject) | The name of the property corresponds to the name of the header. The value describes the type of the header.
 
 ##### Headers Object Example
 
@@ -1850,7 +1862,7 @@ Field Name  |  Type  | Description
 ---|:---:|---
 href        | `string`    | a relative or absolute URL to a linked resource. This field is mutually exclusive with the `operationId` field.
 operationId | `string` | the name of an _existing_, resolvable OAS operation, as defined with a unique `operationId`.  This field is mutually exclusive with the `href` field.  Relative `href` values MAY be used to locate an existing Operation Object in the OAS.
-parameters  | [Link Parameters Object](#linkParameters) | an Object representing parameters to pass to an operation as specified with `operationId` or identified via `href`.
+parameters  | [Link Parameters Object](#linkParameters) | an object representing parameters to pass to an operation as specified with `operationId` or identified via `href`.
 headers     | [Headers Object](#headersObject)    | an object representing headers to pass to the linked resource. Where conflicts occur between these headers, and those defined in the related operation, these headers override.
 description | `string` | a description of the link, supports [CommonMark syntax](http://spec.commonmark.org/).