From f72407986f8e123bfaea56d0cde915845df50537 Mon Sep 17 00:00:00 2001 From: Mike Ralphson Date: Tue, 27 Nov 2018 23:43:39 +0000 Subject: [PATCH 1/2] WIP; support JSON Schema Draft 6 --- versions/3.1.0.md | 87 ++++++++++++++++++++++++++--------------------- 1 file changed, 48 insertions(+), 39 deletions(-) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index f0c7f54abe..50dccd6f69 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). -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. +Primitive data types in the OAS are based on the types supported by the [JSON Schema Specification Wright Draft 01](https://tools.ietf.org/html/draft-wright-json-schema-01#section-4.2). +`null` is only supported as a type modifier (see [`nullable`](#schemaNullable) for an alternative and equivalent method of achieving nullable types). +Models are defined using the [Schema Object](#schemaObject), which is a proper superset of JSON Schema Specification Wright Draft 01. Primitives have an optional modifier property: `format`. OAS uses several known formats to define in fine detail the data type being used. @@ -2268,50 +2267,60 @@ $ref: definitions.yaml#/Pet 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](http://json-schema.org/). +This object is a proper superset of the [JSON Schema Specification Wright Draft 01](http://json-schema.org/) with some additional processing rules. -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). +For more information about the properties, see [JSON Schema Core](https://tools.ietf.org/html/draft-wright-json-schema-01) and [JSON Schema Validation](https://tools.ietf.org/html/draft-wright-json-schema-validation-01). 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](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`. +- `title` +- `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` +- `required` +- `enum` +- `const` +- `examples` +- `contains` +- `propertyNames` + +The following properties are taken directly from the JSON Schema definition, but MUST be ignored: + +- `$id` and `id` for compatibility with OAS 3.0. +- `$schema` and `schema` for compatibility with OAS 3.0. + +The following properties are taken from the JSON Schema definition but their definitions were adjusted within the OpenAPI Specification. +- `type` - Value MUST be a string, or an array where one and only one value MUST be `null` and the array MUST have exactly two elements. +- `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](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`. +- `exclusiveMaximum` - may be a `boolean` or a `number`, for compatibility with OAS 3.0. +- `exclusiveMinimum` - may be a `boolean` or a `number`, for compatibility with OAS 3.0. +- `patternProperties` - Property definitions MUST be a [Schema Object](#schemaObject) and not a standard JSON Schema (inline or referenced). 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. +~~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: +Other than the JSON Schema fields, the following fields MAY be used for further schema documentation: ##### Fixed Fields Field Name | Type | Description @@ -2334,10 +2343,10 @@ The OpenAPI Specification allows combining and extending model definitions using While composition offers model extensibility, it does not imply a hierarchy between the models. To support polymorphism, the OpenAPI Specification adds the `discriminator` field. -When used, the `discriminator` will be the name of the property that decides which schema definition validates the structure of the model. +When used, the `discriminator` will define the name of the property that decides which schema definition validates the structure of the model. As such, the `discriminator` field MUST be a required field. There are two ways to define the value of a discriminator for an inheriting instance. -- Use the schema name. +- Use the schema name. The schema name is the last component of the JSON Pointer reference to the schema within the OAS document or the `$ref` used to reference it. - Override the schema name by overriding the property with a new value. If a new value exists, this takes precedence over the schema name. As such, inline schema definitions, which do not have a given id, *cannot* be used in polymorphism. From c0555d5270bd52f00ee07469620e3c752563d4eb Mon Sep 17 00:00:00 2001 From: Mike Ralphson Date: Wed, 28 Nov 2018 22:03:30 +0000 Subject: [PATCH 2/2] Missing ` in schemaObject.items definition --- 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 50dccd6f69..2eee17c17d 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -2306,7 +2306,7 @@ The following properties are taken from the JSON Schema definition but their def - `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`.~~ +- `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](http://spec.commonmark.org/) MAY be used for rich text representation.