Mongoose Validation and Middleware

Advanced Validation Techniques

Mongoose provides a powerful validation framework that goes far beyond simple type checking. Let's explore advanced validation techniques to ensure your data meets complex business requirements.

Recap: Basic Schema Validation

const mongoose = require('mongoose');
const { Schema } = mongoose;

const productSchema = new Schema({
  name: {
    type: String,
    required: true,
    trim: true,
    minlength: 2,
    maxlength: 100
  },
  price: {
    type: Number,
    required: true,
    min: [0, 'Price cannot be negative'],
    max: 1000000
  },
  description: {
    type: String,
    trim: true,
    maxlength: 2000
  },
  category: {
    type: String,
    required: true,
    enum: {
      values: ['Electronics', 'Clothing', 'Books', 'Home', 'Sports'],
      message: '{VALUE} is not a supported category'
    }
  },
  inStock: {
    type: Boolean,
    default: true
  },
  createdAt: {
    type: Date,
    default: Date.now,
    immutable: true // Cannot be changed once set
  }
});
            

Custom Validators

Custom validators allow you to implement complex validation logic that can't be expressed with built-in validators.

const userSchema = new Schema({
  username: {
    type: String,
    required: true,
    validate: {
      validator: function(v) {
        // Username must be alphanumeric with optional underscores and hyphens
        return /^[a-zA-Z0-9_-]+$/.test(v);
      },
      message: props => `${props.value} is not a valid username. Use only letters, numbers, underscores, and hyphens.`
    }
  },
  email: {
    type: String,
    required: true,
    validate: {
      validator: function(v) {
        // Complex email validation regex
        return /^([\w-\.]+@([\w-]+\.)+[\w-]{2,4})?$/.test(v);
      },
      message: props => `${props.value} is not a valid email address.`
    }
  },
  password: {
    type: String,
    required: true,
    validate: {
      validator: function(v) {
        // Password must have at least 8 characters, one uppercase, one lowercase, and one number
        const passwordRegex = /^(?=.*[a-z])(?=.*[A-Z])(?=.*\d).{8,}$/;
        return passwordRegex.test(v);
      },
      message: 'Password must be at least 8 characters long and contain at least one uppercase letter, one lowercase letter, and one number.'
    }
  },
  age: {
    type: Number,
    min: 18,
    max: 120,
    validate: {
      validator: function(v) {
        // Additional custom logic: age must be a whole number
        return Number.isInteger(v);
      },
      message: 'Age must be a whole number.'
    }
  }
});
            

Asynchronous Validators

For validation that requires database lookups or API calls, Mongoose supports asynchronous validators.

const userSchema = new Schema({
  email: {
    type: String,
    required: true,
    validate: {
      validator: async function(email) {
        // Check if the email is already in use
        const existingUser = await mongoose.models.User.findOne({ email });
        return !existingUser; // Return false if user with this email exists
      },
      message: 'Email is already in use.'
    }
  },
  username: {
    type: String,
    required: true,
    validate: {
      validator: async function(username) {
        // Check if username is already taken
        const existingUser = await mongoose.models.User.findOne({ username });
        
        // Also check against a list of reserved usernames
        const reservedUsernames = ['admin', 'root', 'system', 'moderator'];
        
        return !existingUser && !reservedUsernames.includes(username.toLowerCase());
      },
      message: 'Username is already taken or reserved.'
    }
  },
  website: {
    type: String,
    validate: {
      validator: async function(url) {
        if (!url) return true; // Optional field
        
        try {
          // Check if the website is reachable
          // In a real application, you might use a proper HTTP client
          // This is a simplified example
          const response = await fetch(url, { method: 'HEAD' });
          return response.ok;
        } catch (error) {
          return false;
        }
      },
      message: 'Website is not reachable.'
    }
  }
});
            

Conditional Validation

In many real-world scenarios, validation of one field depends on the value of another field. Mongoose allows you to implement this conditional logic.

const orderSchema = new Schema({
  orderType: {
    type: String,
    enum: ['standard', 'express', 'international'],
    required: true
  },
  
  // Shipping address (required for all orders except digital)
  shippingAddress: {
    street: String,
    city: String,
    state: String,
    zipCode: String,
    country: {
      type: String,
      default: 'USA'
    }
  },
  
  // International shipping details (required only for international orders)
  internationalDetails: {
    customsDeclaration: String,
    taxId: String,
    importLicense: String
  },
  
  // Digital delivery details (for digital products)
  digitalDelivery: {
    email: String,
    downloadLink: String
  },
  
  isDigital: {
    type: Boolean,
    default: false
  }
});

