Docs Home → MongoDB Manual

Specify Validation Level for Existing Documents

On this page

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 LevelBehavior
strict(Default) MongoDB applies validation rules to all inserts and updates.
moderateMongoDB only applies validation rules to existing valid documents. Updates to invalid documents which exist prior to the validation being added are not checked for validity.

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 that:

  • 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