# Joi

> Builds and validates Joi schemas, including custom types, conditional validation with .when(), cross-field references, and custom error messages.

- Skill: `diegosouzapw/joi` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add diegosouzapw/joi`
- Raw SKILL.md: https://api.skillmd.com/api/skills/diegosouzapw/joi/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools, API Design
- Tags: Hapi, Input Validation, Joi, Nodejs, Schema Validation
- Author: diegosouzapw (https://skillmd.com/u/diegosouzapw)
- Updated: 2026-08-22
- Page: https://skillmd.com/skills/diegosouzapw/joi

---


# Joi


## Quick Start

    const Joi = require('@hapi/joi');

    const schema = Joi.object({
        name: Joi.string().min(1).max(100).required(),
        age: Joi.number().integer().min(0),
        email: Joi.string().email()
    });

    const { error, value } = schema.validate(input);


## Critical Rules

1. **Schemas are immutable** - Every method returns a new schema instance; never mutate
2. **Validate at boundaries** - Use `validate()` or `attempt()` at input boundaries; see [validation](reference/validation.md)
3. **Types extend base** - All types inherit from `any()`; see [types overview](reference/types.md)
4. **Refs for cross-field** - Use `Joi.ref()` for dynamic values across fields; see [references](reference/references.md)
5. **Extend for custom types** - Use `Joi.extend()` to create custom types; see [extensions](reference/extensions.md)


## Workflow

1. **Choose a type** - [types overview](reference/types.md) for all built-in types
2. **Add constraints** - Chain rules like `.min()`, `.max()`, `.pattern()`, `.valid()`
3. **Compose schemas** - Nest `Joi.object()`, `Joi.array()`, `Joi.alternatives()`
4. **Add conditionals** - Use `.when()` for dynamic schemas; see [conditionals](reference/conditionals.md)
5. **Customize errors** - Override messages via `.messages()` or `.error()`; see [errors](reference/errors.md)


## Key Patterns

| Topic                    | Reference                                              |
| ------------------------ | ------------------------------------------------------ |
| All built-in types       | [types](reference/types.md)                            |
| Validation & options     | [validation](reference/validation.md)                  |
| References & templates   | [references](reference/references.md)                  |
| Conditional schemas      | [conditionals](reference/conditionals.md)              |
| Error handling           | [errors](reference/errors.md)                          |
| Custom extensions        | [extensions](reference/extensions.md)                  |
| Metadata & introspection | [metadata](reference/metadata.md)                      |
| Common methods (any)     | [any](reference/any.md)                                |
| Testing patterns         | [testing](reference/testing.md)                        |