OAS schema dialect clarifications (#2399)

* OAS schema dialect clarifications

* OAS schema dialect clarifications

Signed-off-by: Mike Ralphson <[email protected]>

* $schema is allowed in subschemas when bundling

Co-authored-by: Ben Hutton <[email protected]>

* Schema dialect clarifications from Ben

Signed-off-by: Mike Ralphson <[email protected]>

* Use top-level jsonSchemaDialect field

Co-authored-by: Ben Hutton <[email protected]>

Author: MikeRalphson

versions/3.1.0.md

@@ -135,13 +135,13 @@ In order to preserve the ability to round-trip between YAML and JSON formats, YA
 
 ### <a name="documentStructure"></a>Document Structure
 
-An OpenAPI document MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the user. In the latter case, `$ref` fields MUST be used in the specification to reference those parts as follows from the [JSON Schema](https://json-schema.org) definitions.
+An OpenAPI document MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the user. In the latter case, `$ref` fields MUST be used in the OAS document to reference those parts as follows from the [JSON Schema](https://json-schema.org/draft/2019-09/json-schema-core.html#references) definitions.
 
 It is RECOMMENDED that the root OpenAPI document be named: `openapi.json` or `openapi.yaml`.
 
 ### <a name="dataTypes"></a>Data Types
 
-Data types in the OAS are based on the types supported by the [JSON Schema Specification Draft 2019-09](http://json-schema.org/draft/2019-09/json-schema-core.html#rfc.section.4.2). 
+Data types in the OAS are based on the types supported by the [JSON Schema Specification Draft 2019-09](https://json-schema.org/draft/2019-09/json-schema-core.html#rfc.section.4.2).
 Note that `integer` as a type is also supported and is defined as a JSON number without a fraction or exponent part. 
 Models are defined using the [Schema Object](#schemaObject), which is a superset of JSON Schema Specification Draft 2019-09.
 
@@ -183,6 +183,7 @@ Field Name | Type | Description
 ---|:---:|---
 <a name="oasVersion"></a>openapi | `string` | **REQUIRED**. This string MUST be the [version number](#versions) of the OpenAPI Specification that the OpenAPI document uses. The `openapi` field SHOULD be used by tooling to interpret the OpenAPI document. This is *not* related to the API [`info.version`](#infoVersion) string.
 <a name="oasInfo"></a>info | [Info Object](#infoObject) | **REQUIRED**. Provides metadata about the API. The metadata MAY be used by tooling as required.
+<a name="oasJsonSchemaDialect"></a> jsonSchemaDialect | `string` | The default value for the `$schema` keyword within [Schema Objects](#schemaObject) contained within this OAS document. MUST be in the form of a URI.
 <a name="oasServers"></a>servers | [[Server Object](#serverObject)] | An array of Server Objects, which provide connectivity information to a target server. If the `servers` property is not provided, or is an empty array, the default value would be a [Server Object](#serverObject) with a [url](#serverUrl) value of `/`.
 <a name="oasPaths"></a>paths | [Paths Object](#pathsObject) | The available paths and operations for the API.
 <a name="oasWebhooks"></a>webhooks | Map[`string`, [Path Item Object](#pathItemObject) \| [Reference Object](#referenceObject)] ] | The incoming webhooks that MAY be received as part of this API and that the API consumer MAY choose to implement. Closely related to the `callbacks` feature, this section describes requests initiated other than by an API call, for example by an out of band registration. The key name is a unique string to refer to each webhook, while the (optionally referenced) Path Item Object describes a request that may be initiated by the API provider and the expected responses. An [example](../examples/v3.1/webhook-example.yaml) is available.
@@ -642,7 +643,6 @@ components:
             read:pets: read your pets
 ```
 
-
 #### <a name="pathsObject"></a>Paths Object
 
 Holds the relative paths to the individual endpoints and their operations.
@@ -2289,7 +2289,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 Specification Draft 2019-09](http://json-schema.org/).
+These types can be objects, but also primitives and arrays. This object is a superset of the [JSON Schema Specification Draft 2019-09](https://json-schema.org/specification-links.html#2019-09-formerly-known-as-draft-8).
 
 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).
 
@@ -2298,16 +2298,20 @@ Where JSON Schema indicates that behavior is defined by the application (e.g. fo
 
 ##### Properties
 
-The OpenAPI Schema Object is a JSON Schema vocabulary which extends JSON Schema Core and Validation vocabularies. As such any keyword available for those vocabularies is by definition available in OpenAPI, and will work the exact same way.
+The OpenAPI Schema Object [dialect](https://json-schema.org/draft/2019-09/json-schema-core.html#rfc.section.4.3.3) is defined as requiring the [OAS base vocabulary](#baseVocabulary), in addition to the vocabularies as specified in the JSON Schema draft 2019-09 [general purpose meta-schema](http://json-schema.org/draft/2019-09/json-schema-core.html#rfc.section.8).
+
+The OpenAPI Schema Object dialect for this version of the specification is identified by the URI `https://spec.openapis.org/oas/3.1/dialect/base` (the <a name="dialectSchemaId"></a>"OAS dialect schema id").
 
-The following properties are taken from the JSON Schema definition but their definitions were adjusted to the OpenAPI Specification.
+The following properties are taken from the JSON Schema specification but their definitions have been extended by the OAS:
 
 - description - [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation.
 - format - See [Data Type Formats](#dataTypeFormat) for further details. While relying on JSON Schema's defined formats, the OAS offers a few additional predefined formats.
 
-In addition to the JSON Schema properties defined in the vocabularies defined in the JSON Schema Core and JSON Schema Validation specifications, any properties can be used from any vocabularies, or entirely arbitrary keywords. The OpenAPI Specification defines an additional vocabulary of keywords which MAY be used along with the JSON Schema vocabulary keywords for further schema description:
+In addition to the JSON Schema properties comprising the OAS dialect, the Schema Object supports keywords from any other vocabularies, or entirely arbitrary properties.
 
-##### Fixed Fields
+The OpenAPI Specification's base vocabulary is comprised of the following keywords:
+
+##### <a name="baseVocabulary"></a>Fixed Fields
 
 Field Name | Type | Description
 ---|:---:|---
@@ -2316,7 +2320,7 @@ Field Name | Type | Description
 <a name="schemaExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this schema.
 <a name="schemaExample"></a>example | Any | A free-form property to include an example of an instance for this schema. To represent examples that cannot be naturally represented in JSON or YAML, a string value can be used to contain the example with escaping where necessary.<br><br>**Deprecated:** The `example` property has been deprecated in favor of the JSON Schema `examples` keyword. Use of `example` is discouraged, and later versions of this specification may remove it.
 
-This object MAY be extended with [Specification Extensions](#specificationExtensions). 
+This object MAY be extended with [Specification Extensions](#specificationExtensions), though as noted, additional properties MAY omit the `x-` prefix within this object.
 
 ###### <a name="schemaComposition"></a>Composition and Inheritance (Polymorphism)
 
@@ -2337,13 +2341,15 @@ As such, inline schema definitions, which do not have a given id, *cannot* be us
 The [xml](#schemaXml) property allows extra definitions when translating the JSON definition to XML.
 The [XML Object](#xmlObject) contains additional information about the available options.
 
-###### Picking Schema Vocabularies
+###### Specifiying Schema Dialects
+
+It is important for tooling to be able to determine which dialect or meta-schema any given resource wishes to be processed with: JSON Schema Core, JSON Schema Validation, OpenAPI Schema dialect, or some custom meta-schema.
 
-It is important for tooling to be able to detect what meta-schema any given resource wishes to be processed with: JSON Schema Core, JSON Schema Validation, OpenAPI Schema Object, or some custom meta schema.
+The `$schema` keyword MAY be present in any root Schema Object, and if present MUST be used to determine which dialect should be used when processing the schema. This allows use of Schema Objects which comply with other drafts of JSON Schema than the default Draft 2019-09 support. Tooling MUST support the <a href="#dialectSchemaId">OAS dialect schema id</a>, and MAY support additional values of `$schema`.
 
-`$schema` MAY be present in any Schema Object, and if present MUST be used to determine which dialect should be used when processing the schema.
+To allow use of a different default `$schema` value for all Schema Objects contained within an OAS document, a `jsonSchemaDialect` value may be set within the <a href="#oasObject">OpenAPI Object</a>. If this default is not set, then the OAS dialact schema id MUST be used for these Schema Objects. The value of `$schema` within a Schema Object always overrides any default.
 
-When `$schema` is not present, the default the following dialect MUST be assumed: `$schema: "https://spec.openapis.org/oas/3.1/schema-object"`.
+When a Schema Object is referenced from an external resource which is not an OAS document (e.g. a bare JSON Schema resource), then the value of the `$schema` keyword for schemas within that resource MUST follow [JSON Schema rules](https://json-schema.org/draft/2019-09/json-schema-core.html#rfc.section.8.1.1).
 
 ##### Schema Object Examples