⚠️ Unsaved

[M]:

Joi Cheatsheet: Quick Reference to Validation Rules

This notebook provides a comprehensive cheatsheet for Joi, the powerful schema validation library for JavaScript. Whether you're validating API requests, form inputs, or configuration objects, this quick reference guide will help you implement robust data validation in your Node.js applications.

[1]:

$ npm install joi

added 6 packages in 2s

28 packages are looking for funding
  run `npm fund` for details

[2]:

Joi version: 17.13.3

[M]:

1. String Validation Rules

Common validation rules for strings.

[3]:

Basic string validation:
{ value: 'hello' } 
{
  value: 123,
  error: [Error [ValidationError]: "value" must be a string] {
    _original: 123,
    details: [ [Object] ]
  }
}

[4]:

String length validation:
{ value: 'hello' } 
{
  value: 'hi',
  error: [Error [ValidationError]: "value" length must be at least 3 characters long] {
    _original: 'hi',
    details: [ [Object] ]
  }
}

[5]:

String pattern validation:
{ value: 'abc123' } 
{
  value: 'abc-123',
  error: [Error [ValidationError]: "value" with value "abc-123" fails to match the required pattern: /^[a-zA-Z0-9]{3,30}$/] {
    _original: 'abc-123',
    details: [ [Object] ]
  }
}

[6]:

Email validation:
{ value: 'user@example.com' } 
{
  value: 'invalid-email',
  error: [Error [ValidationError]: "value" must be a valid email] {
    _original: 'invalid-email',
    details: [ [Object] ]
  }
}

[7]:

String case transformation:
{ value: 'hello' }

[M]:

2. Number Validation Rules

Common validation rules for numbers.

[8]:

Basic number validation:
{ value: 42 } 
{ value: 3.14 } 
{ value: 42 } 
{
  value: 'abc',
  error: [Error [ValidationError]: "value" must be a number] {
    _original: 'abc',
    details: [ [Object] ]
  }
}

[9]:

Number range validation:
{ value: 50 } 
{
  value: 0,
  error: [Error [ValidationError]: "value" must be greater than 0] {
    _original: 0,
    details: [ [Object] ]
  }
} 
{
  value: 100,
  error: [Error [ValidationError]: "value" must be less than 100] {
    _original: 100,
    details: [ [Object] ]
  }
}

[10]:

Integer validation:
{ value: 42 } 
{
  value: 3.14,
  error: [Error [ValidationError]: "value" must be an integer] {
    _original: 3.14,
    details: [ [Object] ]
  }
}

[11]:

Precision validation:
{ value: 3.14 } 
{ value: 3.14 } 
Sign validation:
{ value: 42 } 
{
  value: -42,
  error: [Error [ValidationError]: "value" must be a positive number] {
    _original: -42,
    details: [ [Object] ]
  }
}

[M]:

3. Boolean Validation Rules

Common validation rules for booleans.

[12]:

Basic boolean validation:
{ value: true } 
{ value: false } 
{ value: true } 
{
  value: 'yes',
  error: [Error [ValidationError]: "value" must be a boolean] {
    _original: 'yes',
    details: [ [Object] ]
  }
} 
{
  value: 1,
  error: [Error [ValidationError]: "value" must be a boolean] {
    _original: 1,
    details: [ [Object] ]
  }
} 
{
  value: 'abc',
  error: [Error [ValidationError]: "value" must be a boolean] {
    _original: 'abc',
    details: [ [Object] ]
  }
}

[13]:

Strict boolean validation:
{ value: true } 
{
  value: 'true',
  error: [Error [ValidationError]: "value" must be a boolean] {
    _original: 'true',
    details: [ [Object] ]
  }
}

[14]:

Specific boolean validation:
{ value: true } 
{
  value: false,
  error: [Error [ValidationError]: "value" must be [true]] {
    _original: false,
    details: [ [Object] ]
  }
}

[M]:

4. Date Validation Rules

Common validation rules for dates.

[15]:

Basic date validation:
{ value: 2025-03-12T19:24:13.464Z } 
{ value: 2023-01-01T00:00:00.000Z } 
{ value: 2023-01-01T00:00:00.000Z } 
{
  value: 'not a date',
  error: [Error [ValidationError]: "value" must be a valid date] {
    _original: 'not a date',
    details: [ [Object] ]
  }
}

[16]:

Date range validation:
{ value: 2025-03-12T19:24:15.901Z } 
{
  value: 2000-01-01T00:00:00.000Z,
  error: [Error [ValidationError]: "value" must be greater than or equal to "2025-03-11T19:24:15.901Z"] {
    _original: 2000-01-01T00:00:00.000Z,
    details: [ [Object] ]
  }
}

[17]:

Relative date validation:
{ value: 2025-03-13T19:24:15.901Z } 
{
  value: 2025-03-11T19:24:15.901Z,
  error: [Error [ValidationError]: "value" must be greater than "now"] {
    _original: 2025-03-11T19:24:15.901Z,
    details: [ [Object] ]
  }
}

