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

Documentation on JSON Schema compatibility/divergance? #1263

Closed
philsturgeon opened this issue Jul 12, 2017 · 7 comments
Closed

Documentation on JSON Schema compatibility/divergance? #1263

philsturgeon opened this issue Jul 12, 2017 · 7 comments

Comments

@philsturgeon
Copy link
Contributor

philsturgeon commented Jul 12, 2017

Hey there!

Great work so far getting Open API v3.0 ready, you folks are crushing it. Good luck with the upcoming release.

My initial goal, and my idea of a perfect workflow for API specification, is JSON Schema based contracts. I want JSON Schema files for each resource in each API, being utilized in multiple ways, only one of which is documentation.

I moved away from API Blueprint to achieve this workflow, and Open API v2.0 is moving me a bit closer, but not really. My definitions are broken up into multiple .json files, but they're not JSON Schema. They're a mess of Swagger v2.0, vendor extensions, and backported features like example and nullable supported by ReDoc.

In #229 I spoke to @webron and @darrelmiller about some of this, but that was a specific conversation about "type": ["string", "null"] vs nullable: true. This is only one difference.

Where can I find out what other differences exist between JSON Schema Draft v4 and Open API Schema objects.

If I can find a full list, maybe I could build a conversion script to get me my JSON Schema files. I know v3.0 is way more in line with JSON Schema than v2.0 is, but I really need specifics on this, and those are hard to find.

@darrelmiller
Copy link
Member

We are based off the draft-00 version here https://tools.ietf.org/html/draft-wright-json-schema-00

The differences between JSON Schema and the OpenAPI Schema Object are listed here https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.md#properties in the list right after the list of properties that are unchanged.

@philsturgeon
Copy link
Contributor Author

Oh man, thank you. Sorry I missed this! I'll see what I can knock find or knock up RE conversion.

@webron
Copy link
Member

webron commented Jul 12, 2017

@philsturgeon actually took extra this this time to include all those elusive details that were missed in 2.0 - so feedback is welcome. Not specifically about whether the divergence is acceptable but rather whether it's clear 😉 It's just not going to change for 3.0 at this point in time. Please keep in mind that the release is scheduled for next week, so time is of the essence for the feedback.

@philsturgeon
Copy link
Contributor Author

Absolutely! Being clear about the divergence at this point is exactly what im asking for, acceptable is another conversation entirely.

Thank you for documenting this, and sorry again for somehow missing it. Trying to catch up on a few years with of discussions this week has been... challenging. 👍

@MikeRalphson
Copy link
Member

@philsturgeon this might be interesting for you https://github.com/garethr/openapi2jsonschema

@philsturgeon
Copy link
Contributor Author

Thanks @MikeRalphson, that'll definitely be handy. I had a Google around but couldn't find anything.

@duartealexf
Copy link

The differences between JSON Schema and the OpenAPI Schema Object are listed here

the correct link for the documentation is now: https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md

Some more converters for js:

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

5 participants