Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

For discussion only; support JSON Schema Draft 6 in 3.1 #1766

Closed
wants to merge 2 commits into from
Closed

For discussion only; support JSON Schema Draft 6 in 3.1 #1766

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f724079
WIP; support JSON Schema Draft 6
MikeRalphson Nov 27, 2018
c0555d5
Missing ` in schemaObject.items definition
MikeRalphson Nov 28, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
87 changes: 48 additions & 39 deletions versions/3.1.0.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).
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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is proper meant in this case? If it's only there to differentiate from the current improper (subset/superset/sideset) situation, maybe we could drop it, or find another word which explains that a bit?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good idea, will peruse the thesaurus.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My intention was this specific meaning: https://mathinsight.org/definition/proper_superset

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cool!


<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.
Expand Down Expand Up @@ -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:https://json-schema.org/).
This object is a proper superset of the [JSON Schema Specification Wright Draft 01](http:https://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: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`.
- `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`.~~
MikeRalphson marked this conversation as resolved.
Show resolved Hide resolved
- `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: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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should probably make sure none of the formats added in the newer draft conflict with the ones OpenAPI defines. Putting this here as a reminder to check.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe you should run a copy of our registry site and we can both cross-reference before adding anything which conflicts?

- `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
Expand All @@ -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.

Expand Down