Koa middleware that validates request against swagger documentation.

$ npm install fleek-validator

Quick reference:

• Best used in tandem with the fleek-router
• Validations are based on the swagger parameter specifications, but many additional validations have been added that are not supported by swagger directly
• A request may pass erroneously pass validation if the route is not recognized or the configuration is not correct. if no validation is run this.validated will be false
• The validate object/helper will be added to the request context and can be accessed during request handling. eg: this.validate.one(foo, {/* parameter decription*/})
• if koa-router is not used, paths will be mapped to swager docs using the koa-router module. If another routing module is used in the stack, unexpected results may appear (you have been warned!)
• A full list of errors an codes can be found in error.json

• Usage
  • Basic
  • Fully Custom (paths)
  • Fully Custom (objects)
  • Koa on Fleek
• Response Structure
• Static Utilities
  • validator.validate
    • validate.one
    • validate.object
    • validate.ctx
    • validate.error
    • validate.isError
• Configuration
  • config.swagger
  • config.success
  • config.catch
  • config.strict
• Validations
  • Types
    • string
    • integer
    • long
    • float
    • double
    • byte
    • dateTime
    • date
    • boolean
  • Restrictions
    • multipleOf
    • maximum
    • exclusiveMaximum
    • minimum
    • exclusiveMinimum
    • maxlength
    • maxItems
    • minLength
    • minItems
    • pattern
    • maxProperties
    • minProperties
    • enum
    • email
    • alphaNumeric
    • lowercase
    • uppercase
    • format
    • past
    • future
  • Hygiene
    • trim
    • toUpperCase
    • toLowerCase
  • Miscellaneous
    • defaltsValue
    • required
• Reference Material
• Authors

• Swagger docs will be retrieved from ./api.json, /swagger.json, /config/api.json, or /config/swagger.json in that order
• Full example

let koa       = require('koa');
let validator = require('fleek-validator');
let parser    = require('koa-bodyparser');
let app       = koa();

app.use(parser());
app.use(validator());
app.use(function *() {
  this.body = { message : 'validation passed' };
});

app.listen(7000);

• Swagger docs are pulled from ./custom/docs.json
• error is run on validation failure
• success is run on validation pass (before next middlware)
• TODO Full example

var koa            = require('koa');
var router         = require('koa-router')();
var fleekValidator = require('fleek-validator');
var app = koa();

fleekValidator(app, {
  swagger : './custom/docs.json',
  strict  : true, // fail any route not in the swagger docs
  success : function *(next) {
    console.log('Passed validation!')
  },
  error  : function *(err, next) {
    console.log('Failed Validation :(');
    this.body = err;
  }
});

router.get('/', function *() {
  console.log('hello from root')
});

app.listen(3000);

• Swagger docs are parsed from the object provided
• error is run on validation failure
• success is run on validation pass (before next middlware)
• TODO Full example

var koa            = require('koa');
var router         = require('koa-router')();
var fleekValidator = require('fleek-validator');
var app = koa();

fleekValidator(app, {
  swagger      : require('./some/swagger/generator')(),
  strict  : true, // fail any route not in the swagger docs
  success : function *(next) {
    console.log('Passed validation!')
  },
  error  : function *(err, next) {
    console.log('Failed Validation :(');
    this.body = err;
  }
});

router.get('/', function *() {
  console.log('hello from root')
});

app.listen(3000);

• Controllers are pulled from the ./controllers directory
• Swagger docs will be retrieved from ./api.json, /swagger.json, /config/api.json, or /config/swagger.json in that order
• routes wil be generated by fleek-router
• TODO Full example

var koa         = require('koa');
var fleekRouter = require('fleek-router');
var app = koa();

fleekRouter(app, {
  authenicate : true,
  validate    : {
    error : function *(err, next) {
      console.log('oh no! Returning default errors');
    }
  }
});

app.listen(3000);

• The following structure will be followed in errors passed to the error handler specified
• If no error handler is specified, the error will be sent to the client with the status 400
• A full list of errors an codes can be found in error.json

