JSON Schema Tutorial

What is JSON Schema

In this tutorial we will discuss JSON Schema, a proposed Internet draft defining a JSON media type (application/schema+json). Internet Engineering Task Force defines JSON Schema as follows:

"JSON (JavaScript Object Notation) Schema defines the media type "application/schema+json", a JSON based format for defining the structure of JSON data. JSON Schema provides a contract for what JSON data is required for a given application and how to interact with it. JSON Schema is intended to define validation, documentation, hyperlink navigation, and interaction control of JSON data."

Goals of JSON Schema

There are three main goals of JSON Schema: Validation, Documentation and Hyperlinking. We will discuss these three goals in brief in a moment.

Validation

Suppose there is an application which may interact with many different JSON services. So, there is a requirement for validation, i.e. you need to validate your JSON objects.

Documentation

This allows you to fetch documentation information form JSON Schema. Which in turn, may be used to match your data and also can be used for user interaction.

Hyperlinking

Heyperlinks can be created into the parts of your JSON data by coupling them with the JSON Schema.

JSON Schema validation Libraries

Following table gives an overview of JSON Schema libraries available :

Available Schemas

Core Meta-Schema

This is the meta-schema definition for type/validation part of Schemas themselves. The Schema is as following:

{
	"id" : "http://json-schema.org/schema#",
	"type" : ["object","string"],
	"format": "uri",
	
	"properties" : {
		"type" : {
			"type" : ["string", "array"],
			"items" : {
				"type" : ["string", "#"]
			},
			"uniqueItems" : true,
			"default" : "any"
		},
		
		"properties" : {
			"type" : "object",
			"additionalProperties" : "#",
			"default" : {}
		},
		
		"items" : {
			"type" : ["#", "array"],
			"items" : "#",
			"default" : {}
		},
		
		"required" : {
			"type" : "boolean",
			"default" : false
		},
		
		"additionalProperties" : {
			"type" : ["#", "boolean"],
			"default" : {}
		},
		"additionalItems" : {
			"type" : ["#", "boolean"],
			"default" : {}
		},
		
		"requires" : {
			"type" : ["string", "#"]
		},
		
		"minimum" : {
			"type" : "number"
		},
		
		"maximum" : {
			"type" : "number"
		},
		
		"exclusiveMinimum" : {
			"type" : "number"
		},
		
		"exclusiveMaximum" : {
			"type" : "number"
		},
		
		"minItems" : {
			"type" : "integer",
			"minimum" : 0,
			"default" : 0
		},
		
		"maxItems" : {
			"type" : "integer"
		},
		
		"uniqueItems" : {
			"type" : "boolean",
			"default" : false
		},
		
		"pattern" : {
			"type" : "string",
			"format" : "regex"
		},
		
		"minLength" : {
			"type" : "integer",
			"minimum" : 0,
			"default" : 0
		},
		
		"maxLength" : {
			"type" : "integer"
		},
		
		"enum" : {
			"type" : "array",
			"minItems" : 1,
			"uniqueItems" : true
		},
		
		"title" : {
			"type" : "string"
		},
		
		"description" : {
			"type" : "string"
		},
		
		"format" : {
			"type" : "string"
		},
				
		"maxDecimal" : {
			"type" : "number",
			"minimum" : 0
		},
		
		"disallow" : {
			"type" : ["string", "array", "#"],
			"items" : {
				"type" : ["string", "#"]
			},
			"uniqueItems" : true
		},
		
		"extends" : {
			"type" : ["#", "array"],
			"items" : "#",
			"default" : {}
		}
	},
	"links" : [
		{
			"href" : "{id}",
			"rel" : "self"
		}
	],
	
	"default" : {}
}

Hyper Meta-Schema

This is for schemas with link definition. The Schema is as following:

