Schema Validation

What we're doing: Show a validator rejecting an insert that violates it, and one that is allowed because the field it violates is not covered.

// Rejected: "total" is required and must be a non-negative decimal
db.orders.insertOne({ customerId: 1, total: -5 })
// -> Document failed validation

// Allowed: "notes" is not mentioned by the validator, so any shape is fine
db.orders.insertOne({ customerId: 1, total: 20.00, notes: { anything: "goes" } })

2

The validator enforces total >= 0 because that field is explicitly constrained — the insert is rejected before it is written.

6

The "notes" field is not mentioned anywhere in the validator, so it passes through unconstrained — this is what "partial" validation means in practice.

Why this works: A validator lets a team lock down the fields that matter for correctness (an order must have a non-negative total) while leaving room for fields that genuinely vary or are still evolving — the two are not mutually exclusive in the same collection.

What we're doing: Write a $jsonSchema covering a required field, a range constraint, an enum, and a nested embedded document.

{
  bsonType: "object",
  required: ["status", "total"],
  properties: {
    status: { enum: ["pending", "shipped", "delivered", "cancelled"] },
    total: { bsonType: "decimal", minimum: 0 },
    shipping: {
      bsonType: "object",
      properties: { city: { bsonType: "string" } }
    }
  }
}

4

enum restricts "status" to exactly these four values — an insert with any other string is rejected.

9

A nested properties schema validates the shape of the embedded "shipping" document, the same way the top level does.

Why this works: The same schema vocabulary (bsonType, required, properties) applies at any nesting level, so an embedded document's shape gets the same rigor as the top-level document without a different syntax to learn.

What we're doing: Distinguish a field worth validating (breaks a report if wrong) from one not worth validating (nothing depends on its shape).

// Worth validating: a revenue report sums "total" — a string here breaks the $sum aggregation
{ total: { bsonType: "decimal", minimum: 0 } }  // required, type-checked

// Not worth validating: "notes" is only ever displayed as free text, nothing depends on its shape
// (left out of the validator entirely — schema-flexible by default)

2

A revenue report's $sum aggregation on "total" produces wrong or erroring results if even one document stores it as a string — this is exactly the kind of downstream break validation prevents.

5

Nothing downstream cares what shape "notes" takes, so validating it would add friction (rejecting legitimate free-text variety) without preventing any real failure.

Why this works: The decision of what to validate is itself a design choice, guided by what actually depends on a field's shape — not a blanket "validate everything" or "validate nothing" default.

What we're doing: Show moderate+warn as a safe rollout path on a collection with legacy documents, then tightening to strict+error once clean.

// Step 1: roll out cautiously — see what would fail, without rejecting anything yet
db.runCommand({ collMod: "orders", validator: {...}, validationLevel: "moderate", validationAction: "warn" })
// -> check the logs for violations, fix or migrate the offending documents

// Step 2: once the logs are clean, enforce for real
db.runCommand({ collMod: "orders", validator: {...}, validationLevel: "strict", validationAction: "error" })

2

moderate+warn is the safest way to introduce a new validator: nothing is rejected yet, but the logs reveal exactly which existing documents or write paths would fail once enforcement tightens.

6

Switching to strict+error only after the warnings are addressed avoids a surprise wave of rejected writes on day one of enforcement.

Why this works: Deploying a brand-new validator directly as strict+error risks rejecting legitimate application writes the moment any existing document or write path does not yet conform — the warn action gives visibility before the error action starts blocking anything.

What we're doing: Contrast validation strength across two collections in the same application, and show a collection moving from loose to strict as it matures.

// Payments: business-critical, stable shape — strict validation from day one
db.createCollection("payments", { validator: { $jsonSchema: {...} }, validationLevel: "strict" })

// A new "featureEvents" collection, shape still being iterated on — no validator yet
db.createCollection("featureEvents")
// -> revisit once the event shape has stabilized across a few releases, then add a validator

2

A malformed payment document is expensive — strict validation from the start is worth the friction it adds.

6

An event schema still being designed benefits more from staying flexible while the team learns what fields it actually needs, than from locking in rules that will need frequent changing.

Why this works: The same engineering team reasonably makes opposite validation-strength decisions for two collections in the same project, because the two questions that decide it — cost of a bad document, and how settled the shape is — have different answers for each.

What we're doing: Show a bad document reaching a collection through a path that skips application validation, and a validator catching what the app layer missed.

// A one-off migration script writes directly, skipping the app's normal order-creation code entirely:
db.orders.insertOne({ customerId: 1, total: "twenty" })   // wrong type, app validation never ran

// With a collection validator in place, the same write is rejected regardless of its source:
db.orders.insertOne({ customerId: 1, total: "twenty" })
// -> Document failed validation: total must be decimal

2

A migration script talking to the database directly has no reason to reuse the application's validation logic — and often does not.

6

The collection validator applies to this insert exactly as it would to any other, because it runs at the database rather than in any one code path.

Why this works: The number of code paths that can reach a collection tends to grow over a project's life — new services, scripts, admin tools — and each one that was not built with the original application's validation in mind is a gap a database-level validator closes automatically.