MongoDB Schema Validation Makes Flexibility Reviewable

A flexible document model does not require accepting every document shape. MongoDB collection validation can reject invalid writes at the database boundary, complementing application validation and protecting against scripts or clients that bypass application code.

The useful question is which fields form a durable contract and which fields are intentionally extensible. Define that boundary before adding a large validator that accidentally rejects legitimate historical data.

The concrete problem

This example creates a new collection with a narrow contract for an order. It uses BSON types deliberately: an integer application value may serialize as int or long depending on the driver, while monetary decimals require an appropriate Decimal128 representation.

Figure: Flexible document envelope → Required typed business fields → Invalid write rejected.

A worked example

db.createCollection('orders', {
  validator: {
    $jsonSchema: {
      bsonType: 'object',
      required: ['tenantId', 'state', 'total'],
      properties: {
        tenantId: {bsonType: 'string'},
        state: {enum: ['pending', 'confirmed', 'cancelled']},
        total: {bsonType: 'decimal', minimum: NumberDecimal('0')}
      }
    }
  },
  validationLevel: 'strict',
  validationAction: 'error'
});

Why the behavior matters

This contract requires the core fields but does not forbid every additional field. If additionalProperties is set to false, explicitly account for _id and every allowed property. Otherwise the validator can reject ordinary documents unexpectedly.

Validation and uniqueness solve different problems. Use a unique index for a unique business identifier; a JSON schema validator does not search the collection to prove uniqueness. Likewise, a document-level schema does not automatically enforce relationships between separate collections.

Failure modes and design tradeoffs

Adding or tightening validation on an existing collection requires inspecting historical documents and planning compatibility with old application versions. Validation settings affect how writes are checked; they are not a magic bulk rewrite or an assertion that all existing documents are already valid.

Some privileged operations can bypass document validation. Grant that capability narrowly and test with the actual runtime role. A passing unit test under an administrator account does not establish the production authorization boundary.

What to verify before adoption

Insert valid documents, omit required fields, use the wrong BSON numeric type and attempt an invalid state transition. Confirm expected rejection behavior through the application's actual driver. Inventory old documents before changing a live validator and rehearse rolling application deployment with both accepted shapes.

Primary reference

• MongoDB documentation. Verify the exact deployed version and driver behavior before using the example in a production runbook.