joi

Joi is the flagship schema validation library from the hapi.js ecosystem, letting developers describe the exact shape, types, and constraints of JavaScript objects through a fluent, chainable API and then validate real data against that description. It has been a cornerstone of Node.js input validation since 2012, predating and inspiring much of the modern schema-validation landscape (Yup, Zod, and others openly cite Joi as an influence).

Beyond simple type-checking, Joi supports rich composition: conditional schemas, cross-field references, custom extensions, async validation, and detailed, localizable error messages. It ships first-class TypeScript types and a browser build, and remains under active maintenance by the hapi.js core team with a steady release cadence.

What You Get

• A fluent, chainable schema-building API (Joi.object({...}), Joi.string(), Joi.number(), etc.) covering primitives, arrays, objects, dates, and binary data
• Conditional validation (.when()), cross-field references (Joi.ref()), and custom extensions for domain-specific rules
• Both synchronous .validate() and asynchronous .validateAsync() entry points, plus attempt() for throw-on-failure workflows
• First-class TypeScript typings and a dedicated browser bundle (dist/joi-browser.min.js)
• Detailed, customizable/localizable error messages with per-rule error codes

Common Use Cases

• Validating REST/GraphQL API request bodies and query parameters at the edge of a Node.js service
• Enforcing configuration file and environment variable shapes at application startup
• Building reusable validation schemas shared between hapi.js route definitions and other frameworks
• Sanitizing and coercing untrusted user input before it reaches business logic or a database layer

Under The Hood

Architecture - Joi’s core lives in lib/base.js, lib/validator.js, and lib/compile.js, which together implement an internal schema-object model (Any, extended by type-specific classes under lib/types/) that gets compiled into a validation plan and walked against input data. lib/ref.js and lib/template.js implement cross-field references and string interpolation for dynamic rules, while lib/errors.js centralizes structured error generation with per-rule codes, and lib/extend.js provides the public extension API for adding custom types.

Tech Stack - Written in vanilla JavaScript (97.5%) with a thin TypeScript typings layer (lib/index.d.ts), targeting Node.js >= 20. Runtime dependencies are all first-party @hapi/* utility packages (hoek, topo, formula, address, tlds, pinpoint) plus the @standard-schema/spec interop spec, keeping the dependency tree entirely within the hapi.js ecosystem’s own maintained packages.

Code Quality - The test/ directory mirrors lib/ file-for-file with deep coverage (thousands of assertions across base.js, validator.js, each type module), run via @hapi/lab. The project uses @hapi/eslint-plugin for consistent style enforcement and maintains a legacy-compatibility test (@hapi/joi-legacy-test) to catch breaking changes against older major versions — a strong signal of deliberate API stability discipline.

API Design - The chainable builder pattern (Joi.object({name: Joi.string().required()})) reads close to natural language and is widely imitated by later validators. The 4500+ line API.md reference and dedicated joi.dev documentation portal make the large surface area (dozens of type-specific methods) navigable, though the sheer breadth of rules and options does introduce a real learning curve for newcomers wanting more than basic type validation.