koa-request-schema

koa-request-schema implements request data validation using jsonschema. If data does not pass validation, the server returns a 400 Bad Request error. In non production environments, the response body is populated with the validation errors.

Usage

const schema = require('koa-request-schema');
 
router.post('/secret/:object',
    schema({
        params: {
            properties: {
                object: { type: 'string', required: true }
            }
        },
        query: {
            properties: {
                something: { type: 'string', required: false } }
            }
        },
        body: {
            properties: {
                password: { type: 'string', required: true, minLength: 10 }
            }
        }
    }),
    function *() {
        let body = this.request.body;
 
        if (body.password === 'the best password ever') {
            this.body = 'You got it boss';
        } else {
            this.throw(403, 'Pffttt...');
        }
    });

The error includes the following properties on schema validation error. The validationErrors property is the errors property returned by jsonschema on validation.

{
    "message": "Invalid request parameters",
    "details": {
        "validationErrors": [{
            "property": "request.body",
            "message": "Property password is required",
            "schema": { ... },
            "instance": ...
        }]
    }
}

Options

Options may be passed as the second argument to koa-request-schema; additionally require('koa-request-schema').create({ ... }) will return a function with options you pass it as defaults.

displayErrors [default=true in non-production environments]: Include validationErrors in the error.
coerceTypes [default=true]: Convert string values for date, integer, number, boolean, and object types to their respective type.
validator: Override the jsonschema Validator instance used.
strict [default=true]: Do not permit unknown properties in params, query, or body unless the schema defines its own additionalProperties value. (Default cannot be changed)

Koa 2 Support

To use koa-request-schema with koa@2, please use:

npm install --save koa-request-schema@next