Schema Design Decision Framework
Learners will apply a structured checklist—query patterns, write frequency, document growth—to choose between embedding and referencing for any domain.
Schema Design Decision Framework is a free MongoDB Academy lesson on CoddyKit — lesson 4 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the MongoDB Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.
Why a Decision Framework Matters
MongoDB's schema flexibility is powerful but can lead to analysis paralysis. Should you embed or reference? When is the choice not obvious? A structured decision framework replaces guesswork with a repeatable checklist. By asking the same questions about query patterns, write frequency, and document growth, you can arrive at the right schema for any domain—consistently.
Step 1: Identify Query Patterns
Start by listing the most frequent read queries your application makes. Ask: do these queries always need the parent and children together, or are children queried independently? If child data is almost always fetched with its parent, embedding eliminates a round trip. If children are frequently queried, sorted, or filtered on their own, referencing keeps queries simple and indexes focused.
Step 2: Estimate Data Size and Growth
For every potential array or nested structure, ask: how many elements will this have at steady state, and can it grow without bound? Use rough business rules: a user rarely has more than 5 addresses (embed), but can write thousands of reviews (reference). Anything with an unbounded or unknown upper limit is a candidate for a separate collection.
Step 3: Evaluate Write Frequency
Consider how often the child data is written compared to the parent. Embedding means every child update rewrites the parent document, triggering a storage move if the document grows. If children are updated very frequently and independently of the parent, the overhead of rewriting the parent each time favours referencing—child documents update in place without touching the parent at all.
Step 4: Check for Data Sharing
Ask whether the child data is owned by one parent or shared across multiple parents. An address is owned by a single user—safe to embed. A product in a catalogue is referenced by potentially thousands of orders—it must be in its own collection to avoid duplication and stale data. Shared data should always be referenced, never embedded.
Step 5: Assess Atomicity Requirements
MongoDB guarantees atomic writes at the document level for free—no transactions needed. If you need to update a parent and its children atomically, embedding keeps both in the same document so any update is atomic by default. If you reference across two collections and need atomicity, you must use a multi-document transaction, which adds latency and complexity.
The Framework Decision Table
Apply these rules in order:
- Children always fetched with parent + small count + owned by parent: EMBED
- Children queried independently or shared: REFERENCE
- Children can grow without bound: REFERENCE (or bucket pattern)
- Atomic update required across parent + children: EMBED (or transaction)
- Write frequency of children high relative to parent: REFERENCE
If multiple rules conflict, referencing is the safer default.
Example: E-Commerce Order Schema
Apply the framework to an order in an e-commerce system. Line items: always fetched with order, small count (under 50), owned by order → embed. Shipping address: snapshot at order time, never shared → embed. Customer: shared across thousands of orders → reference. Product catalogue: shared across orders, updated independently → reference.
db.orders.insertOne({
_id: ObjectId(),
customerId: ObjectId('c1'), // reference — shared data
shippingAddress: { // embed — point-in-time snapshot
street: '123 Maple St',
city: 'Austin'
},
items: [ // embed — small, owned by order
{ productId: ObjectId('p1'), qty: 2, price: 19.99, name: 'Widget' }
]
});Example: Social Media Schema
Apply the framework to a social media post. Post author: shared across posts → reference. Post body and metadata: owned by post, small → embed. Likes (count only): numeric field → embed as a counter. Comments: potentially thousands, queried and paginated independently → reference in a separate comments collection.
db.posts.insertOne({
_id: ObjectId(),
authorId: ObjectId('u1'), // reference
title: 'Why MongoDB rocks',
body: '<p>Because documents...</p>',
tags: ['mongodb', 'nosql'], // embed — small, owned
likesCount: 0, // embed — simple counter
createdAt: new Date()
// comments live in db.comments, NOT embedded here
});Evolving Your Schema Over Time
The right schema at launch may not be the right schema at scale. Start with the simplest correct design. If you later discover that an embedded array is growing too large, migrate it to a separate collection. MongoDB's flexible schema makes incremental evolution possible—you can write new documents in the new shape while keeping old ones, then backfill with a migration script.
Documenting Your Schema Decisions
Write down the reasoning behind each schema choice while it is fresh. A comment in a Mongoose schema file or a short design document explaining why items are embedded but customerId is referenced pays enormous dividends when a new engineer joins or when you revisit the schema six months later. Schema design is a deliberate act, not an accident.
const orderSchema = new mongoose.Schema({
customerId: { type: mongoose.Schema.Types.ObjectId, ref: 'Customer' }, // reference: shared
shippingAddress: addressSchema, // embed: point-in-time snapshot
items: [lineItemSchema], // embed: small, always with order
status: { type: String, enum: ['pending', 'shipped', 'delivered'] },
createdAt: { type: Date, default: Date.now }
});Quick Check
Test your understanding of MongoDB & NoSQL Databases concepts from this lesson.
Lesson Recap
In this lesson you learned: the five-step decision framework covers query patterns, data size, write frequency, sharing, and atomicity, shared data always belongs in a separate referenced collection, and schema decisions should be documented alongside the code. Next up we explore schema validation with JSON Schema to enforce data quality in MongoDB collections.
Frequently asked questions
Is the “Schema Design Decision Framework” lesson free?
Yes — the full text of “Schema Design Decision Framework” is free to read here on the web, and the MongoDB Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the MongoDB Academy course, upgrade to CoddyKit PRO.
What will I learn in “Schema Design Decision Framework”?
Learners will apply a structured checklist—query patterns, write frequency, document growth—to choose between embedding and referencing for any domain. You practise MongoDB Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.
Do I need any experience to start MongoDB Academy?
No prior experience is required. MongoDB Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 4 of 4, so you can start here or from the beginning and move at your own pace.
How long does the “Schema Design Decision Framework” lesson take?
Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.
Can I write and run code in this MongoDB Academy lesson?
Yes. Every MongoDB Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.
All lessons in this course
- Embedding: One-to-Few Relationships
- Referencing: One-to-Many and Many-to-Many
- The Unbounded Array Anti-Pattern
- Schema Design Decision Framework