// Conditional validation: Shipping address is required unless it's a digital-only order
orderSchema.path('shippingAddress.street').required(function() {
  return !this.isDigital;
}, 'Shipping address is required for physical orders');

orderSchema.path('shippingAddress.city').required(function() {
  return !this.isDigital;
}, 'Shipping city is required for physical orders');

// Conditional validation: International details required only for international orders
const internationalDetailsValidator = function() {
  return this.orderType === 'international';
};

orderSchema.path('internationalDetails.customsDeclaration').required(
  internationalDetailsValidator,
  'Customs declaration is required for international orders'
);

orderSchema.path('internationalDetails.taxId').required(
  internationalDetailsValidator,
  'Tax ID is required for international orders'
);

// Conditional validation: Digital delivery details required only for digital orders
orderSchema.path('digitalDelivery.email').required(function() {
  return this.isDigital;
}, 'Email is required for digital delivery');
            

Cross-Field Validation

Sometimes validation needs to compare multiple fields. You can implement cross-field validation using custom validators.

const accountSchema = new Schema({
  username: {
    type: String,
    required: true
  },
  password: {
    type: String,
    required: true
  },
  passwordConfirmation: {
    type: String,
    required: true,
    validate: {
      validator: function(value) {
        // Check if password and passwordConfirmation match
        return value === this.password;
      },
      message: 'Passwords do not match.'
    }
  },
  dateOfBirth: {
    type: Date,
    required: true
  },
  retirementDate: {
    type: Date,
    validate: {
      validator: function(value) {
        if (!value) return true; // Optional field
        
        // Retirement date must be after date of birth
        return value > this.dateOfBirth;
      },
      message: 'Retirement date must be after date of birth.'
    }
  },
  
  // Price range validation
  priceMin: {
    type: Number,
    min: 0
  },
  priceMax: {
    type: Number,
    min: 0,
    validate: {
      validator: function(value) {
        if (!value || !this.priceMin) return true; // Both fields are optional
        
        // priceMax must be greater than or equal to priceMin
        return value >= this.priceMin;
      },
      message: 'Maximum price must be greater than or equal to minimum price.'
    }
  }
});
            

Array Validation

MongoDB's flexible schema allows for arrays of various types. Mongoose provides ways to validate both the entire array and individual elements.

const courseSchema = new Schema({
  title: {
    type: String,
    required: true
  },
  
  // Array of simple values with validation
  tags: {
    type: [String],
    validate: {
      validator: function(array) {
        // Must have at least one tag
        return array.length > 0;
      },
      message: 'Course must have at least one tag.'
    }
  },
  
  // Array of objects with nested validation
  lessons: {
    type: [{
      title: {
        type: String,
        required: true
      },
      duration: {
        type: Number,
        required: true,
        min: 1,
        max: 240 // Maximum duration in minutes
      },
      content: {
        type: String,
        required: true,
        minlength: 10
      }
    }],
    validate: {
      validator: function(array) {
        // Must have at least one lesson
        return array.length > 0;
      },
      message: 'Course must have at least one lesson.'
    }
  },
  
  // Custom validation for each element in an array
  prerequisites: {
    type: [String],
    validate: [
      {
        validator: function(array) {
          // Check if all prerequisites are unique
          return new Set(array).size === array.length;
        },
        message: 'Prerequisites must be unique.'
      },
      {
        validator: function(array) {
          // Check if all prerequisites are in proper format
          return array.every(item => /^[A-Z]{3}[0-9]{3}$/.test(item));
        },
        message: 'Prerequisites must be in the format XXX000.'
      }
    ]
  }
});
            

Update Validators

By default, MongoDB's update operations bypass Mongoose's validation. You can enable validation for updates by setting the runValidators option.

// Update a user with validation
const updateUser = async (userId, updates) => {
  try {
    const user = await User.findByIdAndUpdate(
      userId,
      updates,
      {
        new: true, // Return the updated document
        runValidators: true, // Enable update validators
        context: 'query' // Make `this` in validators refer to the query
      }
    );
    
    return user;
  } catch (error) {
    // Handle validation errors
    if (error.name === 'ValidationError') {
      // Process validation errors
      console.error('Validation error:', error.message);
    }
    
    throw error;
  }
};
            

