📐 Schema Design & Governance

Dynamic vs Structured

MongoDB collections can contain documents with varying fields, but this doesn't mean you should ignore structure entirely. Think of it as "schema on write" flexibility with "validation on demand" control.

// Same collection, different structures (allowed, but not always wise!)
{
  _id: 1,
  name: "Alice",
  email: "alice@example.com",
  age: 28
}

{
  _id: 2,
  name: "Bob",
  contactEmail: "bob@example.com",  // Different field name
  dateOfBirth: "1995-03-15",        // Different approach to age
  phoneNumber: "555-0123"           // Extra field
}

{
  _id: 3,
  fullName: "Charlie",               // Another different field
  contact: {                         // Nested structure
    email: "charlie@example.com",
    phone: "555-0456"
  }
}

⚠️ Warning: Just because you CAN have different structures doesn't mean you SHOULD. Inconsistent schemas lead to complex application code, difficult queries, and maintenance nightmares!

The Balance: Flexibility + Governance

The sweet spot is using MongoDB's flexibility for legitimate business needs while maintaining governance through:

• ✅ Schema Validation Rules - Enforce required fields and data types
• ✅ Application-Level Models - Use Mongoose, PyMongo models, etc.
• ✅ Documentation - Maintain clear schema documentation
• ✅ Migration Strategies - Plan for schema evolution

Pattern Examples

1. Embedding Pattern - Blog Post

// ✅ Good: Embed comments (one-to-few)
{
  _id: 1,
  title: "MongoDB Schema Design",
  content: "...",
  author: "Alice",
  comments: [                        // Embedded array
    {
      user: "Bob",
      text: "Great article!",
      date: "2024-01-15"
    },
    {
      user: "Charlie",
      text: "Very helpful!",
      date: "2024-01-16"
    }
  ],
  tags: ["mongodb", "schema", "database"],
  publishedAt: "2024-01-15"
}

// ✅ Benefits:
// - Single query gets post + comments
// - Atomic updates
// - Comments don't exist independently

2. Referencing Pattern - E-Commerce

// Orders collection
{
  _id: 1001,
  orderNumber: "ORD-2024-001",
  customerId: 501,                   // Reference to customer
  items: [
    { productId: 201, quantity: 2 }, // References to products
    { productId: 202, quantity: 1 }
  ],
  total: 150,
  status: "shipped",
  orderDate: "2024-01-15"
}

// Customers collection
{
  _id: 501,
  name: "Alice Johnson",
  email: "alice@example.com",
  address: { /* ... */ }
}

// Products collection
{
  _id: 201,
  name: "Wireless Mouse",
  price: 25,
  stock: 100
}

// ✅ Benefits:
// - Customer data updated once, reflects in all orders
// - Product details stay current
// - Orders remain small and fast

3. Bucket Pattern - IoT Sensor Data

// ❌ Bad: One document per reading (millions of docs!)
{
  sensorId: "TEMP-001",
  temperature: 22.5,
  timestamp: "2024-01-15T10:00:00Z"
}

// ✅ Good: Bucket readings by hour
{
  _id: ObjectId("..."),
  sensorId: "TEMP-001",
  date: "2024-01-15",
  hour: 10,
  readings: [
    { minute: 0, temperature: 22.5 },
    { minute: 1, temperature: 22.6 },
    { minute: 2, temperature: 22.4 },
    // ... 57 more readings
  ],
  count: 60,
  avgTemp: 22.5,
  minTemp: 22.1,
  maxTemp: 22.9
}

// ✅ Benefits:
// - 60x fewer documents
// - Pre-computed statistics
// - Efficient time-range queries

4. Subset Pattern - Social Media

// Users collection (full data)
{
  _id: 101,
  username: "alice",
  fullName: "Alice Johnson",
  email: "alice@example.com",
  bio: "Software engineer...",
  followers: [...],                  // 10,000 follower IDs
  following: [...],                  // 5,000 following IDs
  posts: [...]                       // References to posts
}

// Posts collection (subset of user data)
{
  _id: 5001,
  content: "Just learned MongoDB!",
  author: {                          // Subset of user data
    userId: 101,
    username: "alice",
    fullName: "Alice Johnson"
    // Don't include email, bio, followers!
  },
  likes: 42,
  comments: [...],
  createdAt: "2024-01-15"
}

// ✅ Benefits:
// - Display posts without joining users
// - Keep posts small (no follower lists!)
// - Still link to full user profile

5. Computed Pattern - Analytics

// Product with pre-computed metrics
{
  _id: 301,
  name: "Premium Headphones",
  price: 199,
  category: "Electronics",
  
  // Computed fields (updated periodically)
  stats: {
    totalSold: 1247,
    totalRevenue: 248153,
    avgRating: 4.7,
    ratingCount: 523,
    lastUpdated: "2024-01-15T12:00:00Z"
  },
  
  // Recent reviews (subset)
  recentReviews: [
    { user: "Bob", rating: 5, text: "Excellent!" },
    { user: "Charlie", rating: 4, text: "Good quality" }
  ]
}

