Getting started

• Standalone
  • Creating Validators
  • Validating data
• Express usage

Standalone

var inspector = require('json-inspector');

Creating new Validator

• A validator object is defined by:

  var validator = inspector.define(name, schema, options)

  Argument	Type		Description
  name	String		validator's name
  schema	Object / Function		if it's function, the function is expected to return an object. See Schema Definition for more details
  options	Object	optional	same as Validator options

  if new validator object is created via inspector.define(), the validator is registered in internal cache so it's possible to reference one another in schema definitions.

  if you don't need this functionality, you can also initialize new validator object via:

  // the third argument is optional
  var validator = new inspector.Validator(schema, options, validatorManager);

Validating data

• On the validator object you can then repeatedly call the validator.validate method:

  validator.validate(data, customSchema, options); //=> returns self (validator)
  console.log(validator.success); //boolean
  console.log(validator.error); //=== inspector.ValidationError || inspector.ValidationMultiError

  Argument	Type		Description
  data	mixed		data value being inspected
  customSchema	Object	optional	custom schema definition which will be merged with schema definition of a validator object
  options	Object	optional	Same as Validator options

  if customSchema option object is provided, validator's schema is merged with provided custom schema only for that single validator.validate method call. (The original validator's schema defnition object is not mutated in second validate() call).

  Validation Errors

  In case of validator.success===false, validator.error will contain an error object which is either instance of ValidationError or ValidationMultiError.
  ValidationMultiError has errors property which is collection of validation error objects

---

Express usage

• Register json-inspector middleware in your express app:

      var validatorInjectorMiddleware = require('json-inspector').getExpressInjector;
  
  
      // this line should be immediately after express.bodyParser()
      app.use(validatorInjectorMiddleware({
          expressVersion: 5,
          //other options
      }));

  The validatorInjectorMiddleware takes following options:

  Option	Type	Default	Description
  expressVersion	Integer	4	express v5.x introduced breaking changes for req.query which is getter only from v5.x therefore filtering and sanitization of query data must be handled in specific way.
  required	Boolean	false	whether all properties should be treated as required or not by default
  message	String / Function	"Invalid data for %p ,got: %v"	Default error message for failed assertions. If it's function, it will be given special argument and the function will be expected to return message string. See Multilanguage Errors for more details
  failOnFirstErr	Boolean	false
  nullable	Boolean	false	if true, it will treat null values as empty value (by default only undefined values are treated that way)
  validationError	Function	ValidationError	Error constructor function
  customAssertions	Object		It's possible to extend available dictionary of keywords in schema definition by custom ones. Provide new schema keyword string as index and a function as value. See Defining custom keywords
  definitions	Object		Provide an object with validator name as index and validator schema definition as value. Later on you can call a registered validator by name by one of the methods available in req.validator mapping

  The InjectorMiddleware binds special validator object to the req object:

  • req.validator.define('validator name', schema) => Validator
    Registers and returns new validator object. It's possible to call the validator with validator middleware then
  • req.validator.validateData(validatorSchema, data, customSchema, options) => Validator
  • req.validator.validateQuery(validatorSchema, customSchema, options) => Validator
  • req.validator.validateBody(validatorSchema, customSchema, options) => Validator
  • req.validator.validateParams(validatorSchema, customSchema, options) => Validator

  Argument	Type		Description
  validatorSchema	String / Object / Function		can be name of registered validator or a schema definition. (Registered validator is every validator which was created by req.validator.define() or a validator from definitions option of expressValidatorInjectorMiddleware)
  customSchema	Object	optional	if provided, it's merged to original validator's schema (mutated schema applies only for current method call)
  options	Object	optional	Same as Validator options

• Take advantage of provided validator middleware in your routes

      var validatorMiddleware = require('json-inspector').getExpressMiddleware;
      
      
      router.post('/user',
              validatorMiddleware('user', 'body'),
              function(req, res, next) {
                  //Here, req.body contains validated & sanitized & filtered data according to your schema definition of the `user` validator.
                  //create an user in some way
                  var user = User.create(req.body).then(function(user) {
                      res.json(user);
                  });
              );

  validatorMiddleware has following form: validatorMiddleware(validatorSchema, dataIndex, customSchema, options) and takes following arguments:

  Argument	Type		Description
  validatorSchema	String / Object / Function		can be name of registered validator or a schema definition. (Registered validator is every validator which was created by req.validator.define() or a validator from definitions option of expressValidatorInjectorMiddleware)
  dataIndex	String		Should be one of: (query,body,params) values. Data for validation are then searched in req[dataIndex]
  customSchema	Object	optional	if provided, it's merged to original validator's schema (mutated schema applies only for current middleware call)
  options	Object	optional	Same as Validator options