{
  "error": "Validation Failed",
  "error_name": "VALIDATION_FAILED",
  "details": [{
    "name": "VALUE.FOO",
    "code": 204,
    "message": "Must be a valid foo string",
    "parameter": {
      "name": "some_val",
      "in": "body",
      "description": "fooget about it",
      "required": true,
      "type": "string",
      "foo": true
    }
  }]
}

• A collection of static utilities

var val    = require('fleek-validator').validate;
var errors = val.one(foo, {/* swagger parameter object foo must match */})

// OR - if using fleek-validor as middleware
function *(next) {
  var errors = this.validate.one(foo, {/* swagger parameter object foo must match */});
}

• validate a single object against a swagger parameter object

var error = validator.validate.one(fooEmail, {
  type  : 'string',
  email : true
})

• validate an object of values against an array of swagger parameter objects
• also accepts accepts definition property objects
  • eg:

      definitions : {
        UserModel : {
          parameters : {
            name : {
              type    : "string",
              required: true
            }
          }
        }
      }

• subject [String] - . delimited error property chain to identify which error.json error to generate
• parameters [Object] - swagger parameter description which failed
• options [object] (optional)
  • trim [Boolean] - if true, trim properties from the result that aren't in the the parameters array
  • defaults [Boolean] - if true, apply any defaultValue's from the parameters array
  • partial [Boolean] - if true, allow required parameters to pass through undefined (useful for partial updates)

• [Array] - array of validation errors
• [Object] - the object which passed validation, after options are applied

var parameters = [
  {
    name  : 'user_email',
    type  : 'string',
    email : true
  }, {
    name    : 'user_password',
    type    : 'string',
    pattern : passwordRegexp
  }, {
    name         : 'confirmed',
    defaultValue : false
  }
];

var subject = {
  user_email    : fooEmail,
  user_password : fooPwd,
  injection     : someMaliciousInjection
};

var result = validator.validate.object(subject, parameters, {
  trim     : true,
  defaults : true,
});
// result -> {
//   user_email    : fooEmail,
//   user_password : fooPwd,
//   confirmed     : false
// }

• validate a request context against a set of swagger params

var errors = validator.validate.ctx(ctx, [
  {
    name  : 'user_email',
    type  : 'string',
    email : true
  }, {
    name    : 'user_password',
    type    : 'string',
    pattern : passwordRegexp
  }
])

• An error class for validation errors [ValidationError]

• errorName [String] - . delimited error property chain to identify which error.json error to generate
• parameter [Object] - swagger parameter description which failed
• expected [String] (optional) - expected value for the parameter (replaces instances of ${expected} in the message)

var someError = new validator.validate.error('TYPE.STRING', someParameter, 'alphanumeric');

• detects whether or not the object is a validation error

• result [Mixed] - result object to test for validation failure

• isErr
• isValidationError
• isValidationErr
• isValError
• isValErr

var failedValidationResult = validator.validate.isError(resultOfValidation);

• sets the swagger documentation source for compiling routes.

• Object - javascript object mapping to the swagger doc format exactly
• String - path to the swagger json file (relative or absolute)
• Undefined - attempts to find the config in the following places ./api.json, ./swagger.json, ./config/api.json, and ./config/swagger.json

config.swagger = undefined; // attempts to resolve internally
// OR
config.swagger = './some/relative/swag.json';
// OR
config.swagger = '/some/absolute/swagger.json';
// OR
config.swagger = require('./a/function/returning/swag')();

• Success handler to run if validation succeeds (before the next middleware)
• The next middlewre funciton is provided

• Function - executed on validation success

config.succcess = function *(next) {
  console.log('woo! validation passed!');
  yield next();
}

• Error handler to run if validation fails
• The validation error and the next middleware function are provided
• If not provided, the default validation error structure is returned to the client

• Function - executed on validation failure

config.catch = function *(err, next) {
  console.log('oh no! Returning default errors');
}

