From e5966fabc19c738f69103e4f13a955542075123d Mon Sep 17 00:00:00 2001 From: Mike Ralphson Date: Fri, 30 Oct 2020 11:36:44 +0000 Subject: [PATCH 1/5] OAS schema dialect clarifications --- versions/3.1.0.md | 82 ++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 71 insertions(+), 11 deletions(-) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index 53f48be6c2..ebe54ec0bb 100644 --- a/versions/3.1.0.md +++ b/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 ### 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`. ### 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 ``` +#### Defaults Object + +Contains globally-applied defaults to specific areas of the OAS document. + +##### Fixed Fields + +Field Name | Type | Description +---|:---|--- + 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#' +``` + +#### Schema Defaults Object + +Contains globally-applied defaults for [Schema Objects](#schemaObject). + +##### Fixed Fields + +Field Name | Type | Description +---|:---|--- + $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#' +``` #### Paths Object @@ -2285,7 +2339,7 @@ $ref: definitions.yaml#/Pet #### 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 "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 externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this schema. 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.

**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. ###### 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 OAS dialect schema id, 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 Schema Defaults Object. 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 From b57aed0305a8891dd0fa38b18b70ab35c5430071 Mon Sep 17 00:00:00 2001 From: Mike Ralphson Date: Fri, 30 Oct 2020 11:36:44 +0000 Subject: [PATCH 2/5] OAS schema dialect clarifications Signed-off-by: Mike Ralphson --- versions/3.1.0.md | 82 ++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 71 insertions(+), 11 deletions(-) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index 53f48be6c2..ebe54ec0bb 100644 --- a/versions/3.1.0.md +++ b/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 ### 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`. ### 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 ``` +#### Defaults Object + +Contains globally-applied defaults to specific areas of the OAS document. + +##### Fixed Fields + +Field Name | Type | Description +---|:---|--- + 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#' +``` + +#### Schema Defaults Object + +Contains globally-applied defaults for [Schema Objects](#schemaObject). + +##### Fixed Fields + +Field Name | Type | Description +---|:---|--- + $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#' +``` #### Paths Object @@ -2285,7 +2339,7 @@ $ref: definitions.yaml#/Pet #### 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 "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 externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this schema. 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.

**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. ###### 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 OAS dialect schema id, 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 Schema Defaults Object. 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 From f51e2e70c2cbc1d5858c98e8738f7192a4a3ab82 Mon Sep 17 00:00:00 2001 From: Mike Ralphson Date: Fri, 6 Nov 2020 13:21:12 +0000 Subject: [PATCH 3/5] $schema is allowed in subschemas when bundling 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 ebe54ec0bb..a47fd6e941 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -2395,7 +2395,7 @@ 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 (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 OAS dialect schema id, and MAY support additional values of `$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 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 `$schema` value may be set within a Schema Defaults Object. 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. From 7b277cc3845ffa6d2234d4a1ab70395f4e1ab785 Mon Sep 17 00:00:00 2001 From: Mike Ralphson Date: Fri, 6 Nov 2020 14:20:13 +0000 Subject: [PATCH 4/5] Schema dialect clarifications from Ben Signed-off-by: Mike Ralphson --- versions/3.1.0.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index a47fd6e941..7549a1dae5 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -2348,11 +2348,11 @@ Where JSON Schema indicates that behavior is defined by the application (e.g. fo ##### Properties -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](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 "OAS dialect schema id"). -The following properties are taken from the JSON Schema definition but their definitions have been extended by the OAS: +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. @@ -2361,7 +2361,7 @@ In addition to the JSON Schema properties comprising the OAS dialect, the Schema The OpenAPI Specification's base vocabulary is comprised of the following keywords: -##### Fixed Fields +##### Fixed Fields Field Name | Type | Description ---|:---:|--- From 8aa27b1d1323d01da864826cbc7b011aed7183bc Mon Sep 17 00:00:00 2001 From: Mike Ralphson Date: Thu, 19 Nov 2020 15:39:06 +0000 Subject: [PATCH 5/5] Use top-level jsonSchemaDialect field --- versions/3.1.0.md | 58 ++--------------------------------------------- 1 file changed, 2 insertions(+), 56 deletions(-) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index 7549a1dae5..cc3731f3b5 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -35,8 +35,6 @@ 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) @@ -183,6 +181,7 @@ Field Name | Type | Description ---|:---:|--- 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. info | [Info Object](#infoObject) | **REQUIRED**. Provides metadata about the API. The metadata MAY be used by tooling as required. + 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. 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 `/`. paths | [Paths Object](#pathsObject) | The available paths and operations for the API. 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,59 +641,6 @@ components: read:pets: read your pets ``` -#### Defaults Object - -Contains globally-applied defaults to specific areas of the OAS document. - -##### Fixed Fields - -Field Name | Type | Description ----|:---|--- - 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#' -``` - -#### Schema Defaults Object - -Contains globally-applied defaults for [Schema Objects](#schemaObject). - -##### Fixed Fields - -Field Name | Type | Description ----|:---|--- - $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#' -``` - #### Paths Object Holds the relative paths to the individual endpoints and their operations. @@ -2397,7 +2343,7 @@ It is important for tooling to be able to determine which dialect or 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 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 `$schema` value may be set within a Schema Defaults Object. 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. +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 dialact schema id MUST be used for these Schema Objects. The value of `$schema` within a 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://json-schema.org/draft/2019-09/json-schema-core.html#rfc.section.8.1.1).