OpenShift JSON Schemas

For the upstream Kubernetes schemas instead see garethr/kubernetes-json-schema.

While exploring tooling for Kubernetes I had need for schemas to describe the definition files, and went looking for something that didn't require either kubectl or similar installed or even a working Kubernetes installation.

It turns out that the OpenAPI specification contain this information, but not in a particularly usable format for tools which might just want a raw JSON Schema.

This repository contains a set of schemas for most recent OpenShift versions. For each specified versions you should find three different flavours:

• vX.Y.Z - URL referenced based on the specified GitHub repository
• vX.Y.Z-standalone - de-referenced schemas, more useful as standalone documents
• vX.Y.Z-local - relative references, useful to avoid the network dependency

Example

Here are the links to the latest deployment schemas for OpenShift 1.5.1:

• v1.5.1/deployment.json
• v1.5.1-standalone/deployment.json
• v1.5.1-local/deployment.json

Usage

There are lots of use cases for these schemas, they are primarily useful as a low-level part of other developer workflow tools. But at a most basic level you can validate a definition file.

Here is a very simply example using the Python jsonschema client and an invalid deployment file:

$ jsonschema -F "{error.message}" -i hello-nginx.json 1.5.1-standalone/deployment.json
u'template' is a required property

Specific ideas

As noted these schemas have lots of potential uses for development tools. Here are a few ideas, some of which I've been hacking on:

• Demonstrating using with the more common YAML serialisation
• Testing tools to show your Kubernetes configuration files are valid, and against which versions of Kubernetes
• Migration tools to check your config files are still valid against master or beta releases
• Integration with code editors, for instance via something like Schema Store
• Validation of Kubernetes configs generated by higher-level tools, like Helm, Ksonnet or Puppet
• Visual tools for crafting Kubernetes configurations
• Tools to show changes between Kubernetes versions

Prior-art

The discussion around wanting JSON Schemas for Kubernetes types has cropped up in a few places, but there are some useful comments on this issue. Joël Harkes reached a similar conclusion to the approach I ended up taking.

Building the schemas yourself

The tooling for generating these schemas is openapi2jsonschema. It's not Kubernetes specific and should work with other OpenAPI specificied APIs too.