Skip to main content
Bytes & Beyond

Why Mongoose Exists in a Schema-Flexible World

How Mongoose brings structure to MongoDB's Wild West flexibility

The Wild West Problem

Key idea: MongoDB gives you total freedom with your data structure, but that freedom can quickly turn into a mess if you’re not careful.

Let’s say you’re working on a new app with a team. Here’s how three different developers might each add a user—notice the differences:

Developer A:

{
  name: "Mehedi",
  email: "mehedi@example.com",
  age: 28
}

Standard, expected structure.

Developer B:

{
  username: "sarah_dev",
  email_address: "sarah@example.com",
  birthdate: "1995-03-15"
}

Different field names and structure.

Developer C:

{
  person: {
    fullName: "John Doe",
    contact: {
      electronic: "john@example.com"
    }
  },
  metadata: ["user", "premium"]
}

Deeply nested and custom structure.

Problem: Three developers, three totally different user formats—all in the same collection. If your frontend tries to display these users, things will probably fall apart. This is the “Wild West” of MongoDB: when you have total freedom, it’s easy for things to spiral into chaos.

Enter Mongoose: Bringing Order

Solution: This is where Mongoose steps in—think of it as the sheriff who brings order to the chaos. MongoDB lets you do whatever you want, but Mongoose lays down the law and makes sure everyone follows the same rules.

// Mongoose Schema: The Rules
const UserSchema = new mongoose.Schema({
  name: {
    type: String,
    required: true,
    trim: true
  },
  email: {
    type: String,
    required: true,
    unique: true,
    lowercase: true
  },
  age: {
    type: Number,
    min: 0,
    max: 150
  }
});

const User = mongoose.model('User', UserSchema);

Now, every user must follow this structure. If you try to save a user that doesn’t, Mongoose will throw an error before it ever hits the database.

Example:

const user = new User({
  person: {
    fullName: "John Doe",
    contact: { electronic: "john@example.com" }
  }
});

await user.save();
// Error: Path `name` is required.
// Error: Path `email` is required.

Mongoose steps in and blocks invalid data before it ever reaches your database.

Schema Validation

Mongoose enforces structure and validation at the application layer.

The Mental Model: Application-Layer Enforcement

Here’s the key: MongoDB doesn’t enforce schemas by default at the application level—your application usually does.

Think of MongoDB as a construction site where you can build anything. Mongoose is the blueprint that says, “If you’re building a house, it needs a foundation, walls, and a roof.”

Why This Approach Works

1. Flexibility When You Need It

// Evolving your schema is easy
const UserSchema = new mongoose.Schema({
  name: String,
  email: String,
  // Add new fields later
  preferences: {
    theme: { type: String, default: 'light' },
    notifications: { type: Boolean, default: true }
  }
}, { strict: false }); // Allows extra fields

2. Validation Before Data is Saved

const user = new User({
  name: "", // Invalid: empty string
  email: "not-an-email", // Invalid: wrong format
  age: -5 // Invalid: negative age
});

const errors = user.validateSync();
// Errors are caught before any database operation

3. Consistent Data Structure

// All users follow this structure
{
  _id: ObjectId("..."),
  name: "Mehedi",
  email: "mehedi@example.com",
  age: 28,
  createdAt: ISODate("..."),
  updatedAt: ISODate("...")
}

Mongoose’s Toolkit

Built-in Validators

const UserSchema = new mongoose.Schema({
  email: {
    type: String,
    required: [true, 'Email is required'],
    unique: true,
    lowercase: true,
    validate: {
      validator: function(email) {
        return /\S+@\S+\.\S+/.test(email);
      },
      message: 'Please enter a valid email'
    }
  },
  password: {
    type: String,
    required: true,
    minlength: [8, 'Password must be at least 8 characters'],
    select: false  // Don't return in queries by default
  },
  role: {
    type: String,
    enum: ['user', 'admin', 'moderator'],
    default: 'user'
  },
  profile: {
    firstName: { type: String, required: true, trim: true },
    lastName: { type: String, required: true, trim: true },
    bio: { type: String, maxlength: 500 }
  }
});

Custom Validators

// Check if username is available
UserSchema.path('username').validate(async function(username) {
  const user = await mongoose.model('User').findOne({ username });
  return !user; // Valid if no user found
}, 'Username already taken');

// Ensure age matches birthdate
UserSchema.pre('save', function() {
  if (this.birthdate && this.age) {
    const calculatedAge = new Date().getFullYear() - this.birthdate.getFullYear();
    if (Math.abs(calculatedAge - this.age) > 1) {
      throw new Error('Age does not match birthdate');
    }
  }
});

Virtual Properties

// Virtual property: exists in code, not in database
UserSchema.virtual('fullName').get(function() {
  return `${this.profile.firstName} ${this.profile.lastName}`;
});

