Skip to content

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

Closed
Closed
Support for JSON Schema Core v4, Wright Json Schema 01#1238
Milestone
v3.x-Candidate

Description

@fireproofsocks
fireproofsocks
opened on Jun 29, 2017

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

Activity

  1. gwittel commented on Jun 30, 2017

    @gwittel
    gwittel
    on 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
  2. RobDolinMS
    added this to the milestone on Jul 7, 2017
  3. RobDolinMS
    added
    Post 3.0 Proposal
    on Jul 7, 2017

  4. RobDolinMS commented on Jul 7, 2017

    @RobDolinMS
    RobDolinMS
    on Jul 7, 2017
    Contributor

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

  5. handrews commented on Oct 27, 2017

    @handrews
    handrews
    on Oct 27, 2017
    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.

  6. brendo commented on Oct 31, 2017

    @brendo
    brendo
    on Oct 31, 2017
    Contributor

    @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?

  7. handrews commented on Oct 31, 2017

    @handrews
    handrews
    on Oct 31, 2017
    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).

  8. tiangolo commented on May 20, 2019

    @tiangolo
    tiangolo
    on May 20, 2019
    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.

  9. Capstan commented on Oct 30, 2019

    @Capstan
    Capstan
    on Oct 30, 2019
    Contributor

    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.

  10. philsturgeon commented on Oct 30, 2019

    @philsturgeon
    philsturgeon
    on Oct 30, 2019
    Contributor

    Draft 2019-09 not Draft 09 :)

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

  11. handrews commented on Oct 30, 2019

    @handrews
    handrews
    on Oct 30, 2019
    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.

  12. Capstan commented on Oct 30, 2019

    @Capstan
    Capstan
    on Oct 30, 2019
    Contributor

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

  13. philsturgeon commented on Jan 9, 2020

    @philsturgeon
    philsturgeon
    on Jan 9, 2020
    Contributor

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

  14. darrelmiller
    closed this as completedon Jan 10, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions