# express-validation > express-validation is a middleware that validates a request and returns a response with errors; if any of the configured validation rules fail. Latest version **4.1.1** (published 2024-06-18) · MIT license · 0 weekly downloads ## Install ```sh npm install express-validation pnpm add express-validation yarn add express-validation bun add express-validation ``` ## Health **Score 25/100 (F)** — status: abandoned. Positive: has types; no vulnerabilities; high quality score. Warnings: low downloads; no esm support. Negative: abandoned; low maintenance score. ## Facts | | | |---|---| | Version | 4.1.1 | | Published | 2024-06-18 | | First published | 2014-02-02 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | bundled | | Module format | CommonJS | | Dependencies | 3 | | Unpacked size | 17.8 KB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 392 | | Author | Andrew Keig | | Maintainers | papandreou, airasoul, colthreepv | | Keywords | express, validation, validate, joi, middleware | ## Links - npm: https://www.npmjs.com/package/express-validation - Repository: https://github.com/andrewkeig/express-validation - Issues: https://github.com/andrewkeig/express-validation/issues - npm.io page: https://npm.io/package/express-validation ## Dependencies (3) - [joi](https://npm.io/package/joi.md) ^17.6.0 - [@types/express](https://npm.io/package/@types/express.md) ^4.17.13 - [@types/hapi__joi](https://npm.io/package/@types/hapi__joi.md) 16.x.x ## Alternatives - [@regle/core](https://npm.io/package/@regle/core.md) — 47.0K weekly downloads - [typeof-arguments](https://npm.io/package/typeof-arguments.md) — 12.5K weekly downloads - [@lokalise/projects-engine-contracts](https://npm.io/package/@lokalise/projects-engine-contracts.md) — 978 weekly downloads - [@osjwnpm/nam-laboriosam-quibusdam](https://npm.io/package/@osjwnpm/nam-laboriosam-quibusdam.md) — 70 weekly downloads - [@oridune/validator](https://npm.io/package/@oridune/validator.md) — 16 weekly downloads ## Recent versions - 4.1.1 (latest) — 2024-06-18 - 4.1.0 — 2022-04-26 - 4.0.1 — 2022-04-14 - 4.0.0 — 2022-04-09 - 3.1.0 — 2022-04-08 - 3.0.8 — 2021-02-26 - 3.0.7 — 2021-02-19 - 3.0.6 — 2020-09-02 - 3.0.5 — 2020-05-19 - 3.0.4 — 2020-05-19 - 3.0.3 — 2020-05-18 - 3.0.2 — 2020-03-06 - 3.0.1 — 2020-03-06 - 3.0.0 — 2020-03-05 - 2.0.0 — 2020-02-28 - … 21 more at https://npm.io/package/express-validation/versions ## README express-validation ================== [![Build Status](https://travis-ci.org/AndrewKeig/express-validation.svg?branch=master)](https://travis-ci.org/AndrewKeig/express-validation) [![npm module](https://badge.fury.io/js/express-validation.svg)](https://www.npmjs.org/package/express-validation) [![Current Version](https://flat.badgen.net/npm/v/express-validation?icon=npm)](https://www.npmjs.org/package/express-validation) [![airbnb-style](https://flat.badgen.net/badge/eslint/airbnb/ff5a5f?icon=airbnb)](https://github.com/airbnb/javascript) [![Coverage Status](https://coveralls.io/repos/github/AndrewKeig/express-validation/badge.svg)](https://coveralls.io/github/AndrewKeig/express-validation) [![npm downloads](https://img.shields.io/npm/dm/express-validation.svg?style=flat)](https://www.npmjs.com/package/express-validation) [![Known Vulnerabilities](https://snyk.io/test/github/AndrewKeig/express-validation/badge.svg?targetFile=package.json)](https://snyk.io/test/github/AndrewKeig/express-validation?targetFile=package.json) `express-validation` is an express middleware that validates a request and returns a response with errors; if any of the configured validation rules fail. We use [joi](https://github.com/hapijs/joi/tree/master) to define validation rules. We have a hard dependency on Joi in order to avoid compatibility issues with Joi releases. We are using snyk, which should help with this process. Currently support Joi v17.x.x ## Parameter types We support validating the following parameter types: - headers - params (path) - query - cookies - signedCookies - body ## Install Install with npm: ```sh npm i express-validation --save ``` Install with yarn: ```sh yarn add express-validation ``` ## Example In order to setup and use `express-validation` consider the following simple express application. It has a single route; configured to use the `express-validation` middleware function `validate`; it accepts as input `loginValidation`; which defines validation rules for this route. ```js const express = require('express') const bodyParser = require('body-parser') const { validate, ValidationError, Joi } = require('express-validation') const loginValidation = { body: Joi.object({ email: Joi.string() .email() .required(), password: Joi.string() .regex(/[a-zA-Z0-9]{3,30}/) .required(), }), } const app = express(); app.use(bodyParser.json()) app.post('/login', validate(loginValidation, {}, {}), (req, res) => { res.json(200) }) app.use(function(err, req, res, next) { if (err instanceof ValidationError) { return res.status(err.statusCode).json(err) } return res.status(500).json(err) }) app.listen(3000) ``` We have defined two rules `email` and `password`. They are encapsulated inside `body`; which is important; as this defines their location within the request. We also need to setup an express global error handler, `express-validation` will pass errors to this handler. We can check within the handler for errors of type `validationError` distinguishing validation errors from other types of error. ## Errors `express-validation`, by `default` will return errors in the following format, an object `details` keyed by `parameter`, each containing an array of errors in `joi` format. ```json { "name": "ValidationError", "message": "Validation Failed", "statusCode": 400, "error": "Bad Request", "details": { "body": [ { "message": "\"password\" is not allowed to be empty", "path": [ "password" ], "type": "string.empty", "context": { "label": "password", "value": "", "key": "password" } } ] } } ``` We support other simpler formats via configuration - `keyByField`, flattens the error details object to a list of messages, keyed by field name ```json { "name": "ValidationError", "message": "Validation Failed", "statusCode": 400, "error": "Bad Request", "details": [ { "accesstoken": "\"accesstoken\" is not allowed to be empty" }, { "password": "\"password\" is not allowed to be empty" } ] } ``` ## API `express-validation` exposes the following api: ### `validate(schema, [options], [joiOptions]) => [validationError]` The exported `validate` function takes a `schema` object and two optional arguments, `options` and `joiOptions` and returns a `validationError` instance if schema contains errors. #### `schema` (Object) Default: `{}` Includes validition rules, defined using `joi`, the rules are keyed by the following `parameter` types: - headers - params (path) - query - cookies - signedCookies - body #### `options` (Object) Default: `{ context: false, statusCode: 400, keyByField: false }` Options, used by `express-validation`: - `context`, grants Joi access to the request object. This allows you to: - reference other parts of the request in your validations, see [Joi.ref](https://hapi.dev/family/joi/api/?v=17.1.0#refkey-options) - specify default values, see [Joi.default](https://hapi.dev/module/joi/api/#anydefaultvalue) - will also cast values, e.g. strings to integer - default { context: false } - `statusCode`, defaults to `400`, this will also set the error message via nodes [status codes](https://nodejs.org/api/http.html#http_http_status_codes) - default { statusCode: 400 } - `keyByField`, flattens the error details object to a list of messages, keyed by field name #### `joiOptions` (Object) Default: `{}` Options, used by `joi`, see [Joi options](https://hapi.dev/family/joi/api/?v=17.1.0#anyvalidateasyncvalue-options), note: ### `ValidationError` We expose a custom error; `ValidationError`, use this in you global express error handler to distinguish validation errors from other types of error. ### `Joi` We also expose the version of Joi we have as a dependency, in order to avoid compatibility issues with other versions of Joi. ## Examples For more information on how to use `express-validation` please see the following examples: #### abortEarly [`abortEarly.test.js`](/__tests__/integration/abortEarly.test.js) You can return multiple errors, not just the first encountered, by setting, the joi option `abortEarly: false` #### context [`context.test.js`](/__tests__/integration/context.test.js) Enabling the `context` in `options`, allows you to reference other parts of the request in your validation. #### defaults [`default.test.js`](/__tests__/integration/defaults.test.js) You can specify `joi` `default` values in your schema. ## License This work is licensed under the MIT License (see the LICENSE file). https://github.com/AndrewKeig/express-validation/blob/master/LICENSE --- _Source: https://npm.io/package/express-validation · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._