Openapi-specification: Documentation on JSON Schema compatibility/divergance?

[philsturgeon]

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 https://github.com/OAI/OpenAPI-Specification/issues/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]

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]

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

[webron]

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

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]

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

[philsturgeon]

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

[duartealexf]

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:

• https://www.npmjs.com/package/openapi-schema-to-json-schema
• https://github.com/kogosoftwarellc/openapi-jsonschema-parameters