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

Changelog