Reference Object and Schema Object use of $ref updates for 2019-09 / OAS 3.1 (#2107)

* Checkpoint of draft

* Fix typo.

Co-Authored-By: Darrel <[email protected]>

* Fix plural anchor

Co-Authored-By: Mike Ralphson <[email protected]>

* Remove superfluous specification

Co-Authored-By: Phil Sturgeon <[email protected]>

Co-authored-by: Darrel <[email protected]>
Co-authored-by: Mike Ralphson <[email protected]>
Co-authored-by: Phil Sturgeon <[email protected]>

Author: 4 people

versions/3.1.0.md

@@ -170,12 +170,12 @@ The formats defined by the OAS are:
 Throughout the specification `description` fields are noted as supporting CommonMark markdown formatting.
 Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by [CommonMark 0.27](https://spec.commonmark.org/0.27/). Tooling MAY choose to ignore some CommonMark features to address security concerns. 
 
-### <a name="relativeReferences"></a>Relative References in URLs
+### <a name="relativeReferences"></a>Relative References in URIs
 
-Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-4.2).
-Relative references are resolved using the URLs defined in the [`Server Object`](#serverObject) as a Base URI.
+Unless specified otherwise, all properties that are URIs MAY be relative references as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-4.2).
+Relative references are resolved using the URLs defined in the [`Server Object`](#serverObject) as a Base URI.  This includes relative references in [`Reference Objects`](#referenceObject), outside of any [`Schema Object`](#schemaObject).
 
-Relative references used in `$ref` are processed as per [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03), using the URL of the current document as the base URI. See also the [Reference Object](#referenceObject).
+Relative references in [`Schema Objects`](#schemaObject), including any that appear as `$id` values, use the nearest parent `$id` as a Base URI, as described by [JSON Schema Specification Draft 2019-09](https://json-schema.org/draft/2019-09/json-schema-core.html).  If no parent schema contains an `$id`, then the Base URI is determined as in the previous paragraph.
 
 ### Schema
 
@@ -449,7 +449,7 @@ All objects defined within the components object will have no effect on the API
 
 Field Name | Type | Description
 ---|:---|---
-<a name="componentsSchemas"></a> schemas | Map[`string`, [Schema Object](#schemaObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Schema Objects](#schemaObject).
+<a name="componentsSchemas"></a> schemas | Map[`string`, [Schema Object](#schemaObject) | An object to hold reusable [Schema Objects](#schemaObject).
 <a name="componentsResponses"></a> responses | Map[`string`, [Response Object](#responseObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Response Objects](#responseObject).
 <a name="componentsParameters"></a> parameters | Map[`string`, [Parameter Object](#parameterObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Parameter Objects](#parameterObject).
 <a name="componentsExamples"></a> examples | Map[`string`, [Example Object](#exampleObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Example Objects](#exampleObject).
@@ -1029,7 +1029,7 @@ Field Name | Type | Description
 <a name="parameterStyle"></a>style | `string` | Describes how the parameter value will be serialized depending on the type of the parameter value. Default values (based on value of `in`): for `query` - `form`; for `path` - `simple`; for `header` - `simple`; for `cookie` - `form`.
 <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) \| [Reference Object](#referenceObject) | The schema defining the type used for the parameter.
+<a name="parameterSchema"></a>schema | [Schema Object](#schemaObject) | The schema defining the type used for the parameter.
 <a name="parameterExample"></a>example | Any | Example of the media type.  The example SHOULD match the specified schema and encoding properties if present.  The `example` field is mutually exclusive of the `examples` field.  Furthermore, if referencing a `schema` which contains an example, the `example` value SHALL _override_ the example provided by the schema. To represent examples of media types that cannot naturally be represented in JSON or YAML, a string value can contain the example with escaping where necessary.
 <a name="parameterExamples"></a>examples | Map[ `string`, [Example Object](#exampleObject) \| [Reference Object](#referenceObject)] | Examples of the media type.  Each example SHOULD contain a value in the correct format as specified in the parameter encoding.  The `examples` field is mutually exclusive of the `example` field.  Furthermore, if referencing a `schema` which contains an example, the `examples` value SHALL _override_ the example provided by the schema.
 
@@ -1368,7 +1368,7 @@ Each Media Type Object provides schema and examples for the media type identifie
 ##### Fixed Fields
 Field Name | Type | Description
 ---|:---:|---
-<a name="mediaTypeSchema"></a>schema | [Schema Object](#schemaObject) \| [Reference Object](#referenceObject) | The schema defining the content of the request, response, or parameter.
+<a name="mediaTypeSchema"></a>schema | [Schema Object](#schemaObject) | The schema defining the content of the request, response, or parameter.
 <a name="mediaTypeExample"></a>example | Any | Example of the media type.  The example object SHOULD be in the correct format as specified by the media type.  The `example` field is mutually exclusive of the `examples` field.  Furthermore, if referencing a `schema` which contains an example, the `example` value SHALL _override_ the example provided by the schema.
 <a name="mediaTypeExamples"></a>examples | Map[ `string`, [Example Object](#exampleObject) \| [Reference Object](#referenceObject)] | Examples of the media type.  Each example object SHOULD  match the media type and specified schema if present.  The `examples` field is mutually exclusive of the `example` field.  Furthermore, if referencing a `schema` which contains an example, the `examples` value SHALL _override_ the example provided by the schema.
 <a name="mediaTypeEncoding"></a>encoding | Map[`string`, [Encoding Object](#encodingObject)] | A map between a property name and its encoding information. The key, being the property name, MUST exist in the schema as a property. The encoding object SHALL only apply to `requestBody` objects when the media type is `multipart` or `application/x-www-form-urlencoded`.
@@ -2243,17 +2243,15 @@ description: Pets operations
 
 A simple object to allow referencing other components in the specification, internally and externally.
 
-The Reference Object is defined by [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03) and follows the same structure, behavior and rules. 
-
-For this specification, reference resolution is accomplished as defined by the JSON Reference specification and not by the JSON Schema specification.
-
 ##### Fixed Fields
 Field Name | Type | Description
 ---|:---:|---
 <a name="referenceRef"></a>$ref | `string` | **REQUIRED**. The reference string.
 
 This object cannot be extended with additional properties and any properties added SHALL be ignored.
 
+Note that this restriction on additional properties is a difference between Reference Objects and [`Schema Objects`](#schemaObject) that contain a `$ref` keyword.
+
 ##### Reference Object Example
 
 ```json
@@ -2290,7 +2288,7 @@ $ref: definitions.yaml#/Pet
 
 #### <a name="schemaObject"></a>Schema Object
 
-The Schema Object allows the definition of input and output data types. These types can be objects, but also primitives and arrays. This object is a superset of the [JSON Schema Draft 2019-09](http://json-schema.org/) specification.
+The Schema Object allows the definition of input and output data types. These types can be objects, but also primitives and arrays. This object is a superset of the [JSON Schema Specification Draft 2019-09](http://json-schema.org/).
 
 For more information about the properties, see [JSON Schema Core](https://json-schema.org/draft/2019-09/json-schema-core.html) and [JSON Schema Validation](https://json-schema.org/draft/2019-09/json-schema-validation.html).