skeemas

Comprehensive JSON Schema (drafts 3 and 4) validation.

Installation

npm install skeemas --save

Basic Validation

skeemas.validate(subject, schema[, options])

var skeemas = require('skeemas');
 
skeemas.validate('foo', { type:'string' }).valid; // true
skeemas.validate(10000, { type:'string' }).valid; // false
skeemas.validate(10000, { type:'number' }).valid; // true
 
// Result contains an array of errors
var result = skeemas.validate('test', { enum:['foobar'], minLength:5 });
result.valid; // false
result.errors; // array with 2 error objects
 
// Pass the "breakOnError" option to stop processing on the first error
var result = skeemas.validate('test', { enum:['foobar'], minLength:5 }, { breakOnError:true });
result.valid; // false
result.errors; // array with 1 error object
 
var result = skeemas.validate({
    foo: 'bar',
    nested: {
        stuff: [1,2,3],
        ignoreMe: 'undeclared property'
    }
}, {
    properties: {
        foo: { type:'string' },
        nested: {
            properties: {
                stuff: {
                    type: 'array',
                    items: { type:'integer' }
                }
                // We aren't going to declare `ignoreMe`. To disallow extra 
                // props we could set `additionalProperties:false`.
            }
        }
    }
}); 
result.valid; // true
assert.deepEqual(result.cleanInstance, {
    foo: 'bar',
    nested: {
        stuff: [1,2,3]
        // notice the `ignoreMe` property is removed from `cleanInstance`
    }
});

For more information about constructing schemas see http://json-schema.org/ or the wonderful guide at http://spacetelescope.github.io/understanding-json-schema/index.html

Adding Schemas

Skeemas supports validation by schema id and refrences between schemas via the $ref property:

// Create an instance of a validator
var validator = require('skeemas')();
 
// Add schemas to the validator
validator.addRef({ type:'string', pattern:'^[a-z0-9]+$' }, '/identifier');
 
// Validate by uri/id
validator.validate('foo123', '/identifier').valid; // true
 
// Use a $ref reference in other schemas
validator.validate(user, { 
    type: 'object',
    properties: {
        id: { '$ref':'/identifier' },
        name: { type:'string' }
    } 
}).valid; // true

Related Modules

• skeemas-body-parser - json body parser middleware with schema validation
• skeemas-markdown-validation - simple testing of json blocks in your markdown documentation

Development

Our tests are running the JSON Schema test suite at https://github.com/json-schema/JSON-Schema-Test-Suite. Those tests are referenced as a submodule and therefore dev setup is a little non-standard.

# clone the repo 
 
# install dependencies from npm 
npm install
 
# install the test suite 
git submodule init
git submodule update
 
# run the tests 
npm test

Feature Status

• Full Validation (all errors)
• Quick Validation (first error)
• Instance cleaning
• Manual reference additions
• Validate by reference
• Missing reference resolution
• Custom format validation
• Custom attribute validation
• Plugins
• JSON-Schema draft 03 and 04 feature support
  • Ignored schema attributes
    • $schema
    • title
    • description
    • default
  • References
    • id
    • definitions
    • $ref
  • Validations by type
    • any
      • type
      • enum
      • extends
      • allOf
      • anyOf
      • oneOf
      • not
      • disallow
      • required
      • format
    • array
      • items
      • additionalItems
      • minItems
      • maxItems
      • uniqueItems
    • boolean
    • null
    • number, integer
      • multipleOf
      • divisibleBy
      • minimum
      • maximum
      • exclusiveMinimum
      • exclusiveMaximum
    • object
      • properties
      • patternProperties
      • additionalProperties
      • required
      • dependencies
      • minProperties
      • maxProperties
      • dependencies
    • string
      • minLength
      • maxLength
      • pattern
      • format
        • date-time
        • date
        • time
        • utc-millisec
        • email
        • hostname
        • host-name
        • ip-address
        • ipv4
        • ipv6
        • uri
        • regex
        • color
        • style
        • phone