It’s pretty easy to stand up an API. Unfortunately sometimes though, this easiness is a false friend you can be paying for down the road. Once you get any amount of consumers; even if they are internal, expressing the data models your API delivers and how it is validated can be a messy chore. You may write up some fancy documents describing your API (which is good); however, this can lack a bit in the area of tooling. This is where JSON Schema can really shine.
What is JSON Schema?
The JSON schema is a spec used to describe complex data structures. Because it has an official spec behind it, there are quite a few tools out there that you can use to take advantage of it. This gives you a way to publish agreed upon documents that other vendors can use to model the data from your API.
This schema is simple, but shows off how data can be described. This models a
person as having a
birthdate, and optionally
friends. Just glancing at it this all may seem pretty obvious except for
friends part. The
$ref is a way in the spec to reference another
part of your schema document. In this case it references the top level of the
schema which means that
friends can be an array of
More Complex Example
Part of the spec sets aside the key
definitions as an area where you can
define types so you don’t have to repeat them in your schema. Here is the same
schema from above using that as an example.
Example Referencing Another Schema
Of course sometimes you’ll have a rich set of models which reference each other.
Don’t worry, the spec also has a way to reference other documents via http.
This new spec expands upon the last one by adding in a
hobbies key, which
/hobby.json#. So what is happening here? The magic is in the
id. When a reference is relative like this the spec says to default to the
host found in the id field to resolve another schema file. If the uri in the
reference is a fully qualified url then the id is ignored and it will look for
it at the location given.
A couple gotchas here are the spec really only makes way for http and anything else, such as from disk, are unsupported. The other gotcha when referencing documents is there doesn’t appear to be a relative location ability built into the spec. This means if you start serving your documents under a new sub-directory you’ll have to go through all of your references and update them.
If you want to learn more about JSON Schema you can head on over to the official website at json-schema.org. In my next post I’ll cover some more advanced sections of the spec, including parts which are geared directly for determining what kind of urls you can build from the data models you have!