Docs Menu

Docs HomeDevelop ApplicationsMongoDB Manual

Specify Validation Level for Existing Documents

On this page

  • Context
  • Prerequisite
  • Steps: Use strict Validation
  • Steps: Use moderate Validation
  • Learn More

For documents that already exist in your collection prior to adding validation, you can specify how MongoDB applies validation rules to these documents.

Your schema's validationLevel determines the documents for which MongoDB applies validation rules:

Validation Level
Behavior
strict
(Default) MongoDB applies the same validation rules to all document inserts and updates.
moderate
MongoDB applies the same validation rules to document inserts and updates to existing valid documents that match the validation rules. Updates to existing documents in the collection that don't match the validation rules aren't checked for validity.

The examples on this page use a contacts collection with these documents:

db.contacts.insertMany([
{ "_id": 1, "name": "Anne", "phone": "+1 555 123 456", "city": "London", "status": "Complete" },
{ "_id": 2, "name": "Ivan", "city": "Vancouver" }
])

The following example adds a strict validation to the contacts collection and shows the results when attempting to update invalid documents.

1

Add a validator to the contacts collection with strict validationLevel:

db.runCommand( {
collMod: "contacts",
validator: { $jsonSchema: {
bsonType: "object",
required: [ "phone", "name" ],
properties: {
phone: {
bsonType: "string",
description: "phone must be a string and is required"
},
name: {
bsonType: "string",
description: "name must be a string and is required"
}
}
} },
validationLevel: "strict"
} )

Because the validationLevel is strict, when any document is updated, MongoDB checks that document for validation.

2

The following update commands modify both documents in the contacts collection such that neither of the documents are consistent with the validation rule which requires name to be a string:

db.contacts.updateOne(
{ _id: 1 },
{ $set: { name: 10 } }
)
db.contacts.updateOne(
{ _id: 2 },
{ $set: { name: 20 } }
)
3

Both update operations fail. MongoDB returns the following output for each operation:

MongoServerError: Document failed validation
Additional information: {
failingDocumentId: <id>,
details: {
operatorName: '$jsonSchema',
schemaRulesNotSatisfied: [
{
operatorName: 'properties',
propertiesNotSatisfied: [
{
propertyName: 'name',
description: 'name must be a string and is required',
details: [
{
operatorName: 'bsonType',
specifiedAs: { bsonType: 'string' },
reason: 'type did not match',
consideredValue: <value>,
consideredType: 'int'
}
]
}
]
},
{
operatorName: 'required',
specifiedAs: { required: [ 'phone', 'name' ] },
missingProperties: [ 'phone' ]
}
]
}
}

The following example adds a moderate validation to the contacts collection and shows the results when attempting to update invalid documents.

1

Add a validator to the contacts collection with moderate validationLevel:

db.runCommand( {
collMod: "contacts",
validator: { $jsonSchema: {
bsonType: "object",
required: [ "phone", "name" ],
properties: {
phone: {
bsonType: "string",
description: "phone must be a string and is required"
},
name: {
bsonType: "string",
description: "name must be a string and is required"
}
}
} },
validationLevel: "moderate"
} )

Because the validationLevel is moderate:

  • If you update the document with _id: 1, MongoDB applies the new validation rules because the existing document meets the validation requirements.

  • If you update the document with _id: 2, MongoDB does not apply the new validation rules because the existing document does not meet the validation requirements.

2

The following update commands modify both documents in the contacts collection such that neither of the documents are consistent with the validation rule which requires name to be a string:

db.contacts.updateOne(
{ _id: 1 },
{ $set: { name: 10 } }
)
db.contacts.updateOne(
{ _id: 2 },
{ $set: { name: 20 } }
)
3

MongoDB returns the following output for each operation:

// _id: 1
MongoServerError: Document failed validation
Additional information: {
failingDocumentId: 1,
details: {
operatorName: '$jsonSchema',
schemaRulesNotSatisfied: [
{
operatorName: 'properties',
propertiesNotSatisfied: [
{
propertyName: 'name',
description: 'name must be a string and is required',
details: [
{
operatorName: 'bsonType',
specifiedAs: { bsonType: 'string' },
reason: 'type did not match',
consideredValue: 10,
consideredType: 'int'
}
]
}
]
}
]
}
}
// _id: 2
{
acknowledged: true,
insertedId: null,
matchedCount: 1,
modifiedCount: 0,
upsertedCount: 0
}

The output shows:

  • The update fails for the document with _id: 1. This document met the initial validation requirements, and MongoDB applies validation rules to this document.

  • The update succeeds for the document with _id: 2. This document did not meet the initial validation requirements, and MongoDB does not apply validation rules to this document.

Important

The error output is intended for human consumption. It may change in the future and should not be relied upon in scripts.

←  Modify Schema ValidationChoose How to Handle Invalid Documents →