Validation Levels and Actions: strict/moderate, error/warn, and Safe Rollout of New Rules

Learning outcomes

AtlasMart wants to require a two-letter shipping country code. The schema rule is easy; the deployment is not. Two application versions will overlap during a rolling release, and thousands of historical orders lack shipping.countryCode. validation level controls which inserts/updates are subject to the rule, while validation action controls whether a failing write is rejected or allowed and logged. Those knobs are compatibility tools, not substitutes for migration planning.

1. Level answers “which writes are checked?”; action answers “what happens if they fail?”

Under strict (the default), validation applies to inserts and updates, including updates to existing documents that no longer satisfy the current rule. Under moderate, inserts are still validated, and updates to currently valid documents are validated, but updates to existing invalid documents are not required to become valid. This makes moderate useful during repair windows—but it can also let legacy debt continue changing, so you must measure that debt explicitly.

Do not read “moderate” as “validate only the fields I changed.” MongoDB evaluates document validity. The distinction is whether the existing document was valid before the update.

2. The unsafe cutover: strict + error before old writers are gone

If AtlasMart deploys the new required field to the collection before the old order service is upgraded, the database will correctly reject that service's inserts. The validator is doing its job; the deployment contract is wrong. That is why schema enforcement must be coordinated with application compatibility, not merely reviewed as a database change.

3. Run the staged rollout and observe both data and logs

docker rm -f atlasmart-mongo-ch07-l2 2>/dev/null || truedocker volume rm atlasmart-mongo-ch07-l2-data 2>/dev/null || truedocker run -d --name atlasmart-mongo-ch07-l2 \  -p 127.0.0.1:27048:27017 \  -v atlasmart-mongo-ch07-l2-data:/data/db \  mongodb/mongodb-community-server:8.3.8-ubuntu2204-slimmongosh "mongodb://127.0.0.1:27048/atlasmart?directConnection=true" --quiet --eval \'printjson({server:db.version(), hello:db.hello().isWritablePrimary}); printjson(db.getSiblingDB("admin").runCommand({getParameter:1,featureCompatibilityVersion:1}))' 

const orders = db.getCollection("orders_ch07_l2");orders.drop();orders.insertMany([  { _id:"o-7201", customerId:"c-1", totalCents:NumberInt(4500), shipping:{ country:"United States", city:"Seattle" } },  { _id:"o-7202", customerId:"c-2", totalCents:NumberInt(9200), shipping:{ country:"United States", city:"Boston" } },  { _id:"o-7203", customerId:"c-3", totalCents:NumberInt(3100), shipping:{ country:"Canada", countryCode:"CA", city:"Toronto" } }]);const v2 = {  bsonType:"object",  required:["_id","customerId","totalCents","shipping"],  properties:{    _id:{bsonType:"string"}, customerId:{bsonType:"string"},    totalCents:{bsonType:["int","long"], minimum:0},    shipping:{      bsonType:"object", required:["country","countryCode","city"],      properties:{ country:{bsonType:"string"}, countryCode:{bsonType:"string", pattern:"^[A-Z]{2}$"}, city:{bsonType:"string"} }    }  }};print("candidate invalid:", orders.countDocuments({ $nor:[{ $jsonSchema:v2 }] }));// Deliberately unsafe rollout: old writer immediately breaks.printjson(db.runCommand({ collMod:"orders_ch07_l2", validator:{ $jsonSchema:v2 }, validationLevel:"strict", validationAction:"error" }));try {  orders.insertOne({ _id:"o-old-client", customerId:"c-old", totalCents:NumberInt(1000), shipping:{country:"United States", city:"Austin"} });} catch (e) { print("old writer blocked:", e.code); }// Repair the rollout posture first: observe, do not block.printjson(db.runCommand({ collMod:"orders_ch07_l2", validator:{ $jsonSchema:v2 }, validationLevel:"moderate", validationAction:"warn" }));orders.insertOne({ _id:"o-old-during-rollout", customerId:"c-old2", totalCents:NumberInt(1200), shipping:{country:"United States", city:"Denver"} });orders.insertOne({ _id:"o-new-during-rollout", customerId:"c-new", totalCents:NumberInt(1300), shipping:{country:"United States", countryCode:"US", city:"Denver"} });// Deterministic backfill for the lab's known countries.printjson(orders.updateMany(  { "shipping.countryCode": { $exists:false }, "shipping.country":"United States" },  { $set:{ "shipping.countryCode":"US" } }));print("remaining invalid:", orders.countDocuments({ $nor:[{ $jsonSchema:v2 }] }));// Enforce only after old writers are upgraded and debt reaches zero.printjson(db.runCommand({ collMod:"orders_ch07_l2", validator:{ $jsonSchema:v2 }, validationLevel:"strict", validationAction:"error" }));try {  orders.insertOne({ _id:"o-old-after-cutover", customerId:"c-x", totalCents:NumberInt(900), shipping:{country:"United States", city:"Miami"} });} catch (e) { print("old writer rejected after cutover:", e.code); }orders.insertOne({ _id:"o-new-after-cutover", customerId:"c-y", totalCents:NumberInt(900), shipping:{country:"United States", countryCode:"US", city:"Miami"} });print("new writer accepted:", orders.countDocuments({_id:"o-new-after-cutover"}));

