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.

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

Support for JSON Schema Core v4, Wright Json Schema 01 #1238

Closed
fireproofsocks opened this issue Jun 29, 2017 · 11 comments
Closed

Support for JSON Schema Core v4, Wright Json Schema 01 #1238

fireproofsocks opened this issue Jun 29, 2017 · 11 comments

Comments

@fireproofsocks
Copy link

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
Copy link

gwittel commented Jun 30, 2017

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 RobDolinMS added this to the v3.Next milestone Jul 7, 2017
@RobDolinMS
Copy link
Contributor

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

@handrews
Copy link
Member

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
Copy link
Contributor

brendo commented Oct 31, 2017

@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
Copy link
Member

@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
Copy link
Contributor

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
Copy link
Contributor

Capstan commented Oct 30, 2019

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
Copy link
Contributor

Draft 2019-09 not Draft 09 :)

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

@handrews
Copy link
Member

@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
Copy link
Contributor

Capstan commented Oct 30, 2019

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

@philsturgeon
Copy link
Contributor

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

9 participants