/ /

/ /

Modify Schema Validation

After you add schema validation to a collection, you can modify validation rules at any time. For example, you may decide:

That documents in a users collection no longer require an email address.
To increase the minimum length for a password field from 8 characters to 12.

To modify a collection's schema validation, use the collMod command and specify the updated validation in the validator object.

About This Task

You can modify most components of a schema validation, including its rules, validation level, and validation action.

Note

If you set your validation level to constraint, you can't modify the schema validation rules directly. To change your validation rules, downgrade to strict, modify the rules, and then upgrade back to constraint. For more information on this procedure, see Specify constraint Validation.

If you update a collection's validation rules, documents inserted before the validation change may no longer be valid. MongoDB handles these previously existing invalid documents differently depending on your validationLevel.

At the strict and moderate levels, MongoDB applies validation checks when you insert or update a document but does not retroactively validate documents already in the collection. An update to an already invalid document fails, even if the update itself doesn't introduce the violation.

At the constraint level, MongoDB validates the entire collection when you upgrade to that level. If you downgrade to strict, modify the rules, and then upgrade back to constraint, the upgrade fails if any document doesn't match the new rules.

Steps

The following procedure creates a collection with validation rules and then modifies those rules.

Create a collection with validation.

Create a users collection with validation rules:

db.createCollection("users", {
   validator: {
      $jsonSchema: {
         bsonType: "object",
         required: [ "username", "password" ],
         properties: {
            username: {
               bsonType: "string",
               description: "must be a string and is required"
            },
            password: {
               bsonType: "string",
               minLength: 8,
               description: "must be a string at least 8 characters long, and is required"
            }
         }
      }
   }
} )

Modify the validation schema.

Run the following collMod command to change the minLength of the password field from 8 to 12:

db.runCommand( { collMod: "users",
   validator: {
      $jsonSchema: {
         bsonType: "object",
         required: [ "username", "password" ],
         properties: {
            username: {
               bsonType: "string",
               description: "must be a string and is required"
            },
            password: {
               bsonType: "string",
               minLength: 12,
               description: "must be a string of at least 12 characters, and is required"
            }
         }
      }
   }
} )

Tip

You can also use the collMod command to add validation to an existing collection that was not created with validation.

Results

The following sections show the results of the updated validation in these scenarios:

When you insert an invalid document.
When you insert a valid document.
When a previously valid document becomes invalid because of the validation rule changes.

Insert an Invalid Document

The following operation attempts to insert an invalid document. The document is invalid because the password field is 10 characters long when the minimum length is 12:

db.users.insertOne(
   {
      "username": "salesAdmin01",
      "password": "kT9$j4wg#M"
   }
)

MongoDB returns the following error:

MongoServerError: Document failed validation
Additional information: {
  failingDocumentId: ObjectId("62be0adb73c105dde9231299"),
  details: {
    operatorName: '$jsonSchema',
    schemaRulesNotSatisfied: [
      {
        operatorName: 'properties',
        propertiesNotSatisfied: [
          {
            propertyName: 'password',
            description: 'must be a string of at least 8 characters, and is required',
            details: [
              {
                operatorName: 'minLength',
                specifiedAs: { minLength: 12 },
                reason: 'specified string length was not satisfied',
                consideredValue: 'kT9$j4wg#M'
              }
            ]
          }
        ]
      }
    ]
  }
}

Insert a Valid Document

The following operation inserts a valid document, where the password field is at least 12 characters long:

db.users.insertOne(
   {
      "username": "salesAdmin01",
      "password": "8p&SQd7T90$KKx"
   }
)

Handle a Previously Valid Document That Is No Longer Valid

Consider the following document that is valid for the first version of the schema validation, but not the second:

db.users.insertOne(
   {
      "username": "salesAdmin02",
      "password": "i8U60*VyL8"
   }
)

The document's password field is 10 characters. The first version of the schema validation required a minimum of 8 characters, meaning this document was valid. However, after updating the validation to require the password to be a minimum of 12 characters, the document is no longer valid.

When a change in schema validation causes previously valid documents to become invalid, the newly invalid documents remain in the collection.

The way MongoDB handles newly invalid documents depends on the schema's validationLevel. The schema validation in this example uses the default validationLevel of strict, meaning the document must match the new validation rules. MongoDB checks the validation each time the document is updated.

If the updated schema validation had a validationLevel of moderate, this document would not need to match the new validation rules.

Learn More

Back

View Existing Rules

Query and Modify