[18]:

ISO date validation:
{ value: 2023-01-01T00:00:00.000Z } 
{
  value: '01/01/2023',
  error: [Error [ValidationError]: "value" must be in ISO 8601 date format] {
    _original: '01/01/2023',
    details: [ [Object] ]
  }
}

[M]:

5. Array Validation Rules

Common validation rules for arrays.

[19]:

Basic array validation:
{ value: [ 1, 2, 3 ] } 
{
  value: undefined,
  error: [Error [ValidationError]: "value" must be an array] {
    _original: 'not an array',
    details: [ [Object] ]
  }
}

[20]:

Array items validation:
{ value: [ 'a', 'b', 'c' ] } 
{
  value: [ 'a', 1, 'c' ],
  error: [Error [ValidationError]: "[1]" must be a string] {
    _original: [ 'a', 1, 'c' ],
    details: [ [Object] ]
  }
} 
{ value: [ 'a', 1, 'c' ] }

[21]:

Array length validation:
{ value: [ 1, 2, 3 ] } 
{
  value: [ 1, 2 ],
  error: [Error [ValidationError]: "value" must contain 3 items] {
    _original: [ 1, 2 ],
    details: [ [Object] ]
  }
}

[22]:

Unique array validation:
{ value: [ 'a', 'b', 'c' ] } 
{
  value: [ 'a', 'b', 'a' ],
  error: [Error [ValidationError]: "[2]" contains a duplicate value] {
    _original: [ 'a', 'b', 'a' ],
    details: [ [Object] ]
  }
}

[23]:

Ordered array validation:
{ value: [ 'a', 1, true ] } 
{
  value: [ 1, 'a', true ],
  error: [Error [ValidationError]: "[0]" must be a string] {
    _original: [ 1, 'a', true ],
    details: [ [Object] ]
  }
}

[M]:

6. Object Validation Rules

Common validation rules for objects.

[24]:

Basic object validation:
{ value: { key: 'value' } } 
{
  value: 'not an object',
  error: [Error [ValidationError]: "value" must be of type object] {
    _original: 'not an object',
    details: [ [Object] ]
  }
}

[25]:

Object with keys validation:
{
  value: {
    username: 'johndoe',
    email: 'john@example.com',
    age: 25,
    created: 1741807477463
  }
}

[26]:

Unknown keys handling:
Strict schema: {
  value: { name: 'John', age: 30, extra: 'field' },
  error: [Error [ValidationError]: "extra" is not allowed] {
    _original: { name: 'John', age: 30, extra: 'field' },
    details: [ [Object] ]
  }
} 
Flexible schema: { value: { name: 'John', age: 30, extra: 'field' } }

[27]:

Required and optional keys:
{
  value: {
    street: '123 Main St',
    city: 'Anytown',
    state: 'CA',
    zip: '12345',
    country: 'USA'
  }
}

[28]:

Nested objects validation:
{
  value: {
    user: { name: 'John Doe', email: 'john@example.com' },
    preferences: { theme: 'dark', notifications: true }
  }
}

[M]:

7. Logical Operators

Combining schemas with logical operators.

[29]:

Alternatives (OR) validation:
{ value: 'user@example.com' } 
{
  value: undefined,
  error: [Error [ValidationError]: "value" does not match any of the allowed types] {
    _original: '123e4567-e89b-12d3-a456-426614174000',
    details: [ [Object] ]
  }
} 
{ value: 'AB123456' } 
{
  value: undefined,
  error: [Error [ValidationError]: "value" does not match any of the allowed types] {
    _original: 'invalid',
    details: [ [Object] ]
  }
}

[30]:

Conditional validation:
{ value: { paymentMethod: 'credit', cardNumber: '1234567890123456' } } 
{ value: { paymentMethod: 'paypal', paypalEmail: 'user@example.com' } } 
{
  value: { paymentMethod: 'credit', paypalEmail: 'user@example.com' },
  error: [Error [ValidationError]: "cardNumber" is required] {
    _original: { paymentMethod: 'credit', paypalEmail: 'user@example.com' },
    details: [ [Object] ]
  }
}

[31]:

Logical AND validation:
{ value: 'Password123!' } 
{
  value: 'password123',
  error: [Error [ValidationError]: "value" with value "password123" fails to match the required pattern: /[A-Z]/] {
    _original: 'password123',
    details: [ [Object] ]
  }
} 
{
  value: 'Password',
  error: [Error [ValidationError]: "value" with value "Password" fails to match the required pattern: /\d/] {
    _original: 'Password',
    details: [ [Object] ]
  }
}

[32]:

Logical OR for keys:
{ value: { name: 'John', email: 'john@example.com' } } 
{ value: { name: 'John', phone: '1234567890' } } 
{
  value: { name: 'John' },
  error: [Error [ValidationError]: "value" must contain at least one of [email, phone]] {
    _original: { name: 'John' },
    details: [ [Object] ]
  }
}

[33]:

