From ac236d1e1a5b50a735adbbb1d5312b76f85fa1da Mon Sep 17 00:00:00 2001 From: Phil Sturgeon Date: Fri, 21 Jun 2019 11:49:57 +0200 Subject: [PATCH 1/7] Update Schema Object to proper JSON Schema --- versions/3.1.0.md | 66 ++++++++++++++++++++++++++--------------------- 1 file changed, 36 insertions(+), 30 deletions(-) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index 0bce670627..0280668a2a 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -2269,23 +2269,23 @@ $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 an extended subset of the [JSON Schema Specification Wright Draft 00](https://json-schema.org/). +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 Draft 2019-09](http://json-schema.org/) specification. + +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). -For more information about the properties, see [JSON Schema Core](https://tools.ietf.org/html/draft-wright-json-schema-00) and [JSON Schema Validation](https://tools.ietf.org/html/draft-wright-json-schema-validation-00). Unless stated otherwise, the property definitions follow the JSON Schema. -##### Properties +##### Properties -The following properties are taken directly from the JSON Schema definition and follow the same specifications: +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, including but not limited to: +- $schema +- $id - title +- required - multipleOf - maximum -- exclusiveMaximum - minimum -- exclusiveMinimum - maxLength - minLength - pattern (This string SHOULD be a valid regular expression, according to the [ECMA 262 regular expression](https://www.ecma-international.org/ecma-262/5.1/#sec-7.8.5) dialect) @@ -2294,46 +2294,52 @@ The following properties are taken directly from the JSON Schema definition and - uniqueItems - maxProperties - minProperties -- required - enum - -The following properties are taken from the JSON Schema definition but their definitions were adjusted to the OpenAPI Specification. -- type - Value MUST be a string. Multiple types via an array are not supported. -- allOf - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. -- oneOf - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. -- anyOf - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. -- not - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. -- items - Value MUST be an object and not an array. Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. `items` MUST be present if the `type` is `array`. -- properties - Property definitions MUST be a [Schema Object](#schemaObject) and not a standard JSON Schema (inline or referenced). -- additionalProperties - Value can be boolean or object. Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. Consistent with JSON Schema, `additionalProperties` defaults to `true`. -- description - [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. +- propertyNames +- contains +- const +- examples +- if / then / else +- dependentRequired / dependentSchemas +- deprecated +- additionalItems +- additionalProperties +- unevaluatedItems +- unevaluatedProperties +- maxContains +- minContains +- readOnly +- writeOnly + +The following properties are taken from the JSON Schema definition but their definitions were adjusted to the OpenAPI Specification. + +- type - Used to restrict the allowed types as specified in JSON Schema, but may be modified by the [`nullable`](#schemaNullable) keyword. +- exclusiveMinimum - Value can be a numeric value just like JSON Schema, or for backwards compatibility with older drafts it can accept a boolean to act as a modifier to the `minimum` keyword. The numeric value usage is recommended. +- exclusiveMaximum - Value can be a numeric value just like JSON Schema, or for backwards compatibility with older drafts it can accept a boolean to act as a modifier to the `minimum` keyword. The numeric value usage is recommended. +- 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. - default - The default value represents what would be assumed by the consumer of the input as the value of the schema if one is not provided. Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object defined at the same level. For example, if `type` is `string`, then `default` can be `"foo"` but cannot be `1`. Alternatively, any time a Schema Object can be used, a [Reference Object](#referenceObject) can be used in its place. This allows referencing definitions instead of defining them inline. -Additional properties defined by the JSON Schema specification that are not mentioned here are strictly unsupported. - -Other than the JSON Schema subset fields, the following fields MAY be used for further schema documentation: +In addition to the JSON Schema fields, the following OpenAPI vocabulary properties MAY be used for further schema documentation: ##### Fixed Fields + Field Name | Type | Description ---|:---:|--- -nullable | `boolean` | Allows sending a `null` value for the defined schema. Default value is `false`. +nullable | `boolean` | Allows sending a `null` value for the defined schema. Default value is `false`.

A `nullable` value of `true` allows `null` in addition to other specified `type` values only if `nullable` and `type` are both specified within the same schema object. The effect of `"nullable" : true` is limited to its expansion of the set of allowed types, within the scope of its containing schema. An `enum`, `const`, `allOf`, or other keyword can independently prohibit `null` values, effectively overriding `"nullable" : true`.

A `nullable` value of `false` leaves the specified or default `type` unmodified. It has no effect on the schema object.

**Deprecated:** The `type` property now allows "null" as a type, alone or within a type array. This is the standard way to allow null values in JSON Schema. Use of `nullable` is discouraged, and later versions of this specification may remove it. discriminator | [Discriminator Object](#discriminatorObject) | Adds support for polymorphism. The discriminator is an object name that is used to differentiate between other schemas which may satisfy the payload description. See [Composition and Inheritance](#schemaComposition) for more details. -readOnly | `boolean` | Relevant only for Schema `"properties"` definitions. Declares the property as "read only". This means that it MAY be sent as part of a response but SHOULD NOT be sent as part of the request. If the property is marked as `readOnly` being `true` and is in the `required` list, the `required` will take effect on the response only. A property MUST NOT be marked as both `readOnly` and `writeOnly` being `true`. Default value is `false`. -writeOnly | `boolean` | Relevant only for Schema `"properties"` definitions. Declares the property as "write only". Therefore, it MAY be sent as part of a request but SHOULD NOT be sent as part of the response. If the property is marked as `writeOnly` being `true` and is in the `required` list, the `required` will take effect on the request only. A property MUST NOT be marked as both `readOnly` and `writeOnly` being `true`. Default value is `false`. xml | [XML Object](#xmlObject) | This MAY be used only on properties schemas. It has no effect on root schemas. Adds additional metadata to describe the XML representation of this property. -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 | `boolean` | Specifies that a schema is deprecated and SHOULD be transitioned out of usage. Default value is `false`. +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). ###### Composition and Inheritance (Polymorphism) The OpenAPI Specification allows combining and extending model definitions using the `allOf` property of JSON Schema, in effect offering model composition. -`allOf` takes an array of object definitions that are validated *independently* but together compose a single object. +`allOf` takes an array of object definitions that are validated *independently* but together compose a single object. While composition offers model extensibility, it does not imply a hierarchy between the models. To support polymorphism, the OpenAPI Specification adds the `discriminator` field. From f8f92edb16fed0f4ad878914afba20feb9ea184e Mon Sep 17 00:00:00 2001 From: Phil Sturgeon Date: Fri, 25 Oct 2019 15:51:46 -0400 Subject: [PATCH 2/7] update vocab and arbitrary props --- versions/3.1.0.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index 0280668a2a..5467bedf1f 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -139,10 +139,9 @@ It is RECOMMENDED that the root OpenAPI document be named: `openapi.json` or `op ### Data Types -Primitive data types in the OAS are based on the types supported by the [JSON Schema Specification Wright Draft 00](https://tools.ietf.org/html/draft-wright-json-schema-00#section-4.2). +Primitive 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). Note that `integer` as a type is also supported and is defined as a JSON number without a fraction or exponent part. -`null` is not supported as a type (see [`nullable`](#schemaNullable) for an alternative solution). -Models are defined using the [Schema Object](#schemaObject), which is an extended subset of JSON Schema Specification Wright Draft 00. +Models are defined using the [Schema Object](#schemaObject), which is a superset of JSON Schema Specification Draft 2019-09. Primitives have an optional modifier property: `format`. OAS uses several known formats to define in fine detail the data type being used. @@ -2322,7 +2321,7 @@ The following properties are taken from the JSON Schema definition but their def Alternatively, any time a Schema Object can be used, a [Reference Object](#referenceObject) can be used in its place. This allows referencing definitions instead of defining them inline. -In addition to the JSON Schema fields, the following OpenAPI vocabulary properties MAY be used for further schema documentation: +In addition to the JSON Schema properties, the following OpenAPI vocabulary properties MAY be used for further schema documentation: ##### Fixed Fields @@ -2334,7 +2333,9 @@ 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). + +In previous versions of OpenAPI, Specification Extensions were the only way to add properties, but since v3.1.0 matches JSON Schema in allowing any properties to be used inside the Schema Object. These properties could be defined in their own vocabulary, or entirely arbitrary, and they do not need to follow any specific naming pattern or convention. ###### Composition and Inheritance (Polymorphism) From e121405b9f54550c60e7baf259e17c1ce54cce43 Mon Sep 17 00:00:00 2001 From: Phil Sturgeon Date: Mon, 28 Oct 2019 13:30:12 -0400 Subject: [PATCH 3/7] another go at arbitrary keywords --- versions/3.1.0.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index 5467bedf1f..3e3af6003b 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -2321,7 +2321,7 @@ The following properties are taken from the JSON Schema definition but their def Alternatively, any time a Schema Object can be used, a [Reference Object](#referenceObject) can be used in its place. This allows referencing definitions instead of defining them inline. -In addition to the JSON Schema properties, the following OpenAPI vocabulary properties MAY be used for further schema documentation: +In addition to the JSON Schema properties defined in the JSON Schema Core and JSON Schema Validation vocabularies, any properties can be used from any vocabularies, or entirely arbitrary keywords. OpenAPI has its own vocabulary properties which MAY be used for further schema description: ##### Fixed Fields @@ -2335,8 +2335,6 @@ Field Name | Type | Description This object MAY be extended with [Specification Extensions](#specificationExtensions). -In previous versions of OpenAPI, Specification Extensions were the only way to add properties, but since v3.1.0 matches JSON Schema in allowing any properties to be used inside the Schema Object. These properties could be defined in their own vocabulary, or entirely arbitrary, and they do not need to follow any specific naming pattern or convention. - ###### Composition and Inheritance (Polymorphism) The OpenAPI Specification allows combining and extending model definitions using the `allOf` property of JSON Schema, in effect offering model composition. From 5905f45cfef8a75f0d0dcb80405ce227f35a0673 Mon Sep 17 00:00:00 2001 From: Phil Sturgeon Date: Tue, 29 Oct 2019 16:03:33 -0400 Subject: [PATCH 4/7] feedback from @handrews --- 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 3e3af6003b..d7844b0ed1 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -2321,7 +2321,7 @@ The following properties are taken from the JSON Schema definition but their def Alternatively, any time a Schema Object can be used, a [Reference Object](#referenceObject) can be used in its place. This allows referencing definitions instead of defining them inline. -In addition to the JSON Schema properties defined in the JSON Schema Core and JSON Schema Validation vocabularies, any properties can be used from any vocabularies, or entirely arbitrary keywords. OpenAPI has its own vocabulary properties which MAY be used for further schema description: +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: ##### Fixed Fields From 4822592ab1fab9b891fa22955c492fc55891817a Mon Sep 17 00:00:00 2001 From: Phil Sturgeon Date: Thu, 9 Jan 2020 18:32:01 +0100 Subject: [PATCH 5/7] default should match json schema --- versions/3.1.0.md | 1 - 1 file changed, 1 deletion(-) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index d7844b0ed1..a92f03af69 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -2317,7 +2317,6 @@ The following properties are taken from the JSON Schema definition but their def - exclusiveMaximum - Value can be a numeric value just like JSON Schema, or for backwards compatibility with older drafts it can accept a boolean to act as a modifier to the `minimum` keyword. The numeric value usage is recommended. - 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. -- default - The default value represents what would be assumed by the consumer of the input as the value of the schema if one is not provided. Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object defined at the same level. For example, if `type` is `string`, then `default` can be `"foo"` but cannot be `1`. Alternatively, any time a Schema Object can be used, a [Reference Object](#referenceObject) can be used in its place. This allows referencing definitions instead of defining them inline. From d67f35050971b66448ea1b4e38692733c79fc3bc Mon Sep 17 00:00:00 2001 From: Phil Sturgeon Date: Thu, 9 Jan 2020 18:40:31 +0100 Subject: [PATCH 6/7] removed json schema keyworld list, its just all of em. --- versions/3.1.0.md | 34 +--------------------------------- 1 file changed, 1 insertion(+), 33 deletions(-) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index a92f03af69..6d832042d5 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -2276,39 +2276,7 @@ Unless stated otherwise, the property definitions follow the JSON Schema. ##### 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, including but not limited to: - -- $schema -- $id -- title -- required -- multipleOf -- maximum -- minimum -- maxLength -- minLength -- pattern (This string SHOULD be a valid regular expression, according to the [ECMA 262 regular expression](https://www.ecma-international.org/ecma-262/5.1/#sec-7.8.5) dialect) -- maxItems -- minItems -- uniqueItems -- maxProperties -- minProperties -- enum -- propertyNames -- contains -- const -- examples -- if / then / else -- dependentRequired / dependentSchemas -- deprecated -- additionalItems -- additionalProperties -- unevaluatedItems -- unevaluatedProperties -- maxContains -- minContains -- readOnly -- writeOnly +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 following properties are taken from the JSON Schema definition but their definitions were adjusted to the OpenAPI Specification. From bb9a6f273389d25c3dbbb1d126b1a6fa1d8a4c85 Mon Sep 17 00:00:00 2001 From: Phil Sturgeon Date: Thu, 9 Jan 2020 18:49:02 +0100 Subject: [PATCH 7/7] redundant $ref reference --- versions/3.1.0.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index 6d832042d5..e1ed6bc13c 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -2286,8 +2286,6 @@ The following properties are taken from the JSON Schema definition but their def - 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. -Alternatively, any time a Schema Object can be used, a [Reference Object](#referenceObject) can be used in its place. This allows referencing definitions instead of defining them inline. - 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: ##### Fixed Fields