OAS schema dialect clarifications

versions/3.1.0.md

@@ -35,6 +35,8 @@ An OpenAPI definition can then be used by documentation generation tools to disp
 		- [Server Object](#serverObject)
 		- [Server Variable Object](#serverVariableObject)
 		- [Components Object](#componentsObject)
+		- [Defaults Object](#defaultsObject)
+		- [Schema Defaults Object](#schemaDefaultsObject)
 		- [Paths Object](#pathsObject)
 		- [Path Item Object](#pathItemObject)
 		- [Operation Object](#operationObject)
@@ -133,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.
 
@@ -640,6 +642,58 @@ components:
             read:pets: read your pets
 ```
 
+#### <a name="defaultsObject"></a>Defaults Object
+
+Contains globally-applied defaults to specific areas of the OAS document.
+
+##### Fixed Fields
+
+Field Name | Type | Description
+---|:---|---
+<a name="defaultsSchema"></a> schema | [Schema Defaults Object](#schemaDefaultsObject)] | An object to hold defaults for [Schema Objects](#schemaObject).
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+##### Defaults Object Example
+
+```json
+"defaults": {
+  "schema": {
+    "$schema": "http://json-schema.org/draft-07/schema#"
+  }
+}
+```
+
+```yaml
+defaults:
+  schema:
+    $schema: 'http://json-schema.org/draft-07/schema#'
+```
+
+#### <a name="schemaDefaultsObject"></a>Schema Defaults Object
+
+Contains globally-applied defaults for [Schema Objects](#schemaObject).
+
+##### Fixed Fields
+
+Field Name | Type | Description
+---|:---|---
+<a name="schemaDefaultsSchema"></a> $schema | `string` | **REQUIRED**. The default value for the `$schema` keyword within [Schema Objects](#schemaObject) contained within this OAS document. MUST be in the form of a URI.
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+##### Schema Defaults Object Example
+
+```json
+"schema": {
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}
+```
+
+```yaml
+schema:
+  $schema: 'http://json-schema.org/draft-07/schema#'
+```
 
 #### <a name="pathsObject"></a>Paths Object
 
@@ -2285,7 +2339,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).
 
@@ -2294,14 +2348,18 @@ 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 is described by a JSON Schema [dialect](https://json-schema.org/draft/2019-09/json-schema-core.html#rfc.section.4.3.3), comprising of a base [vocabulary](https://json-schema.org/draft/2019-09/json-schema-core.html#rfc.section.4.3.3) which extends the JSON Schema Core and Validation vocabularies. As such any keyword available within those vocabularies is by definition available in a Schema Object, and will work in exactly the same way.
+
+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 definition 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.
+
+The OpenAPI Specification's base vocabulary is comprised of the following keywords:
 
 ##### Fixed Fields
 
@@ -2312,7 +2370,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)
 
@@ -2333,13 +2391,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 (but MUST NOT occur in subschemas defined directly within those Schema Objects), 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 `$schema` value may be set within a <a href="#schemaDefaultsObject">Schema Defaults 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