Logical XOR validation:
{ value: { pickupLocation: 'Store #123' } } 
{ value: { deliveryAddress: '123 Main St' } } 
{
  value: { pickupLocation: 'Store #123', deliveryAddress: '123 Main St' },
  error: [Error [ValidationError]: "value" contains a conflict between exclusive peers [pickupLocation, deliveryAddress]] {
    _original: { pickupLocation: 'Store #123', deliveryAddress: '123 Main St' },
    details: [ [Object] ]
  }
} 
{
  value: {},
  error: [Error [ValidationError]: "value" must contain at least one of [pickupLocation, deliveryAddress]] {
    _original: {},
    details: [ [Object] ]
  }
}

[M]:

8. Validation Options

Common options for customizing validation behavior.

[34]:

[35]:

Default validation (strict):
{
  value: {
    username: 'johndoe',
    email: 'john@example.com',
    age: 25,
    extra: 'field',
    newsletter: false
  },
  error: [Error [ValidationError]: "extra" is not allowed] {
    _original: {
      username: 'johndoe',
      email: 'john@example.com',
      age: '25',
      extra: 'field'
    },
    details: [ [Object] ]
  }
}

[36]:

Validation with type conversion:
{
  value: {
    username: 'johndoe',
    email: 'john@example.com',
    age: 25,
    extra: 'field',
    newsletter: false
  },
  error: [Error [ValidationError]: "extra" is not allowed] {
    _original: {
      username: 'johndoe',
      email: 'john@example.com',
      age: '25',
      extra: 'field'
    },
    details: [ [Object] ]
  }
}

[37]:

Validation allowing unknown keys:
{
  value: {
    username: 'johndoe',
    email: 'john@example.com',
    age: 25,
    extra: 'field',
    newsletter: false
  }
}

[38]:

Validation stripping unknown keys:
{
  value: {
    username: 'johndoe',
    email: 'john@example.com',
    age: 25,
    newsletter: false
  }
}

[39]:

Validation with abort early (default):
{
  value: { username: 'j', email: 'not-an-email', age: 16 },
  error: [Error [ValidationError]: "username" length must be at least 3 characters long] {
    _original: { username: 'j', email: 'not-an-email', age: 16 },
    details: [ [Object] ]
  }
} 
Validation with all errors:
{
  value: { username: 'j', email: 'not-an-email', age: 16, newsletter: false },
  error: [Error [ValidationError]: "username" length must be at least 3 characters long. "email" must be a valid email. "age" must be greater than or equal to 18] {
    _original: { username: 'j', email: 'not-an-email', age: 16 },
    details: [ [Object], [Object], [Object] ]
  }
}

[M]:

9. Custom Error Messages

Customizing validation error messages.

[40]:

[41]:

Custom error messages:
Validation errors:
- Username must be at least 3 characters
- Please enter a valid email address
- Password must include lowercase, uppercase, and numbers
- Password must include lowercase, uppercase, and numbers

[42]:

Global custom messages:
{
  value: { name: 'a', email: 'not-email' },
  error: [Error [ValidationError]: The field 'name' must be at least 3 characters] {
    _original: { name: 'a', email: 'not-email' },
    details: [ [Object] ]
  }
}

[M]:

10. Practical Examples

Common real-world validation scenarios.

[43]:

API request validation:
{
  value: {
    body: {
      name: 'John Doe',
      email: 'john@example.com',
      role: 'user',
      settings: {}
    },
    query: { sendWelcomeEmail: false },
    headers: {
      'content-type': 'application/json',
      authorization: 'Bearer token123',
      'user-agent': 'Mozilla/5.0'
    }
  }
}

[44]:

Form validation:
{
  value: {
    firstName: 'John',
    lastName: 'Doe',
    email: 'john@example.com',
    subject: 'Question about your services',
    message: 'I would like to know more about your web development services. Please contact me at your earliest convenience.',
    subscribe: true
  }
}

[45]:

Configuration validation:
{
  value: {
    app: {
      name: 'MyApp',
      port: 8080,
      environment: 'production',
      debug: false
    },
    database: {
      host: 'db.example.com',
      username: 'dbuser',
      password: 'dbpass',
      name: 'myapp_db',
      port: 5432,
      pool: [Object]
    },
    logging: { level: 'info' }
  }
}

[M]:

Summary

This cheatsheet has covered the most common Joi validation rules and techniques:

String Validation: Length, patterns, formats, and transformations
Number Validation: Ranges, integers, precision, and sign
Boolean Validation: Truthy/falsy values and conversions
Date Validation: Ranges, formats, and relative dates
Array Validation: Length, item types, and uniqueness
Object Validation: Required/optional keys, defaults, and nesting
Logical Operators: Alternatives, conditionals, and key requirements
Validation Options: Type conversion, unknown keys, and error handling
Custom Error Messages: Improving user experience with clear messages
Practical Examples: Real-world validation scenarios

Joi provides a powerful, flexible system for data validation in JavaScript applications. By leveraging these validation rules, you can ensure data integrity, improve error handling, and create more robust applications.

For more information, check out the Joi documentation.