skeemas

Lightweight JSON Schema valiation

Usage no npm install needed!

<script type="module">
  import skeemas from 'https://cdn.skypack.dev/skeemas';
</script>

README

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

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