Docs Menu
Docs Home
/
MongoDB Manual
/
Data Modeling
/
Schema Validation

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.

Context

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 required to pass validation.

Prerequisite

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" }
])

Steps: Use strict Validation

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

1

Specify validation rules with strict validation level.

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

Test the validation.

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

Observe results.

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' ]
       }
     ]
   }
 }

Steps: Use moderate Validation

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

1

Specify validation rules with moderate validation level.

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

Test the validation.

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

Observe results.

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.

Learn More

  • Choose How to Handle Invalid Documents

  • Modify Schema Validation

Back

Specify Query Operators

Next

Handle Invalid Documents