{
	"id": "http://json-schema.org/hyper-schema",
	"properties": {
		"links": {
			"type": "array",
			"items": { "$ref": "http://json-schema.org/links" }
		},
		
		"fragmentResolution": {
			"type": "string",
			"default": "slash-delimited"
		},
		
		"root": {
			"type": "boolean",
			"default": false
		},
		
		"readonly": {
			"type": "boolean",
			"default": false
		},
		
		"pathStart": {
			"type": "string",
			"format": "uri"
		},
		
		"mediaType": {
			"type": "string"
		},
		
		"alternate": {
			"type": "array",
			"items": { "$ref": "http://json-schema.org/hyper-schema-or-uri" }
		},
		
		"type": {
			"type": [ "string", "array" ],
			"items": {
				"type": [ "string", { "$ref": "http://json-schema.org/hyper-schema-or-uri" } ]
			},
			"uniqueItems": true,
			"default": "any"
		},
		"properties": {
			"type": "object",
			"additionalProperties": { "$ref": "http://json-schema.org/hyper-schema-or-uri" },
			"default": {}
		},
		"items": {
			"type": [ { "$ref": "http://json-schema.org/hyper-schema-or-uri" }, "array" ],
			"items": { "$ref": "http://json-schema.org/hyper-schema-or-uri" },
			"default": {}
		},
		"additionalProperties": {
			"type": [ { "$ref": "http://json-schema.org/hyper-schema-or-uri" }, "boolean" ],
			"default": {}
		},
		"additionalItems": {
			"type": [ { "$ref": "http://json-schema.org/hyper-schema-or-uri" }, "boolean" ],
			"default": {}
		},
		"contentEncoding": {
			"type": "string"
		},
		
		"default": {
		},
		
		"requires": {
			"type": [ "string", { "$ref": "http://json-schema.org/hyper-schema-or-uri" } ]
		},
		"disallow": {
			"type": [ "string", "array", { "$ref": "http://json-schema.org/hyper-schema-or-uri" } ],
			"items": {
				"type": [ "string", { "$ref": "http://json-schema.org/hyper-schema-or-uri" } ]
			},
			"uniqueItems": true
		},
		"extends": {
			"type": [ { "$ref": "http://json-schema.org/hyper-schema-or-uri" }, "array"],
			"items": { "$ref": "http://json-schema.org/hyper-schema-or-uri" },
			"default": {}
		}
	},
	
	"links": [
		{
			"href": "{$schema}",
			"rel": "describedby"
		},
		
		{
			"href": "{$ref}",
			"rel": "full"
		}
	],
	
	"fragmentResolution": "dot-delimited",
	"extends": { "$ref": "http://json-schema.org/schema" }
}

JSON Referencing

This Schema defines a generic linking mechanism used by meta-schemas for liking. The Schema is as following:

{
	"$schema": "http://json-schema.org/hyper-schema",
	"id": "http://json-schema.org/json-ref",
	
	"items": { "$ref": "#" },
	"additionalProperties": { "$ref": "#" },
	
	"links": [
		{
			"href": "{$ref}",
			"rel": "full"
		},
		
		{
			"href": "{$schema}",
			"rel": "describedby"
		},
		
		{
			"href": "{id}",
			"rel": "self"
		}
	]
	
	"fragmentResolution": "json-pointer"
}

JSON Schema Interfaces

This schema is for meta-schema definition for schemas which define class-style method interfaces for programming languages. The Schema is as following:

{
    "extends":"http://json-schema.org/hyper-schema",
    "description":"A schema for schema interface definitions that describe programmatic class structures using JSON schema syntax",
    "properties":{
        "methods":{
            "type":"object",
            "description":"This defines the set of methods available to the class instances",
            "additionalProperties":{
            	"type":"object",
            	"description":"The definition of the method",
            	"properties":{
            		"parameters":{
            			"type":"array",
            			"description":"The set of parameters that should be passed to the method when it is called",
            			"items":"#",
            			"required": true
            		},
            		"returns":"#"
            	}
            }
        }    
    }
}
            
			

Geographic Coordinate Card

This Schema is for microformat style representation of a person, company, organization or place. The Schema is as following:

{
	"description": "A geographical coordinate",
	"type": "object",
	"properties": {
		"latitude": { "type": "number" },
		"longitude": { "type": "number" }
	}
}

Calendar

This schema is for microformat style representation of an event. The Schema is as following:

{
	"description": "A representation of an event",
	"type": "object",
	"properties": {
		"dtstart": {
			"format": "date-time",
			"type": "string",
			"description": "Event starting time",
			"required": true
		},
		"dtend": {
			"format": "date-time",
			"type": "string",
			"description": "Event ending time"
		},
		"summary": { "type": "string", "required": true },
		"location": { "type": "string" },
		"url": { "type": "string", "format": "uri" },
		"duration": {
			"format": "time",
			"type": "string",
			"description": "Event duration"
		},
		"rdate": {
			"format": "date-time",
			"type": "string",
			"description": "Recurrence date"
		},
		"rrule": {
			"type": "string",
			"description": "Recurrence rule"
		},
		"category": { "type": "string" },
		"description": { "type": "string" },
		"geo": { "$ref": "http: //json-schema.org/geo" }
	}
}

Address

This schema is for microformat style representation of an address. The Schema is as following:

{
	"description": "An Address following the convention of http://microformats.org/wiki/hcard",
	"type":"object",
	"properties": {
		"post-office-box": { "type": "string" },
		"extended-address": { "type": "string" },
		"street-address": { "type": "string" },
		"locality":{ "type": "string", "required": true },
		"region": { "type": "string", "required": true },
		"postal-code": { "type": "string" },
		"country-name": { "type": "string", "required": true}
	},
	"dependencies": {
		"post-office-box": "street-address",
		"extended-address": "street-address"
	}
}

These are the Schemas available for mow, since this project is in the process of being updated, keep watching for more Schemas to come. By that time you may explore these schemas to validate your JSON objects and let us know what you reveal.