JSON Validation with JSON Schema

It didn't take long for JSON to become the hottest thing since Pam Anderson slowly bounced her way down the BayWatch beaches. And why shouldn't it be? JSON is easy to understand visually, easy to parse on both the client and server sides, and is supported in just about every language except aborigine. There is however one problem I see with the way JSON is used by developers today: lack of validation. Most developers assume the JSON provide is not only error-free also in the proper format. Bad assumption. Let me show you how Kris Zyp's JSON Schema can help you validate JSON on both the client and server sides.

What is JSON Schema?

JSON Schema is a standard (currently in draft) which provides a coherent schema by which to validate a JSON "item" against. Properties within the schema are defined and with another object containing their expected type. For example:

"myObj" : { "type" : "array", "properties" : { "id": { "type": "number" }, "username": { "type" : "string" } } }

Besides providing the required type , other properties can be defined, including:

items : This should be a schema or an array of schemas. When this is an object/schema and the instance value is an array, all the items in the array must conform to this schema.

: This should be a schema or an array of schemas. When this is an object/schema and the instance value is an array, all the items in the array must conform to this schema. optional : Notes if the property should be considered optional

: Notes if the property should be considered optional requires : This indicates that if this property is present in the containing instance object, the property given by requires attribute must also be present in the containing instance object.

: This indicates that if this property is present in the containing instance object, the property given by requires attribute must also be present in the containing instance object. maxItems : Defines the maximum number of items in the collection

Numerous other properties are available, all of which may be found at: http://tools.ietf.org/html/draft-zyp-json-schema-03

Defining a Simple JSON Schema

Let's say that our application requires data in the following format:

{ users: [ { id: 1, username: "davidwalsh", numPosts: 404, realName: "David Walsh" }, { id: 2, username: "russianprince", numPosts: 12, realName: "Andrei Arshavin" } ] }

Right away we can see:

The object has a users property

The users property is an array

The users array contains objects

Each object has an id (number), username (string), numPosts (number), and realName (string)

With this structure in mind, we can create a simple schema to validate our expected format:

{ "type" : "object", "properties" : { "users" : { "type" : "array", // remember that arrays are objects "items" : { // "items" represents the items within the "users" array "type" : "object", "properties" : { "id": { "type": "number" }, "username": { "type" : "string" }, "numPosts": { "type" : "number" }, "realName": { "type" : "string", optional: true } } } } } }

dojox.json.schema and JSON Schema - Client Side

A JSON Schema validation routine is available with dojox.json.schema . The validate method accepts two arguments: your JSON to validate and the schema. Let's load the schema we created above, along with the sample JSON we created, and validate it:

// Require the json scheme module dojo.require("dojox.json.schema"); // When resources are ready dojo.ready(function() { // Load the schema dojo.xhrGet({ url: 'schema.json', handleAs: 'json', load: function(schema) { // Now load the JSON dojo.xhrGet({ url: 'users.json', handleAs: 'json', load: function(users) { // Now validate it! var result = dojox.json.schema.validate(users,schema); // Show the result console.log(result); } }); } }); });

A true valid property signals that the JSON is valid. If the result fails validation, valid will be false and the errors property will contain an array of error messages detailing why the given property did not pass validation. Here's a sample return result with errors:

{ errors: [ { message: "is missing and not optional", property: "users" } ] valid: false }

How you handle invalid data is up to you; moving forward with invalid data could present a security risk for both your organization and the user.

CommonJS-Utils and JSON Schema - Server Side

Kris also provides a server side JSON Schema validation routine within his CommonJS Utils project on GitHub. I've installed this project using NPM for NodeJS:

npm install commonjs-utils

Within this package is a json-schema resource. The following snippet requires that resources, reads in the schema and data JSON files, and validates the data JSON against the schema:

// Require Sys and FileSystem var sys = require('sys'), fs = require('fs'); // Require package var validate = require('commonjs-utils/json-schema').validate; // Load a schema by which to validate fs.readFile('schema.json',function(err,data) { if(err) throw err; var schema = data; // Load data file fs.readFile('./users.json',function(err,data) { if(err) throw err; // Parse as JSON var posts = JSON.parse(data); // Validate var validation = validate(posts, schema); // Echo to command line sys.puts('The result of the validation: ',validation.valid); }); });

To run this via the command line:

node server-validate.js

The server side uses the exact same schema and data as the client side, so your web application can be covered on both fronts.

Closing Thoughts on JSON Schema

JSON Schema is still a draft but I think Kris has done an outstanding job in creating the draft and coding server and client side validators. JSON validation is often overlooked and the data is wrongly assumed as correct. The resources for data validation are available -- it's up to you to use them!