Reduce duplications and complexity in v3.0 JSON Schema

[vearutop]

Current WIP Schema suffers from copy-paste, with these changes it can be improved.

Combine HTTP Methods in patternProperties

patternProperties:
  '^(get|put|post|delete|options|head|patch|trace)$': $ref: '#/definitions/Operation'

Combine some definitions as filtered supersets

In order to avoid massive duplication all possible properties can be defined in a superset.
Custom rules of exclusiveness can be further defined as a list of traits in allOf.

For example such structure does not allow having example and examples in same object:

not:
  required:
    - example
    - examples

Embed references

In order to simplify oneOf logic, many references can be embedded in respective definitions

All references to #/definitions/Schema are happening in such form:

oneOf:
  - $ref: '#/definitions/Reference'
  - $ref: '#/definitions/Schema'

Therefore #/definitions/Reference can be merged into #/definitions/Schema to simplify usages:

$ref: '#/definitions/Schema'

Validation difference after this change is that additional unknown properties are no longer accepted for References.
Such data would become invalid:

{"$ref": "#", "unknown":  1}

Validate example schemas

Modified schema fails validation against example schemas:

• petstore-expanded.yaml: GET /pets has query parameter tags with invalid style simple,
• api-with-examples.yaml: Object expected for examples, array received.

[handrews]

@vearutop I wish you'd commented on the issue before doing this. I'm thrilled to have someone else work on it but this is mostly but not quite a duplicate of what I was about to post later this week- it only didn't get posted during December because I got really sick for several weeks. So now I guess we try to put PRs next to each other and figure out the overlap and what needs to be kept from each :-/

[handrews]

@vearutop if you have any more of these in the works, please let me know- as I noted, it's great that you're working on this, and you may get things done faster than me. I'd just like to avoid duplication.

[vearutop]

I did this refactoring in just couple of hours, more like a demo of alternative approach. I don't mind to withdraw my PR or rebase it on anything else.

I don't have any other ideas to apply to this schema so far. :)

[handrews]

@vearutop oh, cool, glad this was a quick thing for you- I'll take a look in more detail. I'm more than happy to recommend merging yours if it works. I am not possessive here :-)

[handrews]

@vearutop @webron embarrassingly since commenting above I've been plagued by a series of minor illnesses and never quite getting caught up enough to attend to the OAS schema. :-( I haven't given up, but I'm currently coming down with my 4th cold in 2.5 months and I'm not sure when I'll be back to full strength and caught up with all of my projects.

[handrews]

This is largely the same as what I have had mostly-done in my working copy for quite a while, but been unable to finish and test.

I don't see any way for me to get back to working on this schema, as I told the TSC recently. JSON Schema's next draft has been stalled for 5 months, and I need to focus on that (instead of staring at both projects, feeling overwhelmed, and then not working on either).

So contrary to my prior comment, I'm officially giving up :-( At least until the next JSON Schema draft is published, and then I probably want to stop thinking about schemas for a bit :-P

However, this is great work and I hope other folks can follow up on it.

Thanks @vearutop for moving this forward, and I apologize for my initial reaction.

[MikeRalphson]

@vearutop could you look at breaking this PR down into smaller commits? The change I've so far spotted problems with is with folding the $ref object definition into surrounding objects and removing the oneOfs. If you look specifically at the response object, you seem to have made $ref a pattern property of the main object, but the constraint that description is required is still present. This leads my test suite to fail.

[vearutop]

@MikeRalphson sure, I can do that. Could you share few schemas that are failing validation if they are in public domain?

[MikeRalphson]

Sure, all of these point into https://github.com/APIs-guru/openapi-directory

../openapi-directory/APIs/6-dot-authentiqio.appspot.com/6/swagger.yaml:
../openapi-directory/APIs/adafruit.com/2.0.0/swagger.yaml:
../openapi-directory/APIs/agco-ats.com/v1/swagger.yaml:
../openapi-directory/APIs/aiception.com/1.0.0/swagger.yaml:
../openapi-directory/APIs/amazonaws.com/AWSMigrationHub/2017-05-31/swagger.yaml:
../openapi-directory/APIs/amazonaws.com/acm-pca/2017-08-22/swagger.yaml:

[vearutop]

@MikeRalphson indeed I underestimated the effect of embedding references. Having $ref in patternProperties of respective schema affects required and oneOf/allOf. Now I think the benefits of having embedded refs are not enough so I reverted that commit.

Please check again.

[MikeRalphson]

No other regressions detected across the APIs-guru collection. Good job!

[webron]

@vearutop we're having a meeting dedicated to the JSON Schema tomorrow. Feel free to join us if you want. Details are at https://openapi.groups.io/g/tsc/viewevent?repeatid=3837&eventid=428242&calstart=2019-03-21.

[darrelmiller]

Summary of TSC discussion

• We would like to revert the references to schema objects to use the oneOf syntax as referenced above in the "Embed Reference" comment.

[vearutop]

@darrelmiller done, please check.

[webron]

Thanks for all the work, @vearutop! You've definitely managed to elegantly reduce the size of the JSON Schema without compromising validation. Top-notch work!

@OAI/tsc - if I can get one or two more approvals, I'll merge this and make the final additions to my PR.