chai-json-schema
Chai plugin with assertions to validate values against JSON Schema v4.
Assert both simple values and complex objects with the rich collection of validation terms (examples).
For general help with json-schema see this excellent guide and usable reference.
Notes
JSON Schema validation is done by Tiny Validator tv4.
The assertion will fail if a schema use a $ref
to a schema that is not added before the assertion is called. Use chai.tv4.addSchema(uri, schema)
to preset schemas.
JSON Schema's main use-case is validating JSON documents and API responses, but it is also a powerful way to describe and validate any JavaScript value or object.
Usage
server-side
Install from npm:
$ npm install chai-json-schema
Have chai use the chai-json-schema module:
var chai = ;chai;
browser-side
Using globals:
Include chai-json-schema after jsonpointer.js, Tiny Validator tv4 and Chai:
Install from bower:
$ bower install chai-json-schema
The module supports CommonJS, AMD and browser globals. You might need to shim tv4
's global and make sure jsonpointer.js
can be required as 'jsonpointer'
.
Assertions
jsonSchema(value, schema)
Validate that the given javascript value conforms to the specified JSON Schema. Both the value and schema would likely be JSON loaded from a external datasource but could also be literals or object instances.
var goodApple = skin: "thin" colors: "red" "green" "yellow" taste: 10;var badApple = colors: "brown" taste: 0 worms: 2;var fruitSchema = "title": "fresh fruit schema v1" "type": "object" "required": "skin" "colors" "taste" "properties": "colors": "type": "array" "minItems": 1 "uniqueItems": true "items": "type": "string" "skin": "type": "string" "taste": "type": "number" "minimum": 5 ; //bdd styletobe;tonotbe; goodAppleshouldbe;badAppleshouldnotbe; //tdd styleassert;assert;
Additional API
The tv4
instance is 'exported' as chai.tv4
and can be accessed to add schemas for use in validations:
chaitv4;
There are other useful methods:
var list = chaitv4;var list = chaitv4; var list = chaitv4;var list = chaitv4; var schema = chaitv4;var schema = chaitv4; chaitv4;
For more API methods and info on the validator see the tv4 documentation.
Non-standard tv4 properties
Cyclical objects
This will be passed to the internal tv4
validate call to enable support for cyclical objects. It allows tv4 to validate normal javascipt structures (instead of pure JSON) without risk of entering a loop on cyclical references.
chaitv4cyclicCheck = true;
This is slightly slower then regular validation so it is disabled by default.
Ban unknown properties
chaitv4banUnknown = true;
Passed to the internal tv4
validate call makes validation fail on unknown schema properties. Use this to make sure your schema do not contain undesirable data.
Remote references
Due to the synchronous nature of assertions there will be no support for dynamically loading remote references during validation.
Use the asynchronous preparation feature of your favourite test runner to preload remote schemas:
// simplified example using a bdd-style async before(); // as used in mocha, jasmine etc. ;
History
- 1.1.0 - Dependency update
- 1.0.10 - AMD loader support
- 1.0.9 - Published to bower.
- 1.0.7 - Updated tv4 dependency, improved error formatting.
- 1.0.5 - Dropped underscore dependency, various internal tweaks.
- 1.0.4 - Use and expose separated tv4 instance. Improved readme examples.
- 1.0.3 - Published to chaijs.com/plugins
- 1.0.2 - Improved reporting, made compatible with standard reporters.
Build
Install development dependencies in your git checkout:
$ npm install
You need the global grunt command:
$ npm install grunt-cli -g
Build and run tests:
$ grunt
See the Gruntfile
for additional commands.
License
Copyright (c) 2013 Bart van der Schoor
Licensed under the MIT license.