• Determines whether or not to reject undocumented routes

• Boolean - if true, undocumented routes will fail validation

config.strict = true;

Validates params based on configuration. Can be used in either the parameters structure in a path or the properties structure of a definition

Paramer validation will occur during middleware execution

{
  "paths" : {
    "/foo" : {
      "post" : {
        "parameters" : [{
          "name"         : "someFormParam",
          "in"           : "body",
          "description"  : "An arbitrary date",
          "type"         : "date",
          "defaultValue" : "01/01/1990"
        }, {
          "name"         : "someQueryParam",
          "in"           : "query",
          "description"  : "An arbitrary required string",
          "required"     : true,
          "type"         : "string",
          "alphaNumeric" : true
        }]
      }
    }
  }
}

Definition validation must be called explicitly with a static function

{
  "definitions" : {
    "someDefinition" : {
      "properties": {
        "someFormParam" : {
          "description"  : "An arbitrary date",
          "type"         : "date",
          "defaultValue" : "01/01/1990"
        },
        "someQueryParam" : {
          "description"  : "An arbitrary required string",
          "type"         : "string",
          "required"     : true,
          "alphaNumeric" : true
        }
      }
    }
  }
}

Accept any String value

"parameters": [{
  "name" : "foo",
  "type" : "string",
  "in"   : "body"
}]

Accept any integer value

"parameters": [{
  "name" : "foo",
  "type" : "integer",
  "in"   : "body"
}]

Accept any long value

"parameters": [{
  "name" : "foo",
  "type" : "long",
  "in"   : "body"
}]

Accept any float value

"parameters": [{
  "name" : "foo",
  "type" : "float",
  "in"   : "body"
}]

Accept any double value

"parameters": [{
  "name" : "foo",
  "type" : "double",
  "in"   : "body"
}]

Accept any byte value

"parameters": [{
  "name" : "foo",
  "type" : "byte",
  "in"   : "body"
}]

Accept any dateTime value

"parameters": [{
  "name" : "foo",
  "type" : "dateTime",
  "in"   : "body"
}]

Accept any date value of form MM/DD/YY. see format for custom format. using "strict": true

"parameters": [{
  "name" : "foo",
  "type" : "date",
  "in"   : "body"
}]

Accept any boolean value

"parameters": [{
  "name" : "foo",
  "type" : "boolean",
  "in"   : "body"
}]

• Required Type: Number
• Description: Reject any number not a multiple of the config value
• Expects: Number to compare

"parameters": [{
  "name"       : "foo",
  "in"         : "body",
  "type"       : "integer",
  "multipleOf" : 10
}]

• Required Type: Number
• Description: Reject any number greater than the config value
• Expects: Number maximum

"parameters": [{
  "name"    : "foo",
  "type"    : "integer",
  "in"      : "body",
  "maximum" : 10
}]

• Required Type: Number
• Description: Reject any number greater than or equal to the config value
• Expects: Number maximum

"parameters": [{
  "name"             : "foo",
  "type"             : "integer",
  "in"               : "body",
  "exclusiveMaximum" : 10
}]

• Required Type: Number
• Description: Reject any number less than the config value
• Expects: Number minimum

"parameters": [{
  "name"    : "foo",
  "type"    : "integer",
  "in"      : "body",
  "minimum" : 10
}]

• Required Type: Number
• Description: Reject any number less than or equal to the config value
• Expects: Number maximum

"parameters": [{
  "name"             : "foo",
  "type"             : "integer",
  "in"               : "body",
  "exclusiveMinimum" : 10
}]

• Required Type: Array
• Description: Reject any array containing more than the number the config value
• Expects: Maximum number of properties allowed

"parameters": [{
  "name"      : "foo",
  "type"      : "array",
  "in"        : "body",
  "maxLength" : 10,
  "maxItems"  : 10
}]

• Required Type: Array
• Description: Reject any array containing fewer than the number the config value
• Expects: Minimum number of properties allowed

