node package manager

Introducing npm Enterprise add-ons. Integrate third-party dev tools into npm…

jsontype

A small library that takes JSON structure descriptions and creates a function that validates if a javascript value is in exactly this structure.

Overview

JSONtype is a markup language that describes JSON data layout and allows you to validate random JavaScript values. This prevents you from writing lots of try-catch blocks or to get undefined results when processing malformed user input.

The JSONtype library is a schema validator library for JavaScript (mainly Node.js). It allows you to define your data structure in a compact way and create a JavaScript function from it. The validation is then just a function call.

Syntax

* - accepts everything but undefined values
string - only accepts string
mail - only accepts strings that are formed like an email
"abc" - only accepts string with exactly this content
number - only accepts numbers
boolean - only accepts true or false
function - only accepts a function
undefined - only accepts undefined (a object entry must not be defined)

[*] - accepts any array
[type] - accepts only arrays of that specified subtype

{name: type, name: type} - accepts only objects that have these properties with exactly these types
{name: type, * : undefined} - accepts only objects that have no other properties than the named ones
{*: type} - accepts only objects where all properties have the specified subtype
{name?: type} - accepts only objects that dont have this named property or the property has the specified type
{"name": type} - accepts only objects which have this named property with exactly this type (be careful, the parser is not perfect)

Caution: Do not accept validation schemas from the user because they could harm you.

Using jsontype in JavaScript and Node.js

    var jsontype = require('jsontype');
    var validator = jsontype.makeValidator('{username: string, password: string}');
    if(validator({username: 'peter', password: '123'})) {
        // do something 
    }

You can also define your own types as regexp or function like

    var jsontype = require('jsontype');
    function validatePassword(value) {
        // Password criteria 
        return typeof(value) === 'string' && value.length >= 8;
    }
    // we define two additional validators 
    // identifier forces strings via regexp to begin with a alphanumerical character 
    // pwstring forces strings via function to be at least 8 characters strong 
    var validator = jsontype.makeValidator('{username: identifier, password: pwstring}', {
        identifier: /^[a-zA-Z_][a-zA-Z_0-9]*$/,
        pwstring: validatePassword
    });
    if(!validator({username: 'peter', password: '123'})) {
        console.log('Check if your password fits the criteria');
    }

This especially makes sense if you want to compose validators to more complex situations.

makeValidator creates a Function which you can call with one parameter - the value to validate. The function returns true if the value validates successfully. It is good practise to create all validators at startup and then just call the generated functions. If you want to have an exception thrown instead of a boolean return value, use makeThrowValidator. It will create functions that exit with undefined or throw an exception.

Using jsontype in PHP

To use jsontype in PHP, e.g. to build JSON APIs, use jsontype2php.js

Usage:

  • node jsontype2php.js {username: string, password: string} for creating a function validate($x)
  • node jsontype2php.js $foo [mail] for creating a inline PHP statement that validates $foo

Some remarks:

  • you might need single quotes on command line for escaping the string and double quotes for string literals inside the schema
  • using custom types like validate_my_regex lead to calls to a function with the same name returning a boolean

Once you created a PHP snippet, copy+paste it into your code. This guarantees high performance and effective JSON validation.

More Examples

Look into runtests.js which provides a lot of test cases that cover all features of jsontype.