Schema-wide Validation

Some validation needs to examine the entire document. You can use the validate hook for this purpose.

const projectSchema = new Schema({
  title: {
    type: String,
    required: true
  },
  startDate: {
    type: Date,
    required: true
  },
  endDate: {
    type: Date
  },
  budget: {
    type: Number,
    min: 0
  },
  expenses: {
    type: [{
      description: String,
      amount: Number,
      date: Date
    }]
  },
  status: {
    type: String,
    enum: ['planning', 'ongoing', 'completed', 'cancelled'],
    default: 'planning'
  }
});

// Schema-level validation
projectSchema.pre('validate', function(next) {
  const project = this;
  
  // Ensure end date is after start date
  if (project.endDate && project.startDate && project.endDate < project.startDate) {
    project.invalidate('endDate', 'End date must be after start date.');
  }
  
  // Validate that expenses don't exceed budget
  if (project.budget && project.expenses && project.expenses.length > 0) {
    const totalExpenses = project.expenses.reduce((sum, expense) => sum + expense.amount, 0);
    
    if (totalExpenses > project.budget) {
      project.invalidate('expenses', `Total expenses (${totalExpenses}) exceed budget (${project.budget}).`);
    }
  }
  
  // Validate based on status
  if (project.status === 'completed' && !project.endDate) {
    project.invalidate('endDate', 'End date is required for completed projects.');
  }
  
  next();
});
            

Custom Error Messages

Clear, contextual error messages improve the developer and user experience. Mongoose allows for dynamic error messages that can include field values and other context.

const productSchema = new Schema({
  name: {
    type: String,
    required: [true, 'Product name is required']
  },
  price: {
    type: Number,
    required: [true, 'Product price is required'],
    min: [0, 'Price cannot be negative'],
    validate: {
      validator: function(value) {
        // Price must be a multiple of 0.01 (no more than 2 decimal places)
        return (value * 100) % 1 === 0;
      },
      message: props => `${props.value} is not a valid price. Price must have at most 2 decimal places.`
    }
  },
  sku: {
    type: String,
    required: [true, 'SKU is required'],
    validate: {
      validator: function(value) {
        return /^[A-Z]{2}-\d{4}$/.test(value);
      },
      message: props => `${props.value} is not a valid SKU. Format must be XX-0000.`
    }
  },
  category: {
    type: String,
    required: [true, 'Category is required'],
    enum: {
      values: ['Electronics', 'Clothing', 'Books', 'Home', 'Sports'],
      message: props => `${props.value} is not a supported category. Supported categories: Electronics, Clothing, Books, Home, Sports.`
    }
  }
});
            

Custom Validation Error Handling

When validation fails, Mongoose returns a ValidationError containing detailed information about each invalid field. You can extract and format these errors for user-friendly responses.

// Express route handler with validation error handling
app.post('/api/products', async (req, res) => {
  try {
    const product = new Product(req.body);
    await product.save();
    res.status(201).json(product);
  } catch (error) {
    if (error.name === 'ValidationError') {
      // Format validation errors
      const formattedErrors = formatValidationErrors(error);
      return res.status(400).json({
        message: 'Validation error',
        errors: formattedErrors
      });
    }
    
    // Handle other types of errors
    console.error('Error creating product:', error);
    res.status(500).json({ message: 'Server error' });
  }
});

// Helper function to format validation errors
function formatValidationErrors(error) {
  const formattedErrors = {};
  
  // Loop through all validation errors
  for (const field in error.errors) {
    const fieldError = error.errors[field];
    
    // Format based on error type
    if (fieldError.kind === 'required') {
      formattedErrors[field] = `${fieldError.path} is required`;
    } else if (fieldError.kind === 'enum') {
      formattedErrors[field] = `${fieldError.value} is not a valid option for ${fieldError.path}`;
    } else if (fieldError.kind === 'min') {
      formattedErrors[field] = `${fieldError.path} must be at least ${fieldError.properties.min}`;
    } else if (fieldError.kind === 'max') {
      formattedErrors[field] = `${fieldError.path} must be at most ${fieldError.properties.max}`;
    } else {
      // Use the error message directly
      formattedErrors[field] = fieldError.message;
    }
  }
  
  return formattedErrors;
}