"parameters": [{
  "name"      : "foo",
  "type"      : "array",
  "in"        : "body",
  "minLength" : 10,
  "minItems"  : 10
}]

• Required Type: String
• Description: Reject any pattern not matching the config value
• Expects: RegExp string

"parameters": [{
  "name"    : "foo",
  "type"    : "string",
  "in"      : "body",
  "pattern" : "\\s*foo\\s*"
}]

• Required Type: Object
• Description: Reject any object with fewer than number specified
• Expects: Number maximum

"parameters": [{
  "name"          : "foo",
  "type"          : "object",
  "in"            : "body",
  "maxProperties" : 10
}]

• Required Type: Object
• Description: Reject any object with greater than number specified
• Expects: Number minimum

"parameters": [{
  "name"          : "foo",
  "type"          : "object",
  "in"            : "body",
  "minProperties" : 10
}]

• Required Type: Mixed
• Description: Reject any value not in the config array
• Expects: array

"parameters": [{
  "name" : "foo",
  "type" : "string",
  "in"   : "body",
  "enum" : ["accepted", "values"]
}]

• Required Type: String
• Description: Reject any invalid email address
• Expects: Boolean

"parameters": [{
  "name"  : "foo",
  "type"  : "string",
  "in"    : "body",
  "email" : true
}]

• Required Type: String
• Description: Reject any non alpha-numeric value
• Expects: Boolean

"parameters": [{
  "name"         : "foo",
  "type"         : "string",
  "in"           : "body",
  "alphaNumeric" : true
}]

• Required Type: String
• Description: Reject any value with uppercase values
• Expects: Boolean

"parameters": [{
  "name"      : "foo",
  "type"      : "string",
  "in"        : "body",
  "lowercase" : true
}]

• Required Type: String
• Description: Reject any value with lowercase values
• Expects: Boolean

"parameters": [{
  "name"      : "foo",
  "type"      : "string",
  "in"        : "body",
  "uppercase" : true
}]

• Required Type: Date
• Description: Reject any string not fitting the date format
• Expects: String following Moment formatting

"parameters": [{
  "name"   : "foo",
  "type"   : "date",
  "in"     : "body",
  "format" : "MM-DD-YYYY"
}]

• Required Type: Date
• Description: Reject any date that is not in the past
• Expects: Boolean

"parameters": [{
  "name" : "foo",
  "type" : "date",
  "in"   : "body",
  "past" : true
}]

• Required Type: Date
• Description: Reject any date not in the future
• Expects: boolean

"parameters": [{
  "name"   : "foo",
  "type"   : "date",
  "in"     : "body",
  "future" : true
}]

• Required Type: String
• Description: Trims leading and trailing whitespace
• Expects: Boolean

"parameters": [{
  "name" : "foo",
  "type" : "date",
  "in"   : "body",
  "trim" : true
}]

• Required Type: String
• Description: perform a toUpperCase operation on the parameter
• Expects: Boolean

"parameters": [{
  "name"        : "foo",
  "type"        : "date",
  "in"          : "body",
  "toUpperCase" : true
}]

• Required Type: String
• Description: perform a toLowerCase operation on the parameter
• Expects: Boolean

"parameters": [{
  "name"        : "foo",
  "type"        : "date",
  "in"          : "body",
  "toLowerCase" : true
}]

• Required Type: Mixed
• Description: Sets the parameter if none is provided
• Expects: Mixed

"parameters": [{
  "name"         : "foo",
  "type"         : "date",
  "in"           : "body",
  "defaultValue" : "Hello World."
}]

• Required Type: Mixed
• Description: Rejects any request not containing a value for the parameter. Performed before validation, but after defaults
• Expects: boolean

"parameters": [{
  "name"     : "foo",
  "type"     : "date",
  "in"       : "body",
  "required" : true
}]

• Home
• Editor Demo
• Documentation

• Hart Engineering

• John Hofrichter
• Peter A. Tariche
• Lan Nguyen

Built and maintained with by the Hart team.