From 01098c67108927e0f322d13f9ca8968b7aa26b30 Mon Sep 17 00:00:00 2001 From: Phil Sturgeon Date: Mon, 15 Jun 2020 18:59:35 +0200 Subject: [PATCH 1/5] chore: explain how $schema might work --- versions/3.1.0.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index 41d0b73ea1..3cc002f5ef 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -2336,6 +2336,18 @@ 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 + +OpenAPI documents are made up of multiple resources, sometimes resources are all in the same root OpenAPI document (inline resources), or resources are contain their own documents with `$ref` (separate resources). 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 can be used to define which meta-schema should be used when interacting with any resource. + +Inline resources will default to using `$schema: "https://json-schema.org/draft/2019-09/schema"`. + +Separate resources will default to using `$schema: "https://spec.openapis.org/oas/3.1/schema-object"`. + +Any resource can override this default by setting the `$schema` property to something else. + ##### Schema Object Examples ###### Primitive Sample From 3d2144b36dad87f6ef83b2e00ed830868dd594eb Mon Sep 17 00:00:00 2001 From: Phil Sturgeon Date: Thu, 2 Jul 2020 14:37:23 +0200 Subject: [PATCH 2/5] reordered and made it specifically only schema resources --- versions/3.1.0.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index 3cc002f5ef..e63af9278f 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -2338,15 +2338,17 @@ The [XML Object](#xmlObject) contains additional information about the available ###### Picking Schema Vocabularies -OpenAPI documents are made up of multiple resources, sometimes resources are all in the same root OpenAPI document (inline resources), or resources are contain their own documents with `$ref` (separate resources). 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. +OpenAPI documents are made up of multiple resources, sometimes resources are all in the same root OpenAPI document (inline resources), or resources are contain their own documents with `$ref` (separate resources). A schema object could exist as an inline resource, or a separate resource. -The `$schema` keyword can be used to define which meta-schema should be used when interacting with any resource. +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. -Inline resources will default to using `$schema: "https://json-schema.org/draft/2019-09/schema"`. +The `$schema` keyword can be used to define which meta-schema should be used when interacting with any schema resource. -Separate resources will default to using `$schema: "https://spec.openapis.org/oas/3.1/schema-object"`. +Inline schema resources will default to using `$schema: "https://spec.openapis.org/oas/3.1/schema-object"`. -Any resource can override this default by setting the `$schema` property to something else. +Separate schema resources will default to using `$schema: "https://json-schema.org/draft/2019-09/schema"`. + +Any schema resource can override this default by setting the `$schema` property to something else. ##### Schema Object Examples From 7e2e35f1c2fe0f6c4aee8e84029c5d5c2ada9842 Mon Sep 17 00:00:00 2001 From: Phil Sturgeon Date: Mon, 6 Jul 2020 11:19:35 +0200 Subject: [PATCH 3/5] Update versions/3.1.0.md Co-authored-by: Karen Etheridge --- versions/3.1.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index e63af9278f..94d13ead07 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -2338,7 +2338,7 @@ The [XML Object](#xmlObject) contains additional information about the available ###### Picking Schema Vocabularies -OpenAPI documents are made up of multiple resources, sometimes resources are all in the same root OpenAPI document (inline resources), or resources are contain their own documents with `$ref` (separate resources). A schema object could exist as an inline resource, or a separate resource. +OpenAPI documents are made up of multiple resources. Sometimes resources are all in the same root OpenAPI document (inline resources); also, resources can contain their own documents with `$ref` (separate resources). A schema object could exist as an inline resource, or a separate resource. 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. From ae38cfbd5ab29e9910eefbb61afdf958e182b526 Mon Sep 17 00:00:00 2001 From: Phil Sturgeon Date: Mon, 6 Jul 2020 11:19:51 +0200 Subject: [PATCH 4/5] Update versions/3.1.0.md Co-authored-by: Ben Hutton --- versions/3.1.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index 94d13ead07..68852b4784 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -2342,7 +2342,7 @@ OpenAPI documents are made up of multiple resources. Sometimes resources are all 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 can be used to define which meta-schema should be used when interacting with any schema resource. +The `$schema` keyword can be used to identify which meta-schema should be used when interacting with any schema resource. Inline schema resources will default to using `$schema: "https://spec.openapis.org/oas/3.1/schema-object"`. From 6e71af60cd5768ec9b3c349ae3cdd3cfc43411ac Mon Sep 17 00:00:00 2001 From: Phil Sturgeon Date: Wed, 22 Jul 2020 12:23:24 +0200 Subject: [PATCH 5/5] new approach --- versions/3.1.0.md | 10 ++-------- 1 file changed, 2 insertions(+), 8 deletions(-) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index 68852b4784..dbcef3c639 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -2338,17 +2338,11 @@ The [XML Object](#xmlObject) contains additional information about the available ###### Picking Schema Vocabularies -OpenAPI documents are made up of multiple resources. Sometimes resources are all in the same root OpenAPI document (inline resources); also, resources can contain their own documents with `$ref` (separate resources). A schema object could exist as an inline resource, or a separate resource. - 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 can be used to identify which meta-schema should be used when interacting with any schema resource. - -Inline schema resources will default to using `$schema: "https://spec.openapis.org/oas/3.1/schema-object"`. - -Separate schema resources will default to using `$schema: "https://json-schema.org/draft/2019-09/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. -Any schema resource can override this default by setting the `$schema` property to something else. +When `$schema` is not present, the default the following dialect MUST be assumed: `$schema: "https://spec.openapis.org/oas/3.1/schema-object"`. ##### Schema Object Examples