I’ve made it no secret that I’m not a fan of XML. However, one of the advantages of XML that is constantly brought up is the ability to validate XML documentes using an XML Schema or DTD. I haven’t had much use for them myself, but seeing as many people consider this important, I figured there was no reason the same couldn’t be done in JSON. So I came up with a format for a JSON schema file (written in JSON, of course) and added a function to the CFJSON library to validate a JSON document based on a schema.
While I don’t have docs written for this, it’s pretty self-explanatory. Here’s an example of a schema that shows pretty much all the features I’ve put in it so far:
{
type: "struct",
keys: ["title","body","categories","start_date","active"],
items: {
title: {
type: "string", maxlength: 20, minlength: 8
},
body: {
type: "string", minlength: 1
},
categories: {
type: "array",
minlength: 1,
maxlength: 4,
items: {
type: "struct",
items: {
id: {
type: "number", min:6, max:10
},
name: {
type: "string"
}
}
}
},
start_date: {
type: "date", mask: "mm-dd-yyyy"
},
active: {
type: "boolean"
}
}
}
In a nutshell, your schema is always an object/struct and it must always have a “type” key set. Then you go on nesting more definitions under the “items” key if you have more complex data types like structs or arrays. The valid types right now are “struct”, “array”, “date”, “number”, “boolean”, and “string”. Each of these data types have some additional options, which are explained below.
struct
For a type “struct, you have two additional keys you can add. The first is “keys”, in which you can provide an array of the keys that this structure MUST have. The second is “items”, which is a structure with keys for each structure key you want to add validation rules for. The “keys” and “items” values are both optional. You can specify an array of keys without providing “items” and vice-versa.
array
An “array” type can take 3 additional parameters, “minlength”, “maxlength”, and “items”. The first two are pretty self-explanatory, they check for a certain array length. The last is similar to the “struct” type’s “items” key, except inside that structure you do not list validation individually for keys since arrays are just numeric. So you simply put in the structure you want for all the items in the array.
date
The only option for the “date” struck type is “mask”. In it you can specify a date mask that you want the date to conform to. The possible masks are the same as the ones used by ColdFusion’s DateFormat function, although this could change because JSON is a universal format not restricted to CF.
number
A “number” type provides additional options of “min” and “max”, which allows you to specify minimum and maximum values for a number. Note that right now the “number” type allows for floats too, this will eventually be updated to allow for validating for integers, floats, unsigned numbers, etc.
boolean
The boolean type has no additonal options, although eventually it’ll probably allow for choosing what can be considered a valid boolean.
string
The “string” type can specify a “maxlength” and “minlength” option that will make sure the string is not longer or shorter than the values specified. Note that the “string” type will actually accept booleans and numbers. Right now I’m not seeing a way around it given the way I implemented things, and I’m not sure it’s really a big deal.
After defining the JSON schema standard I added a validate() function to CFJSON that validates a JSON document based on a schema conforming to the format described above. I also made a small example, creating a JSON document that conforms to the schema above and running the validate function against it. There’s a link to download the example below, all you have to do is change some values in the document or in the schema to see the validation working. There are a few more options that are probably easy to figure out looking at the code, such as the “errorVar” and “stopOnError” arguments. If anybody has any feedback on this I’d love to hear it.
DOWNLOAD CFJSON DOCUMENT VALIDATION EXAMPLE (includes the latest CFJSON)
FIND OUT MORE ABOUT CFJSON