Late in 2019, the API industry was abuzz about some new developments for two major description languages: OpenAPI and JSON. OpenAPI v2.0, when it was originally known as Swagger 2.0, was created to be an extended subset of JSON Schema. In the last quarter of 2019, OpenAPI v3.0 achieved up to 90% of compatibility with Draft 5 of JSON Schema, its predecessor.

This was great news for developers who’d spent time trying to bridge keywords that were, in a way, lost in translation. But where did the two diverge in the first place, and what strategies have developers used when choosing between them? Moreover, what do OpenAPI and JSON Schema compatibility have to do with the future of API design?

This article seeks to give a brief explanation about how schemas are meant to work. It will also detail the difference between the OpenAPI and JSON Schemas, and how these two were known to work alongside each other. This guide should also prove the advantages of an OpenAPI Specification Toolkit, a boon to working with both the JSON and OpenAPI description formats. And lastly, the article will turn all previous knowledge about JSON and OpenAPI on its head, thanks to industry developments as recent as February 2020.

A Review of the Basics: Schemas, JSON, and OpenAPI

To those learning about JSON and OpenAPI, one of the first questions asked is: what is a schema in the first place? In the parlance of API design, schemas are metadata that describe how data is structured. A schema, therefore, acts as a template for structuring data.

Technically speaking, you could implement an API’s endpoints without any sort of schema in place. But a previous generation of API developers found life without schemas to be incredibly difficult and messy. Today’s developers now see the value of designing APIs with a greater sense of structure. For them, schemas can simplify a lot of complex API design work by matching data patterns and organizing databases into reusable blocks. And the two most popular schemas, used like proverbial Rosetta Stones, are JSON and OpenAPI.

But here is where the two fundamentally differ. While JSON Schema can describe instances of JSON data (like those found in HTTP requests), OpenAPI can describe entire APIs. It does so by virtue of the multiple API Specification formats that it has at its disposal.

That said, let’s break down the enduring issues of OpenAPI and JSON Schema.

Issues of Compatibility

As recounted above, the versions of OpenAPI and JSON Schema circa late 2019 were 90% compatible with each other. To some developers, that 10% difference counted for a lot. It still stood for the fact that OpenAPI could not recognize, let alone support, some important JSON Schema keywords. It wasn’t a problem for those already using JSON Schema by default, but it was a point of frustration for those who were accustomed to OpenAPI.

The gaps in compatibility meant doing one of two things. The first option would be to do the added work of converting JSON Schema to OpenAPI Schema. The second option would be to keep using JSON Schema as usual, but also keeping an API version with keywords OpenAPI would support.

Do these pain points still exist, however? Some recent developments may prove otherwise.

The Future Indicates Greater Harmony

As of February 2020, both JSON Schema Draft 2019-09 and OpenAPI v3.1 have been rolled out. Among other things, OpenAPI is now defined as a small superset of JSON Schema and no longer a side set or a subset. Experts in JSON and OpenAPI have made the happy discovery that there’s no longer a list of supported keywords. That’s because all keywords that exist in JSON Schema 2019-09 can also be used in OpenAPI v3.1. In summary, choosing between OpenAPI and JSON Schema may now be a simple issue of which one your team is more knowledgeable of. One may still outweigh the other as their foregrounding to designing APIs. Now that API design tools are leveling up and becoming more in sync, it’s the perfect time for you to invest in them.