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

Update Schema Objects to JSON Schema Draft 2019-09 #1977

Merged
merged 7 commits into from
Jan 9, 2020
Merged

Update Schema Objects to JSON Schema Draft 2019-09 #1977

Changes from 4 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
ac236d1
Update Schema Object to proper JSON Schema
Jun 21, 2019
f8f92ed
update vocab and arbitrary props
Oct 25, 2019
e121405
another go at arbitrary keywords
Oct 28, 2019
5905f45
feedback from @handrews
Oct 29, 2019
4822592
default should match json schema
Jan 9, 2020
d67f350
removed json schema keyworld list, its just all of em.
Jan 9, 2020
bb9a6f2
redundant $ref reference
Jan 9, 2020
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
73 changes: 39 additions & 34 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).
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.
Expand Down Expand Up @@ -2269,23 +2268,23 @@ $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
##### Properties
philsturgeon marked this conversation as resolved.
Show resolved Hide resolved

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:
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 "a JSON Schema vocabulary"? is it a fork of the "JSON Schema vocabulary"? if so, shouldn't we call it the "OpenAPI vocabulary" as it is referred down below?

Where will this vocabulary be located? Can we see it? It would be nice to link it here, especially if tooling is required to support it.

Copy link
Contributor

Choose a reason for hiding this comment

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

A "JSON Schema vocabulary" is a specification which defines a set of keywords which have specific semantic meaning when applying a JSON Schema to a JSON instance.
A JSON Shema meta-schema defines the known vocabularies and if support for them is required in order to process the document.
You can see this in practice by looking at the General-purpose meta-schema for draft 2019-09 at http://json-schema.org/specification.html

The URI used as the vocabulary identifier, as like with $id, is not necessarily network addressable, and in the case of vocabularies, the identifier URI as a resources is reserved but not defined.

If you'd like to talk about this in more detail, feel free to come by the JSON Schema slack server, or reach out to any of the core team =]

Copy link
Contributor

@jstoiko jstoiko Nov 6, 2019 •
edited
Loading

Choose a reason for hiding this comment

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

I understand the mechanics. I guess where I want to get with this is: how will this look like when implementing this (practically-speaking). How will one be able to support OpenAPI Schemas using the vocabulary mechanism if none is provided (in this repo)? Will this mean it will be up to the implementor to maintain their own OpenAPI Schema vocabulary?

Copy link
Member

Choose a reason for hiding this comment

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

@jstoiko I'm not sure why you think none will be provided. This is about updating a certain part of the specification document to conform to 2019-09. It is not a PR to finalize every aspect of every issue related to updating JSON Schema ever. There are various other issues and PRs filed. PR #2016 in particular shows a first pass at a vocabulary meta-schema.

Please don't burden this PR with more work than it is already doing. It is already doing a lot.

Copy link
Contributor

Choose a reason for hiding this comment

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

How will one be able to support OpenAPI Schemas using the vocabulary mechanism if none is provided (in this repo)? - @jstoiko

The "vocabulary" IS the specification document which defines the additional keywords.

An implementer will implement a given vocabulary. There are implementations which DO stuff with OAS 3.0 flavour JSON Schema already, right?

An implementer will not "maintain a vocabulary". They may maintain a library which supports the vocabulary. As @handrews that, and a meta-schema for any potential vocabulary, is way beyond the scope of this PR.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

There’s no such thing as a vocabulary file so we’re good here.

Copy link
Member

@handrews handrews Nov 7, 2019 •
edited
Loading

Choose a reason for hiding this comment

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

There’s no such thing as a vocabulary file so we’re good here.

Correct. #2016 shows one possible meta-schema for the vocabulary, with a vocabulary URI that I just made up. The TSC may prefer to URI to either be a pure identifier, be the URI for the Schema Object specification, or be an identifier which redirects to the specification (which is more or less what we're doing with the official JSON Schema vocabulary URIs right now, although limitations of GitHub pages mean it's done in a slightly weird way using an HTML refresh https://json-schema.org/draft/2019-09/vocab/applicator ).

The recommendation in the JSON Schema spec is that vocabulary URIs be pure identifiers, with the idea being that we can add a formal vocabulary file type later. But that seems to confuse people too much so redirecting to the relevant specification is probably best for now.


- $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)
Expand All @@ -2294,46 +2293,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
philsturgeon marked this conversation as resolved.
Show resolved Hide resolved
- 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 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.
Copy link
Member

Choose a reason for hiding this comment

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

This suggestion aligns the nullable language with the OAS 3.0.3 language from PR #2046, with minimal wording tweaks to account for type now being able to have multiple values (type arrays).

Suggested change
<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="schemaNullable"></a>nullable | `boolean` | A true value adds `"null"` to the allowed type(s) specified by the `type` keyword, only if `type` is explicitly defined within the same Schema Object. Other Schema Object constraints retain their defined behavior, and therefore may disallow the use of `null` as a value. A `false` value leaves the specified or default value(s) of `type` unmodified. The default value is `false`.
<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.

Copy link
Contributor

Choose a reason for hiding this comment

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

Looks good. Thanks!

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I forgot to apply this suggestion, so its over here #2124

<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.

philsturgeon marked this conversation as resolved.
Show resolved Hide resolved
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.

philsturgeon marked this conversation as resolved.
Show resolved Hide resolved
While composition offers model extensibility, it does not imply a hierarchy between the models.
To support polymorphism, the OpenAPI Specification adds the `discriminator` field.
Expand Down