From fe9c31efd7f384469be01c8a2121df43a0ab7b69 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Thu, 13 Jun 2024 13:31:03 -0700 Subject: [PATCH 1/3] More guidance on schema dialects. This makes it more clear that jsonSchemaDialect, like $schema, is per document, and provides guidance for incomplete OAS documents and using $schema in standalone schema documents. It also clarifies the nature of "requiring" the OAS extension vocabulary. --- versions/3.1.1.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index ba2f17bf01..a59c7ac920 100644 --- a/versions/3.1.1.md +++ b/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: +The OpenAPI Specification's base vocabulary is safe for standard validators to ignore, as indicated by its inclusion in the OAS dialect's [`$vocabulary`](https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-00#section-8.1.2) keyword with a value of `false`. +It is comprised of the following keywords: ##### 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 OAS dialect schema id, 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 OAS dialect schema id, 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 OpenAPI Object. 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 OpenAPI Object. 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 From 0da20604142b54e5d155258d55602dea26aeef8e Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Mon, 17 Jun 2024 12:02:00 -0700 Subject: [PATCH 2/3] Better wording (review feedback) Co-authored-by: Karen Etheridge --- versions/3.1.1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index a59c7ac920..03d1174be5 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -2583,7 +2583,7 @@ 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 safe for standard validators to ignore, as indicated by its inclusion in the OAS dialect's [`$vocabulary`](https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-00#section-8.1.2) keyword with a value of `false`. +Validators MAY choose to ignore keywords defined by the OpenAPI Specification's base vocabulary, 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`. It is comprised of the following keywords: ##### Fixed Fields From 324f2c5466e74892a0633daa3b6ed8794877e314 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Mon, 17 Jun 2024 12:06:36 -0700 Subject: [PATCH 3/3] Better explanation of "false" vocabularies --- versions/3.1.1.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index 03d1174be5..0e282e2c83 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -2583,8 +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. -Validators MAY choose to ignore keywords defined by the OpenAPI Specification's base vocabulary, 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`. -It 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: ##### Fixed Fields