Support for JSON Schema Core v4, Wright Json Schema 01

[fireproofsocks]

The OAS does not yet support a full implementation of the Json Schema spec. The Json Schema spec is currently at version 4, but version 5 purported close to release. Many of the bugs and feature requests I'm seeing in the issue tracker seem related to this spec (or the lack of it). Version 3 of the OpenAPI Spec mentions only Wright Json Schema 00, not 01, so several important advances are not accommodated.

Specifically important are:

• support for the $schema keyword to define which draft of the Json Schema is being used.
• support for the id keyword -- from my understanding this is how definitions and sub-schemas can be be "namespaced".

See http://json-schema.org/latest/json-schema-core.html

Some consequences of lacking full Json Schema support:

• the swagger definition files must be manually massaged to block out parts of the schema definitions.

Consideration for Meta issues for OpenAPI.Next

[gwittel]

draft-wright-01 adds useful, but possibly breaking features. Having a bunch of wright-01 (aka draft 06) schema, it would be really nice to not regress to draft-04 or draft-wright-01 features.

Core:

draft-wright-json-schema-01

        Updated intro
        Allowed for any schema to be a boolean
        "$schema" SHOULD NOT appear in subschemas, although that may change
        Changed "id" to "$id"; all core keywords prefixed with "$"
        Clarify and formalize fragments for application/schema+json
        Note applicability to formats such as CBOR that can be represented in the JSON data model

Validation:

draft-wright-json-schema-validation-01

        Standardized on hyphenated format names ("uriref" becomes "uri-ref")
        Add the formats "uri-template" and "json-pointer"
        Changed "exclusiveMaximum"/"exclusiveMinimum" from boolean modifiers of "maximum"/"minimum" to independent numeric fields.
        Split the additionalItems/items into two sections
        Reworked properties/patternProperties/additionalProperties definition
        Added "examples" keyword
        Added "contains" keyword
        Allow empty "required" and "dependencies" arrays
        Fixed "type" reference to primitive types
        Added "const" keyword
        Added "propertyNames" keyword

[RobDolinMS]

#TDC: Updating Issue Metadata so this is flagged for consideration after v3.0.0 release.

[handrews]

Barring unforeseen problems, draft-07 (which will either be draft-handrews-json-schema*-00 or draft-wright-json-schema*-02, possibly split, so let's just say draft-07), will be published by November 20th if not earlier.

Core changes:

• add $comment
• add an optional media type for use with instances

Validation changes

• add contentMediaType and contentEncoding (formerly Hyper-Schema's media object)
• add readOnly (formerly in Hyper-Schema)
• add writeOnly
• add if/then/else (which can be implemented with oneOf, but this is easier to read)
• add several formats, mostly around i18n and RFC 3339 dates and times
• restore accidentally deleted regex format
• formally define how to apply annotation keywords (such as title, description, readOnly, writeOnly, examples) to instances

If there is a need for the draft to be published more quickly in order to be useful here, please let me know. The final review period has been remarkably quiet, so maybe we don't need the whole planned month.

[brendo]

@handrews Thanks for the insight. Do you happen to know if there is a history document that shows how all the JSON Schema versions have come about and what's the equivalents? We're a bit lost as to what each of the specs actually refer to now. eg. draft-04 === wright-00? or draft-06? or something in between?

[handrews]

@brendo http://json-schema.org/specification-links.html
(although for the latest about-to-be-published work in progress you can find built docs at http://json-schema.org/work-in-progress )

The IETF drafts are named after the primary editor, and -00, -01 resets with each new name. The meta-schema numbers are sequential, though, so we often casually use those. All of the draft-06 documents are wright-01. The draft-04 documents were submitted by three different editors so they are zyp-04 (core), fge-00 (validation) and luff-00 (hyper-schema).

[tiangolo]

I'm asking about JSON Schema draft-07 here: #1466 (comment)

But I don't know if this would be the right issue to track it, updating the request to upgrade to JSON Schema draft-07, a.k.a draft- @handrews -json-schema*-01 instead of draft-04.

[Capstan]

draft-09 has just been published, though their specification-links section hasn't reflected the new draft docs. EDIT: Draft 2019-09 is published.

Also, @brendo, to follow-on to @handrews pointer, the Published Drafts section of the Specification Links page has a changes link for each specification which will point into an RFC appendix explaining what was changed. There's also Migrating from older drafts on the Specification page which gives IMO a slightly better read on the changes.

[philsturgeon]

Draft 2019-09 not Draft 09 :)

PR #1977 is sorting out the JSON Schema update, you can close this issue.

[handrews]

@Capstan

draft-09 has just been published, though their specification-links section hasn't reflected the new draft docs.

??? Where? As far as I know the specs and relevant links are updated everywhere.

[Capstan]

@handrews I totally misread the announcement, as @philsturgeon points out. Sorry. :(

[philsturgeon]

This was fixed in #1977 so we can close this.