Expected result shape

candidate invalid: 2{ ok: 1 }old writer blocked: 121{ ok: 1 }{ acknowledged: true, matchedCount: 3, modifiedCount: 3, ... }remaining invalid: 0{ ok: 1 }old writer rejected after cutover: 121new writer accepted: 1

During warn mode the old-client write is accepted, so an acknowledgement is not proof of schema compliance. The corresponding mongod log contains a “Document would fail validation” event. Log payload detail is version-sensitive and can contain document/field values, so treat diagnostic logs as governed data—not a free telemetry channel.

docker logs atlasmart-mongo-ch07-l2 2>&1 | grep -F "Document would fail validation" || true

docker logs atlasmart-mongo-ch07-l2 2>&1 | Select-String "Document would fail validation"

4. Rollback is a state, not a command

A safe rollback is not simply “set warn again.” Decide what happens if the new application is rolled back after it has written new-only fields. AtlasMart's expansion keeps the old fields readable until the old application is retired. If a cutover causes unexpected rejection, the database team can restore the previous validator or move back to moderate/warn, but only if the application still understands the data written during the experiment.

Backfill rollback is a separate concern. For reversible transformations, retain the source fields or record enough provenance to reconstruct them. For destructive transformations, require a tested backup/restore path. Never claim that a validator can reverse a migration; it only gates future writes.

5. Verification, cleanup, and production judgment

Verification checklist

• The candidate query reports two historical orders without a country code.
• Direct strict/error enforcement blocks the synthetic old writer, demonstrating the deployment incompatibility.
• Moderate/warn permits the old writer while creating observable warning evidence.
• The deterministic backfill reaches zero candidate-invalid documents in the lab.
• Strict/error is enabled only after data and writer compatibility are verified.
• After cutover, the old writer is rejected and the new writer succeeds.

Use warn only when you have a consumer for the warning signal and a plan to drive debt down; otherwise it can turn schema validation into decorative logging. Use moderate deliberately when existing invalid records must remain mutable during migration. Final strict enforcement is strongest when old clients are gone, all historical documents pass, and bypass privileges are controlled. None of these settings change transaction isolation, durability, replica elections, shard targeting, or tenant authorization.

On a large replica set or sharded cluster, backfill writes replicate and consume storage/cache/network budget; validator changes affect every writer quickly. Test under production-like load, throttle from measured pressure, and keep rollback reversible. The next lesson adds a first-class schemaVersion field and compares lazy migration with eager backfills.

docker rm -f atlasmart-mongo-ch07-l2docker volume rm atlasmart-mongo-ch07-l2-data

Authoritative references

• MongoDB 8.3 release notes — Current server-series and patch-release status; re-check before reproducing the lab.
• MongoDB versioning — Explains major/minor release series and why the latest stable patch should be used.
• mongosh release notes — Current mongosh release and version-sensitive shell behavior.
• PyMongo release notes — Current Python driver line used when application-side migration behavior is demonstrated.
• Specify validation level — Defines strict and moderate behavior for existing valid/invalid documents.
• Handle invalid documents — Defines error, warn, and current errorAndLog actions and shows warning log evidence.
• Modify schema validation — Official collMod process and effect of tightening rules on previously valid documents.
• collMod command — Command-level validator, validationLevel, and validationAction options.
• Query valid or invalid documents — Supports preflight debt measurement with $jsonSchema.
• Log messages — Context for treating validation warnings as operational log data.