Documentation on JSON Schema compatibility/divergance?

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.

[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

[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.