I’ve been doing my regular trolling of Github lately, looking for anything interesting. I came across a repository this week that contained JSON Schema for Kubernetes. Something that is interesting by itself, but I also thought the fact that they had autogenerated the individual JSON Schema files from the Kubernetes OpenAPI was worth a story. It demonstrates for me, the growing importance of schema in all of this, and shows that having them readily available on Github is becoming more important for API providers and consumers.
Creating schema is an important aspect of crafting an OpenAPI, but I find that many API providers, or the consumers who are creating OpenAPIs and publishing them to Github are not always investing the time into making sure the definitions, or schema portion of them are complete. Another aspect, as Gareth Rushgrove, the author of the Github repo where I found these Kubernetes schema points out, is the JSON Schema in OpenAPI often leaves much to be desired. Until version 3.0 it hasn’t supported everything you need, and many of the ways you are going to use these schema aren’t going to be able to use them in an OpenAPI, and you will need them as individual schema files like Gareth has done.
I just published the latest version of the OpenAPI for my Human Services Data API (HSDA) work, and one of the things I’ve done is extracted the JSON Schema into separate files so I can use them in schema validation, and other services and tooling I will be using throughout the API lifecycle. I’ve setup an API that automatically extracts and generates them from the OpenAPI, but I’m also creating a Github repo that does this automatically for any OpenAPI I publish into the data folder for the Github repository. This way all I have to do is publish an OpenAPI, and there is automatically a page that tells me how complete or incomplete my schema are, as well as generates individual representations that I can use independent of the OpenAPI.
I am hoping this is the beginning of folks investing more into getting their schema act together. I’m also hoping this is something that OpenAPI 3.0 will help us focus on more as well. Pushing API designers, architects, and developers to get their schema house in order, and publish them not just as OpenAPI, but individual JSON Schema, so they can be used independently. I’m investing more cycles into helping folks learn about JSON Schema as I’m pushing my own awareness forward, and will be creating more tooling, training material, and stories that help out on this front. I’m a big fan of OpenAPI, and defining our APIs, but as an old database guy I’m hoping to help stimulate the schema side of the equation, which I think is often just as important.
