---
published: true
layout: post
title: A OpenAPI and JSON Schema for JSON:API
tags:
  - JSON API
  - OpenAPI
  - JSON Schema
  - Responses
image: >-
  https://kinlane-productions2.s3.amazonaws.com/algorotoscope-master/bf-skinner-fixing-satellite-1.jpeg
---
I love getting sucked down into standards rabbit holes. As long as I don’t get lost for many days it usually results in fruitful outcomes. I am working on my base structure that I will use across all of the API Evangelist APIs I am developing. I like using [JSON:API](https://jsonapi.org/) for responses because of the flexibility the meta and data properties provide, but also the “hypermedia light” links properties. To be honest I don’t fully know the rest of it, but I will spend more time learning how it all works—-I just wanted to get started with the fundamentals that I’ve used before, meta and data. 

To accomplish what I needed I wanted to find an OpenAPI for JSON:API, and while Googling I came across [Phil’s amazing (as always) work comparing OpenAPI and JSON:API](https://apisyouwonthate.com/blog/json-api-openapi-and-json-schema/)-which was a little higher level and less hands-on than I wanted. I also came across [a forum discussion on the subject](https://discuss.jsonapi.org/t/openapi-3-0-spec-that-conforms-to-json-api/1803/4), which mostly just talked about the absence of an OpenAPI for the JSON:API, but then a link on one of the posts led me to a [Columbia University course API developed as part of a Django training](https://github.com/columbia-it/django-jsonapi-training/blob/master/docs/schemas/openapi.yaml) which used JSON:API for the course, complete with a beautiful API, but what made me happy is it had a [supporting JSON Schema for JSON:API](https://github.com/columbia-it/django-jsonapi-training/blob/master/docs/schemas/original-jsonapi.json), which actually gets to the point of what I wanted—JSON Schema always leaves me feeling validated. ;-) However, I noticed they were using JSON Schema draft-06, so I fired up [AlterSchema](https://alterschema.sourcemeta.com/) and converted to the latest draft — thank you [Juan Cruz Viotti](https://www.linkedin.com/in/jviotti/)--you should always be working with the latest draft of JSON Schema—no excuses.

<script src="https://gist.github.com/kinlane/4563655cd1d37f5d7e649abbf938c9dd.js"></script>

I now have my JSON Schema, and I need this standalone artifact to validate my response payloads, but I also need this JSON Schema delivered as an OpenAPI. Now, I want to be clear, I am only going after the “success” capabilities of JSON:API. I am not interested in the error payload and I am still on the fence about needing the info representations. I am using Problem Details for HTTP APIs to communicate errors, so the JSON:API errors don't interest me. I have the following OpenAPI started to help me continue working on the base of my APIs, but also provide something in the API Commons that I can keep working on based upon other API producer’s needs.

<script src="https://gist.github.com/kinlane/83f5e2c36dada98b21c04ad03c71c9e9.js"></script>

I am only interested in the meta and data properties right now, so I make sure I have an example that validates the present for that. I’ve also added a pagination example that I had to clean up the JSON Schema a bit to get to validate properly. I am just starting with these two examples right now, which I will make sure to validate. I will add additional example JSON:API examples as I need them, or as I get asked by others. My goal is to not boil the ocean with JSON:API, but tackle only what I need, and publish something to the API Commons. This is an example of how my work on APIs.io and API Evangelist feed into API Commons, providing more base and blueprint API artifacts that can be used and reused as part of API development.

In reverse engineering the original Columbia course API I found their use of JSON:API and OpenAPI very interesting, and the fact that they were still on draft-06 JSON Schema interesting, but they also publish an AWS version of their OpenAPI in their repo too. I see this more and more, and I am working on an overlay approach to managing my AWS extensions as part of my API governance. I like having each layer of my API platform overlayed on top of my core API definition. I will do more work and storytelling around AlterSchema, AWS OpenAPI extensions, as well as more work on the JSON:API OpenAPI and JSON Schema artifacts—-[if you have a specific need feel free to submit an issue on the API Commons repository](https://github.com/api-commons/json-api). 

A lot of folks get confused by the number of API specifications available out there, struggling with the difference between OpenAPI, JSON Schema, JSON:API, APIs.json, Postman Collections, and other specifications we depend on-—where I embrace the multi-specification reality we live in, and hope to bind them together using APIs.json. I will keep doing this through my [API Commons](https://apicommongs.org) work, publishing new artifacts like the [JSON:API OpenAPI and JSON Schema](https://github.com/api-commons/json-api), and telling stories about them here on API Evangelist. JSON:API is an extremely useful API standard, but I also see it as one standard in a patchwork of API standards we are going to need to define our enterprise API landscape. But, for right now, I am just looking to ensure that all of the APIs I deploy to power APIs.io and API Evangelist have consistent API responses using the JSON:API standard.