express-openapi-validator, request and response checks driven by your own OpenAPI file

The spec becomes a runtime contract, not a document

The premise of this library is narrow and useful. You already have an OpenAPI 3 specification, and you want the running server to check traffic against it instead of leaving the document as decoration. The project describes itself as an unopinionated library that integrates with new and existing API applications, and it stresses that it lets you write code the way you want without imposing a coding convention or project layout. You install the validator onto an Express app, point it at your `openapi.yaml`, and then define and implement routes the way you prefer. The middleware handles request validation and response validation, where response validation is json only, and it also handles security validation through custom security functions. That last item is the one most teams underrate: the same document that describes a bearer token can also carry the code that checks one.

Three middleware lines and one error handler

The documented setup is short. You install the package, import it, mount the middleware, and register an error handler. The middleware takes an options object where `apiSpec` is the path to the specification file, `validateRequests` is true by default, and `validateResponses` is false by default. That default matters more than it looks: response validation is opt-in, and once enabled it will reject payloads that your handlers produce, which is exactly the point for teams that have drifted from their spec. The error handler is where the design choice of the library shows. It reads `err.status` and `err.errors` and formats them into a JSON body, so validation problems arrive at the client as structured data rather than an Express default HTML page. The library is deliberately quiet about the shape of your routes, which is the main difference between it and code generators.

app.use(
  OpenApiValidator.middleware({
    apiSpec: './openapi.yaml',
    validateRequests: true, // (default)
    validateResponses: true, // false by default
  }),
);

The error handler that follows the routes is what turns a validation failure into a client-facing answer:

app.use((err, req, res, next) => {
  // format error
  res.status(err.status || 500).json({
    message: err.message,
    errors: err.errors,
  });
});

Body parsers have to come first, and this trips people up

The documentation flags one ordering requirement as important: Express must be configured with all relevant body parsers, and those parser middleware functions must be specified prior to any validated routes. The reason is structural rather than a quirk. The validator reads the request body to compare it against the schema, and a body that has not been parsed yet is an empty object, which will fail a schema that expects fields. Mount the parser, then the validator, then the routes, and a request that fails validation reaches the error handler as a structured 4xx rather than as a confusing mismatch deep inside a handler. The other ordering that matters is the error handler itself, which has to be registered after the routes that throw so that it catches them. The project keeps a set of example applications under `examples/`, running from a standard OAS 3.0 setup through OAS 3.1, multiple API specs, the operations API, Babel, a custom operation resolver, a multi-file spec, response date serialization, a top-level discriminator and a NestJS integration, which is the fastest way to see the correct ordering in practice.

What the validator can and cannot check

The feature list is specific about the boundaries. Request validation is on by default. Response validation covers json only, so a text or binary response is not inspected. Security validation is supported and can be extended with custom security functions. Third party and custom formats are supported, along with custom data serialization and deserialization, which is what lets a non-standard field type or an unusual date format pass through. File upload is supported, and there is optional auto-mapping of OpenAPI endpoints to Express handler functions for people who want the library to wire the routes, though it is optional. Reference support is there, so a spec split over multiple files works, and the `examples/6-multi-file-spec/` directory shows that case. The limits worth naming are the ones implied by the list: anything not expressed in the OpenAPI document is not checked, and anything expressed as a non-json response is not checked on the way out.

The same idea now ships for Koa, Fastify and NestJS

The library started as an Express-only package and has since spread, which changes the answer to the question of whether you should write your own validation layer. The README points at a NestJS example directory and states that Koa and Fastify versions are now available, pointing at their own package directories in a lerna-fastify tree. The Express package remains the canonical one and the one the install instructions cover. The version numbers attached to each capability are worth keeping in mind, because they define the minimum version you need. Express 5 support is available in v5.5.0 and later, and OpenAPI 3.1 support is available in v5.4.0 and later, so a project on OpenAPI 3.1 with Express 5 has to be on at least v5.5.0 to have both. The published releases are v5.6.2 on 2026-01-20, v5.6.0 on 2025-09-06 and v5.5.8 on 2025-07-27.

Package layout and the shape of the dependency set

The package metadata in the repository describes how the library is built and tested, and it is a TypeScript project with a compiled `dist` directory as its published surface. The scripts show a `compile` step driven by `tsc` after clearing the output, and a test command that runs mocha with ts-node over the spec files in `test/`. There are separate test scripts for Express 4 and for the latest Express, plus a `test:all` that runs both, which is the honest way to keep a library that claims support for two major Express versions honest. Coverage is produced with `nyc` and pushed to coveralls, and Codacy is configured for the same report. The dependency list is worth a glance because it explains the feature set: `ajv` with `ajv-draft-04` and `ajv-formats` for JSON Schema validation, `@apidevtools/json-schema-ref-parser` for resolving references across files, and `content-type` for content negotiation. The licence is MIT, with the text in `LICENSE`.

Where this approach stops working

The validator can only be as good as the document in front of it, and a stale OpenAPI file produces errors that look like server faults. This is the main operational risk, and it is not addressed by the library itself. A team that enables response validation without a habit of regenerating the spec from the code will spend time reading 500 errors that a stale schema caused. There is a second, subtler limit. Because the middleware is unopinionated about routes, it will not tell you that a handler is missing, and the optional auto-mapping exists precisely because plain middleware cannot enforce that a route exists. A third limit is coverage of formats: response validation is json only, and a service that returns a mix of json, plain text and streamed output is only partly checked. The documentation does not describe a mode for turning validation off per route for those cases, so a mixed-content service tends to need separate handling for the non-json parts.

Editorial conclusion

Adopt express-openapi-validator if your Express service already has an OpenAPI document that clients trust and you want the server to enforce it, and skip it if you have no spec or no interest in response checking, because a spec nobody maintains produces failures that look like application bugs. Verify three things first: that the body parsers are registered before the middleware, since the documentation calls this out as important and the failure mode is a request that never reaches your handler; that you decide whether `validateResponses` stays off, because it is false by default and turning it on will start rejecting your own responses; and which version line you install, since Express 5 support arrived in v5.5.0 and OpenAPI 3.1 support in v5.4.0, and the newest published release is v5.6.2.

Frequently asked questions

Official sources

1. cdimascio/express-openapi-validator on GitHub
2. Issues
3. License: MIT
4. README
5. Releases