Merge pull request #3909 from handrews/dialect-311

More guidance on schema dialects.

Author: handrews

versions/3.1.1.md

@@ -2583,7 +2583,8 @@ The following properties are taken from the JSON Schema specification but their
 
 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:
+JSON Schema implementations MAY choose to treat keywords defined by the OpenAPI Specification's base vocabulary as [unknown keywords](https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-00#section-4.3.1), due to its inclusion in the OAS dialect with a [`$vocabulary`](https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-00#section-8.1.2) value of `false`.
+The OAS base vocabulary is comprised of the following keywords:
 
 ##### <a name="baseVocabulary"></a>Fixed Fields
 
@@ -2623,11 +2624,12 @@ The [XML Object](#xmlObject) contains additional information about the available
 
 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.
 
-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 2020-12 support. Tooling MUST support the <a href="#dialectSchemaId">OAS dialect schema id</a>, and MAY support additional values of `$schema`.
+The `$schema` keyword MAY be present in any Schema Object that is a [schema resource root](https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-00#section-4.3.5), 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 2020-12 support. Tooling MUST support the <a href="#dialectSchemaId">OAS dialect schema id</a>, and MAY support additional values of `$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 dialect schema id MUST be used for these Schema Objects. The value of `$schema` within a Schema Object always overrides any default.
+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 dialect schema id MUST be used for these Schema Objects. The value of `$schema` within a resource root Schema Object always overrides any default.
 
-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://tools.ietf.org/html/draft-bhutton-json-schema-00#section-8.1.1).
+For standalone JSON Schema documents that do not set `$schema`, or for Schema Objects in OpenAPI description documents that are _not_ [complete documents](#documentStructure), the dialect SHOULD be assumed to be the OAS dialect.
+However, for maximum interoperability, it is RECOMMENDED that OpenAPI description authors explicitly set the dialect through `$schema` in such documents.
 
 ##### Schema Object Examples