Joi
By the Hapi/Joi open-source community
js, used to define the expected shape of an object and verify that incoming data conforms to it. Developers build a schema using Joi's chainable API, describing types, required fields, and constraints, then validate objects such as request…
Definition
Joi is a schema description and data validation library for JavaScript and Node.js, used to define the expected shape of an object and verify that incoming data conforms to it. Developers build a schema using Joi's chainable API, describing types, required fields, and constraints, then validate objects such as request payloads against it and receive detailed error messages when validation fails. It originated within the Hapi web framework ecosystem but is used independently across many Node.js projects.
Overview
Joi was created to solve the recurring problem of validating unstructured input, most commonly HTTP request bodies, query strings, and configuration objects, before it flows into application logic. Rather than scattering manual `if` checks throughout a codebase, Joi lets developers declare what valid data looks like once, as a schema object, and reuse that schema anywhere the same shape of data needs checking. Mechanically, a Joi schema is built by chaining methods that describe a value's type and constraints, such as `Joi.string().min(3).max(30).required()`, and schemas can be composed into objects describing entire request bodies with nested objects and arrays. Validation is performed by calling `.validate()` on a schema with the candidate data, which returns either the validated (and optionally coerced) value or a detailed error object describing exactly which fields failed and why, including support for collecting all errors at once rather than stopping at the first. Joi is one of several validation approaches available in the Node.js ecosystem alongside Ajv, which validates against the JSON Schema standard, and Zod, which is TypeScript-first and infers static types directly from schemas. Joi predates both in wide adoption and uses its own schema description language rather than JSON Schema, which gives it an expressive, readable API at the cost of not being directly interoperable with JSON Schema tooling such as OpenAPI generators without a conversion step. In practice, Joi is used heavily to validate request payloads in Hapi and Express applications, to validate environment variable configuration at startup so misconfiguration fails fast, and to check data shapes before writing to a database. Its readable, English-like chaining syntax makes schemas easy to review even for developers unfamiliar with the library. Joi's main trade-offs are its runtime-only nature, since it does not generate TypeScript types from schemas the way Zod does, and its comparatively larger size relative to leaner alternatives like Ajv, which compiles schemas to highly optimized validation functions. Teams working in a TypeScript-heavy codebase that want compile-time type safety derived from validation schemas often prefer Zod, while teams needing strict JSON Schema compliance for tooling interoperability often prefer Ajv, leaving Joi strongest where its expressive API and Hapi ecosystem ties matter most. Joi's long history also means its documentation and community answers cover an unusually wide range of edge cases, which can make it a pragmatic default even outside Hapi when a team simply wants a mature, well-documented validator with a large body of existing examples to draw on.
Key Features
- Chainable schema-building API for describing object shapes and constraints
- Detailed validation errors identifying which fields failed and why
- Support for nested objects, arrays, conditional rules, and custom validators
- Option to collect all validation errors instead of stopping at the first
- Originated in and integrates closely with the Hapi web framework
- Widely used independent of Hapi across general Node.js projects