Merge pull request #1977 from philsturgeon/json-schema-update

Update Schema Objects to JSON Schema Draft 2019-09

Author: Ron

versions/3.1.0.md

@@ -139,10 +139,9 @@ It is RECOMMENDED that the root OpenAPI document be named: `openapi.json` or `op
 
 ### <a name="dataTypes"></a>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.
 
 <a name="dataTypeFormat"></a>Primitives have an optional modifier property: `format`.
 OAS uses several known formats to define in fine detail the data type being used.
@@ -2271,71 +2270,42 @@ $ref: definitions.yaml#/Pet
 
 #### <a name="schemaObject"></a>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 
-
-The following properties are taken directly from the JSON Schema definition and follow the same specifications:
-
-- title
-- 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)
-- maxItems
-- minItems
-- 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.
-- 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`.
+##### 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.
 
-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.
+The following properties are taken from the JSON Schema definition but their definitions were adjusted to the OpenAPI Specification.
 
-Additional properties defined by the JSON Schema specification that are not mentioned here are strictly unsupported.
+- 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.
 
-Other than the JSON Schema subset fields, the following fields MAY be used for further schema documentation:
+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
+
 Field Name | Type | Description
 ---|:---:|---
-<a name="schemaNullable"></a>nullable | `boolean` | Allows sending a `null` value for the defined schema. Default value is `false`.
+<a name="schemaNullable"></a>nullable | `boolean` | Allows sending a `null` value for the defined schema. Default value is `false`.<br><br>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`.<br><br>A `nullable` value of `false` leaves the specified or default `type` unmodified. It has no effect on the schema object.<br><br>**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.
 <a name="schemaDiscriminator"></a>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.
-<a name="schemaReadOnly"></a>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`.
-<a name="schemaWriteOnly"></a>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`.
 <a name="schemaXml"></a>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.
-<a name="schemaExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this schema. 
-<a name="schemaExample"></a>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.
-<a name="schemaDeprecated"></a> deprecated | `boolean` | Specifies that a schema is deprecated and SHOULD be transitioned out of usage. Default value is `false`.
+<a name="schemaExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this schema.
+<a name="schemaExample"></a>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.<br><br>**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). 
 
 ###### <a name="schemaComposition"></a>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.