Solving OpenAPI and JSON Schema Divergence

••1 min read•
apijson-schemaapi-specsopenapi

Update 2020-02-02: This article has been replaced entirely, as the proposed workaround was written into a now abandoned project Speccy, and the long-term proposed solution “Alternative Schemas” has been punted to a later version of OpenAPI due to complications with the form it took.

Instead of using Speccy go grab Spectral, it’s everything I wanted Speccy to be but with 10x the functionality thanks to having a whole team of people working on it instead of just me and Mike. It doesn’t bother with the JSON Schema proper to OpenAPI-flavoured Schema conversion because you can use json-schema-to-openapi-schema for that, and we solved the divergence properly in OpenAPI without the need for workarounds…

Instead of worrying about Alternative Schemas, the JSON Schema <> OpenAPI divergence will be resolved in OpenAPI v3.1 thanks to #1977 being merged. The latest estimate for v3.1.0-RC1 is end of February, so tooling vendors should get to work on upgrading support for JSON Schema 2019-09 and other OpenAPI v3.1 changes.