// ✅ Benefits:
// - Fast dashboard queries
// - No aggregation needed for stats
// - Updated in background job

6. Extended Reference Pattern - Orders

// Order with extended customer reference
{
  _id: 1001,
  orderNumber: "ORD-2024-001",
  
  // Extended reference: ID + frequently accessed fields
  customer: {
    customerId: 501,                 // Reference ID
    name: "Alice Johnson",           // Frequently needed
    email: "alice@example.com"       // Frequently needed
    // Don't include: full address, payment methods, etc.
  },
  
  items: [...],
  total: 150,
  status: "shipped"
}

// ✅ Benefits:
// - Display order details without join
// - Still link to full customer record
// - Balance between embedding and referencing

Decision Tree

START: Should I embed or reference?
├─ Does child data exist independently? 
│  ├─ NO  → Likely EMBED
│  └─ YES → Continue...
│
├─ How many child items?
│  ├─ < 100       → Likely EMBED
│  ├─ 100-1000    → Consider SUBSET pattern
│  └─ > 1000      → REFERENCE
│
├─ Is data always accessed together?
│  ├─ YES → EMBED
│  └─ NO  → REFERENCE
│
├─ Do you need atomic updates?
│  ├─ YES → EMBED
│  └─ NO  → REFERENCE can work
│
└─ What's your access pattern?
   ├─ Read-heavy  → EMBED (fast reads)
   └─ Write-heavy → REFERENCE (smaller docs, targeted updates)

Real-World Examples

📦 Embed: Blog Post & Comments (one-to-few)

// ✅ Perfect for embedding
{
  title: "My First Post",
  content: "...",
  comments: [                        // Usually < 100 comments
    { user: "Alice", text: "Great!" },
    { user: "Bob", text: "Thanks!" }
  ]
}

// Why embed?
// ✓ Posts and comments always displayed together
// ✓ Few comments per post
// ✓ Comments don't exist without post
// ✓ Need atomic updates

🔗 Reference: E-commerce Orders & Products (many-to-many)

// ✅ Perfect for referencing
// Orders
{
  _id: 1,
  customerId: 501,
  items: [
    { productId: 201, qty: 2 },      // Reference!
    { productId: 202, qty: 1 }
  ]
}

// Products
{
  _id: 201,
  name: "Laptop",
  price: 1200,
  stock: 50
}

// Why reference?
// ✓ Products exist independently
// ✓ Product details update (price, stock)
// ✓ Many orders reference same product
// ✓ Need to query products separately

🔗📄 Extended Reference: User & Posts (hybrid)

// ✅ Best of both worlds
{
  _id: 5001,
  content: "Check out my new post!",
  author: {
    userId: 101,                     // Reference
    username: "alice",               // Cached for display
    avatar: "https://..."            // Cached for display
    // Full user data still in users collection
  },
  likes: 42
}

// Why extended reference?
// ✓ Display posts without join
// ✓ Full user profile still accessible
// ✓ Username changes? Update in background
// ✓ Balance performance and consistency

Advanced Validation Patterns

Conditional Validation

// Different rules based on user type
{
  validator: {
    $jsonSchema: {
      bsonType: "object",
      required: ["email", "userType"],
      properties: {
        userType: { enum: ["customer", "admin"] }
      },
      // If admin, require adminCode
      if: {
        properties: { userType: { const: "admin" } }
      },
      then: {
        required: ["adminCode"],
        properties: {
          adminCode: { bsonType: "string", minLength: 10 }
        }
      }
    }
  }
}

Expression-Based Validation

// Use MongoDB operators for complex rules
{
  validator: {
    $expr: {
      $and: [
        // End date must be after start date
        { $gte: ["$endDate", "$startDate"] },
        // Discount must be less than price
        { $lt: ["$discount", "$price"] },
        // Status must be consistent with payment
        {
          $cond: {
            if: { $eq: ["$paymentStatus", "paid"] },
            then: { $in: ["$orderStatus", ["processing", "shipped", "delivered"]] },
            else: { $eq: ["$orderStatus", "pending"] }
          }
        }
      ]
    }
  }
}

Common Anti-Patterns to Avoid

// ❌ BAD: Unbounded array growth
{
  userId: 101,
  posts: [/* 10,000 post objects */],
  followers: [/* 50,000 user IDs */]
}

// ✅ GOOD: Reference pattern
{
  userId: 101,
  postCount: 10000
}
// Posts in separate collection

// ❌ BAD: Embedding frequently updated data
{
  productId: 201,
  name: "Laptop",
  price: 1200,
  reviews: [/* embedding full review objects */]
}
// Every new review updates the product doc!

// ✅ GOOD: Reviews in separate collection
{
  productId: 201,
  name: "Laptop",
  price: 1200,
  reviewCount: 523,
  avgRating: 4.7
}

// ❌ BAD: No validation, inconsistent data
{ name: "Alice", email: "alice@example.com", age: 28 }
{ name: "Bob", mail: "bob@", years: "thirty" }
{ fullName: "Charlie", contact: "charlie@example.com" }

// ✅ GOOD: Schema validation enforces consistency
// All documents have same required fields and types