sjv
An easy-to-write yet powerful schema validator for objects.
Features
- ES5-compatible, uses Promises
- Elegant, minimal syntax
- Comprehensive error reporting - all validation failures, not just first one
- Asynchronous custom validators
- Type-matching
- No other library dependencies (small browser footprint)
Installation
This package requires Node 4 or above
$ npm install sjv
To use in the browser ensure you must have a working Promise implementation
(e.g. bluebird) available at window.Promise
.
Usage
Here is a schema with all the possible field types:
var schema = name: String // shorthand for `{ type: String }` isMarried: Boolean numCars: type: Number born: type: Date // any plain JS object with any keys jobDetails: type: Object // a simple array with any data favouriteNumbers: type: Array // a nested object which adheres to given schema address: type: houseNum: type: Number // value which must be one of given strings taxBand: type: String enum: 'low' 'medium' 'high' // an array of nested objects which must adhere to given schema children: type: name: type: String // custom validators validate: { if 'john' === value return Promise; else return Promise; } age: type: Number
Example
First we define the schema:
var EmployeeSchema = name: type: String required: true born: type: Date numChildren: type: Number address: type: houseNum: type: Number street: type: String country: type: String required: true spouse: type: name: type: String required: true ; var CompanySchema = name: type: String required: true employees: type: EmployeeSchema required: true ;
Now we can validate data against it:
var schema = CompanySchema; schema;
Type matching
When stringifying JSON you often lose type information (e.g. Date
instances get converted to strings). When the stringified version gets parsed back into a JSON object you can use the typeify()
function to help restore type information:
var schema = name: type: String isMarried: type: Boolean numCars: type: Number born: type: Date ; var object = name: 'John' isMarried: true numCars: 3 born: 201501 var str = JSON; /*"{"name":"John","isMarried":true,"numCars":3,"born":"2014-12-31T16:00:00.000Z"}"*/ var newObject = JSON; /*{ name: 'John', isMarried: true, numCars: 3, born: "2014-12-31T16:00:00.000Z"}*/ var typedObject = schema; /*{ name: 'John', isMarried: true, numCars: 3, born: Date("2014-12-31T16:00:00.000Z")}*/
The type-ification process is quite tolerant of values. For example, for boolean values;
false
<-"false"
or"FALSE"
or"no"
or"NO"
or"0"
or0
true
<-"true"
or"TRUE"
or"yes"
or"YES"
or"1"
or1
To take the previous example again:
var newObject = name: 'John' isMarried: 'no' numCars: '76' born: '2014-12-31T16:00:00.000Z'; var typedObject = schema; /*{ name: 'John', isMarried: false, numCars: 76, born: Date("2014-12-31T16:00:00.000Z")}*/
It is also smart enough to know when a conversion isn't possible. Instead of throwing an error it will simply pass through the original value.
Using the schema from our previous example:
var newObject = name: null {} numCars: false born: 'blabla'; var typedObject = schema; /*{ name: null, isMarried: function() {} numCars: false born: 'blabla'}*/
You can limit type-ification to certain types only by setting the
limitTypes
option:
var newObject = name: 23 isMarried: '0' numCars: '3' born: '2018-01-01'; var typedObject = schema; /*{ name: '23', isMarried: '0', numCars: '3', born: '2018-01-01'}*/
Building
To run the tests:
$ npm install -g gulp
$ npm install
$ npm test
Contributing
Contributions are welcome! Please see CONTRIBUTING.md.
License
MIT - see LICENSE.md