UserSchema.virtual('isAdult').get(function() {
  return this.age >= 18;
});

// Usage
const user = await User.findOne();
console.log(user.fullName); // "Mehedi Hasan" 
console.log(user.isAdult);  // true
// But these don't exist in the actual MongoDB document

Real-World Example: Blog System Schemas

Let’s design a blog system using Mongoose schemas:

// User Schema
const UserSchema = new mongoose.Schema({
  username: { 
    type: String, 
    required: true, 
    unique: true,
    minlength: 3,
    maxlength: 20
  },
  email: { 
    type: String, 
    required: true, 
    unique: true,
    lowercase: true 
  },
  password: { 
    type: String, 
    required: true, 
    minlength: 8,
    select: false 
  }
}, { 
  timestamps: true  // Automatic createdAt/updatedAt
});

// Post Schema  
const PostSchema = new mongoose.Schema({
  title: { 
    type: String, 
    required: true,
    maxlength: 100 
  },
  content: { 
    type: String, 
    required: true 
  },
  author: { 
    type: mongoose.Schema.Types.ObjectId, 
    ref: 'User',  // Reference to User model
    required: true 
  },
  status: {
    type: String,
    enum: ['draft', 'published', 'archived'],
    default: 'draft'
  },
  tags: [String],
  metadata: {
    views: { type: Number, default: 0 },
    likes: { type: Number, default: 0 }
  }
}, { timestamps: true });

// Comment Schema
const CommentSchema = new mongoose.Schema({
  content: { 
    type: String, 
    required: true,
    maxlength: 500 
  },
  author: { 
    type: mongoose.Schema.Types.ObjectId, 
    ref: 'User', 
    required: true 
  },
  post: { 
    type: mongoose.Schema.Types.ObjectId, 
    ref: 'Post', 
    required: true 
  }
}, { timestamps: true });

Usage in Practice

// Creating a user (with validation)
const createUser = async (userData) => {
  try {
    const user = new User(userData);
    await user.save(); // Validation happens here
    return user;
  } catch (error) {
    if (error.name === 'ValidationError') {
      // Handle validation errors
      console.log('Validation failed:', error.message);
    }
    throw error;
  }
};

// Creating a post with a user reference
const createPost = async (postData, userId) => {
  const post = new Post({
    ...postData,
    author: userId
  });
  await post.save();
  return post;
};

// Querying with populated relationships
const getPostWithAuthor = async (postId) => {
  return await Post.findById(postId)
    .populate('author', 'username email')
    .exec();
};

Common Pitfalls

1. Schema vs. Database Reality

Note: MongoDB does support database-level schema validation, but Mongoose validation only applies when data flows through your application.

// Your schema says this is required
const UserSchema = new mongoose.Schema({
  email: { type: String, required: true }
});

// But MongoDB itself doesn’t enforce this
// Someone could insert directly via the MongoDB shell:
db.users.insertOne({ name: "No Email User" }); // This works!

// Mongoose validation only works through Mongoose

2. Schema Evolution

// V1: Simple user
const UserSchemaV1 = new mongoose.Schema({
  name: String,
  email: String
});

// V2: Add required field - breaks old documents
const UserSchemaV2 = new mongoose.Schema({
  name: String,
  email: String,
  phoneNumber: { type: String, required: true } // Oops!
});

// Solution: Use defaults or make it optional at first
const UserSchemaV2 = new mongoose.Schema({
  name: String,
  email: String,
  phoneNumber: { type: String, default: null } // Safe migration
});

Interview Insights: Schema Design

Q: What is schema design in MongoDB and how does it differ from relational design?

SQL schema design is a rigid blueprint: all users must have the same fields. Mongoose schema design is a flexible blueprint with rules: all users should have the same fields, but you can deviate if needed.

// Good schema design
const UserSchema = new mongoose.Schema({
  // Identity
  email: {
    type: String,
    required: true,
    unique: true,
    lowercase: true,
    match: /\S+@\S+\.\S+/ // Email validation
  },

  // Profile info (can be embedded or referenced)
  profile: {
    firstName: { type: String, required: true },
    lastName: { type: String, required: true },
    bio: { type: String, maxlength: 500 }
  },

  // Status fields
  isActive: { type: Boolean, default: true },
  role: {
    type: String,
    enum: ['user', 'admin', 'moderator'],
    default: 'user'
  },

  // Timestamp fields
  createdAt: { type: Date, default: Date.now },
  updatedAt: { type: Date, default: Date.now }
});

Key principles for schema design:

  1. Embed when data is accessed together (like user + profile)
  2. Reference when data is updated separately (like user + posts)
  3. Use proper types for storage efficiency and validation
  4. Set defaults to avoid null/undefined issues
  5. Index frequently queried fields for performance