JSON, the JavaScript Object Notation, has a somewhat misleading name, since it is used for data exchange in a lot of places that have nothing to do with JavaScript. It has become very common that web-services encode all sorts of payloads using JSON, which is then decoded on the receiving end, using libraries like Google’s gson, which can automatically convert JSON documents into Java objects.

In many applications, JSON has replaced XML, which used to be the premier encoding format, used by web-services. JSON is more compact and arguably more readable; with XML however, XML-Schema was used to document or explain and also validate XML encoded data structures.

Fortunately, JSON is catching up in this respect as well. While still under development, the current 4th draft is quite good and already supported by many tools.

JSON-Schema

JSON Schema is a powerful tool for validating the structure of JSON data. Just like an XML-Schema is written in XML, a JSON-Schema is written in JSON, i.e. has to be a valid JSON document by itself. While typical JSON-Validation just checks for a correct syntax of the document, e.g., every opening curly brace has a closing one etc., a JSON-Schema allow for content validation, for instance that a document contains all the required properties, but not any unknown ones.

A good introduction into JSON Schema can be found in Michael Droettboom’s free book Understanding JSON Schema and of course by taking a closer look at the JSON Schema Core Definition.

To get started with creating a JSON Schema out of existing JSON data, take a look at http://jsonschema.net. One if not the best tools for experimenting with JSON-Schema is the home of the json-schema-validator, which allows to load schema and data, and perform the validation directly on their site.

Quick Intro

To make this a less abstract and a little more hands on, here is a short example:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "My Notification Schema",
  "description": "JSON Schema for Notification that can be interpreted by my app",
  "id": "https://wolfpaulus.com/",
  "type": "object",
  "required": [
    "style"
  ],
  "additionalProperties": false,
  "properties": {
    "BigTextStyle": {
      "description": "used when declaring a BigTextStyle Notification",
      "properties": {
        "bigContentTitle": {
          "description": "Content Title for a BigTextStyle notification",
          "type": "string"
        },
        "bigText": {
          "description": "Content Text for a BigTextStyle notification",
          "type": "string"
        }
      },
      "type": "object"
    },

The top level $schema property declares which version of JSON-Schema should be applied during validation. The required property is used to declare an array, containing all properties, which must be available in a valid JSON data document, and if the additionalProperties property is set to false, any JSON document that contains properties not declared in this schema, would be invalid. The following properties property now declares (optional and/or required) structures that make up a valid JSON document.

JSON Schema for Validation

Like aforementioned, JSON Schema is used to validate JSON data beyond simple syntax validation (like for instance performed by JSON Lint). JSON-Schema Validators exist, implemented in several languages and can be found here http://json-schema.org/implementations.html. Again, a good online validator for ad hoc testing is this Java Web-service http://json-schema-validator.herokuapp.com

JSON Schema for Documentation

While JSON documents are easily readable, examples are not always the best and rarely provide a complete form of documentation. JSON Schema can complement example documents, to provide an unabridged overview.

The matic tool can be used to generate HTML encoded documentation based of a JSON-Schema. On Mac OS X install it like so:

• To install HomeBrew, run
  • ruby -e “$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)”
• brew install npm
• npm install -g jade
• npm install -g matic

Building the HTML documentation

• download this sample template project: https://github.com/mattyod/matic-draft4-example
• navigate into ~/Downloads/matic-draft4-example-master
• add your JSON Schema into the ./schemas folder
• execute the matic command in terminal and you should see something like this “Matic Documentation built to web”
• finally, open ~/Downloads/matic-draft4-example-master/web/index.html in your web browser