Visualise JSON Schema using JSON Schema Viewer

[sohilpandya]

Why
You have a really great schema in place, which is understood by all the technical people in your team, but what about the non-technical people? Visualisation of a schema will lead to better understanding of the schema across the team.

How
We will use JSON Schema Viewer to visualise the schema

[sohilpandya]

Steps to creating your very first visualisation of a schema

Repo Setup

1. Clone repository: git clone https://github.com/jlblcc/json-schema-viewer.git
2. Enter project directory: cd json-schema-viewer
3. Install dependencies via Bower: bower install
   • if you don't have bower installed: npm i -g bower. (strange decision by developer to have dependencies across both bower and npm.
4. Install dependencies via NPM: npm install

Schema Setup

You will notice that the documentation for getting a simple schema up and running is not so straight forward, so here is what I suggest:

• create a schemas folder with the following structure:
  
• Create a basic schema for user and address

schema.json

{
  "id": "schema.json#",
  "$schema": "http://json-schema.org/draft-04/schema#",
  "version": "1.1.3",
  "description": "schema for ADIwg mdJSON metadata",
  "type": "object",
  "required": ["version", "contact", "metadata"],
  "properties": {
    "user": {
      "$ref": "sub-schema/user.json",
      "example": "../schema-example/user.json"
    }
  }
}

user.json

{
  "id": "user.json#",
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Contains user details",
  "properties": {
    "first_name": {
      "type": "string"
    },
    "last_name": {
      "type": "string"
    },
    "address": {
      "type":"object",
      "properties": {
        "billing_address": {
          "$ref": "address.json",
          "example": "../schema-example/address.json"
        },
        "delivery_address": {
          "$ref": "address.json",
          "example": "../schema-example/address.json"
        }
      }
    },
    "age": {
      "type":"number",
      "maxValue": 100
    }
  }
}

address.json

{
  "id": "address.json#",
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Contains user address",
  "properties": {
    "street_name": {
      "type": "string"
    },
    "city": {
      "type": "string"
    },
    "postcode": {
      "type": "string"
    },
    "country": {
      "type": "string"
    }
  }
}

JSON-Schema-Viewer Setup

• Once you have the above files in place, we can tell the app to load the schema from the given folder, to do so, we need to specify the schema under json-schema-viewer.json file

Build & Run JSON Schema Viewer

• build the app using grunt prod
  • If you do not have gulp, then please install using npm i -g grunt
• create a local server to view the compiled files using grunt connect:server:keepalive
• access it using via http://localhost:9001

We have our very first JSON Schema Viewer

*And it should look something like this 🎉 *

To add examples for each json file, simple add some examples in json file and link it to the schema

Example user.json

{
  "id": "user.json#",
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Contains user details",
  "properties": {
    "first_name": {
      "type": "string"
    },
    "last_name": {
      "type": "string"
    },
    "address": {
      "type":"object",
      "properties": {
        "billing_address": {
          "$ref": "address.json",
          "example": "../schema-example/address.json"
        },
        "delivery_address": {
          "$ref": "address.json",
          "example": "../schema-example/address.json"
        }
      }
    },
    "age": {
      "type":"number",
      "maxValue": 100
    }
  }
}

• Connect the example as shown in the screenshot below
  

[sohilpandya]

Having experimented with this a little more, I feel that JSON Schema Viewer is rough around the edges, It works great if your schema is not too complex.