Express JSON Validator Middleware

Express middleware for validating requests against JSON schemas with Ajv.

Why validate with JSON schemas?

• Expressive: JSON Schema is a portable way to describe data structures.
• Separate validation: Route handlers can focus on business logic.
• Rich errors: Ajv provides detailed error objects you can return or transform.
• Flexible: You can validate body, params, query, or custom request properties.

Requirements

• Node.js 24 or newer. Node 24 is the latest LTS line as of March 28, 2026.
• Express 4.21.2+ or 5.2.1+.

Installation

Install with npm:

npm install express express-json-validator-middleware

Install with Bun:

bun add express express-json-validator-middleware

Upgrading from v3? Read the v3 to v4 upgrade guide.

Getting started

import express from "express";
import { Validator } from "express-json-validator-middleware";

const app = express();

app.use(express.json());

const addressSchema = {
	type: "object",
	required: ["street"],
	properties: {
		street: {
			type: "string"
		}
	}
};

const { validate } = new Validator({ allErrors: true });

app.post("/address", validate({ body: addressSchema }), (request, response) => {
	response.json({ street: request.body.street });
});

Coming from express-jsonschema? Read the migration notes.

Schemas in TypeScript

When authoring schemas in TypeScript, combine this package's AllowedSchema type with Ajv's JSONSchemaType helper:

import type { JSONSchemaType } from "ajv";
import { type AllowedSchema } from "express-json-validator-middleware";

type Address = {
	street: string;
};

const addressSchema: AllowedSchema & JSONSchemaType<Address> = {
	type: "object",
	required: ["street"],
	properties: {
		street: {
			type: "string"
		}
	}
};

Error handling

Validation failures are forwarded to Express with a ValidationError:

import express from "express";
import { ValidationError } from "express-json-validator-middleware";

const app = express();

app.use((error, request, response, next) => {
	if (error instanceof ValidationError) {
		response.status(400).json({
			name: error.name,
			validationErrors: error.validationErrors
		});
		return;
	}

	next(error);
});

Example error payload:

{
	name: "JsonSchemaValidationError",
	validationErrors: {
		body: [
			{
				instancePath: "/name",
				keyword: "type"
			}
		]
	}
}

Validating multiple request properties

const tokenSchema = {
	type: "object",
	required: ["token"],
	properties: {
		token: {
			type: "string",
			minLength: 36,
			maxLength: 36
		}
	}
};

const paramsSchema = {
	type: "object",
	required: ["uuid"],
	properties: {
		uuid: {
			type: "string",
			minLength: 36,
			maxLength: 36
		}
	}
};

app.post(
	"/address/:uuid",
	validate({
		body: addressSchema,
		params: paramsSchema,
		query: tokenSchema
	}),
	(request, response) => {
		response.send({});
	}
);

Using dynamic schemas

Instead of passing a schema object, you can pass a function that derives a schema from the current request:

function getSchema(request) {
	if (request.query.requireAge === "1") {
		return {
			type: "object",
			required: ["name", "age"],
			properties: {
				name: { type: "string" },
				age: { type: "number" }
			}
		};
	}

	return {
		type: "object",
		required: ["name"],
		properties: {
			name: { type: "string" }
		}
	};
}

app.post("/user", validate({ body: getSchema }), (request, response) => {
	response.json({ success: true });
});

Ajv instance

The underlying Ajv instance is available as validator.ajv and should be configured before you create middleware with validate():

import { Validator } from "express-json-validator-middleware";

const validator = new Validator({ allErrors: true });

validator.ajv;

If you use schema formats, remember to install and register ajv-formats.

Development

This repository now uses Bun for dependency management:

bun install

Run the full verification suite with either package manager:

bun run verify
npm run verify

npm run verify and bun run verify cover:

• Node runtime tests
• type-checking against the published API
• coverage generation
• packaging the library with npm pack
• installing the packed tarball into /tmp/sample-express-app/npm
• installing the packed tarball into /tmp/sample-express-app/bun

Tests

npm test
npm run test:types
npm run test:install:npm
npm run test:install:bun

More documentation on JSON Schema

• Understanding JSON Schema

Credits

• Maintained by @simonplend
• Created and previously maintained by @vacekj
• Thank you to all of this project's contributors
• Based on the express-json-schema library by @trainiac