For AI agents: a documentation index is available at https://www.mongodb.com/docs/llms.txt — markdown versions of all pages are available by appending .md to any URL path.
Docs Menu
Docs Home
/ /
Schema Validation
Docs Home
/ /
Best Practices
/
Schema Validation
Docs Home
/
Development
/
Data Modeling
/
Best Practices
/
Schema Validation

Specify Validation Level for Existing Documents

For documents that already exist in your collection before you add 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

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.

strict

(Default) MongoDB applies the same validation rules to all document inserts and updates.

constraint

MongoDB applies the validation rules to all document inserts and updates, and guarantees that every document in the collection satisfies the rules. Unlike strict, a collection with constraint validation can't contain documents that were invalid before you set the level. This level adds the following restrictions:

  • The validation action must be error or errorAndLog.

  • You can't modify the schema validation rules while the level is constraint. To change your validation rules, downgrade to strict, modify the rules, and then upgrade back to constraint.

New in version 9.0. :

Prerequisite

The examples on this page use a movies collection. To create the collection and insert the documents that the examples use, run the following command:

db.movies.insertMany( [
   { title: "The Godfather", year: 1972 },
   { title: "Casablanca", year: 1942 }
] )

Specify moderate Validation

The following example adds a moderate validator to the movies collection and inserts a document that satisfies the validation rules.

1

Specify validation rules with moderate validation level.

Add a validator to the movies collection with moderate validationLevel:

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

Because the validationLevel is moderate, MongoDB applies the validation rules to all document inserts and to updates of existing documents that already meet the rules.

2

Insert a valid document.

The following insert command adds a document that includes a title field with a string value, which satisfies the validation rule:

db.movies.insertOne(
   { title: "Wings", year: 1927 }
)
3

Observe results.

The insert succeeds because the document satisfies the validation rules. MongoDB returns output similar to the following:

{
  acknowledged: true,
  insertedId: ...
}

Specify strict Validation

The following example adds a strict validator to the movies collection and inserts a document that satisfies the validation rules.

1

Specify validation rules with strict validation level.

Add a validator to the movies collection with strict validationLevel:

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

Because the validationLevel is strict, MongoDB applies the validation rules to all document inserts and updates.

2

Insert a valid document.

The following insert command adds a document that includes a title field with a string value, which satisfies the validation rule:

db.movies.insertOne(
   { title: "The Conversation", year: 1974 }
)
3

Observe results.

The insert succeeds because the document satisfies the validation rules. MongoDB returns output similar to the following:

{
  acknowledged: true,
  insertedId: ...
}

Note

When you upgrade to strict validation, MongoDB does not retroactively check that existing documents in the collection pass the validator. After the upgrade, the collection may contain invalid documents that existed before the upgrade. However, update operations on invalid documents fail because of the validator. To update an invalid document, first resolve the issue that fails the validator.

Specify constraint Validation

The following example upgrades the movies collection to the constraint validation level. When you upgrade to the constraint level, MongoDB checks that every document already in the collection satisfies the validator.

Note

The following procedure applies to a collection that already exists. If you set the validationLevel to constraint when you create the collection, you don't need to set the level to strict first or prepare the collection.

1

(Conditional) Set your validationLevel to strict.

If your collection's validationLevel is not already strict, follow the procedure to specify strict validation.

2

Prepare the collection for the constraint level.

Run collMod with prepareConstraintValidationLevel set to true:

db.runCommand( {
   collMod: "movies",
   prepareConstraintValidationLevel: true
} )

This command prepares the collection for the upgrade by blocking bypassDocumentValidation and preventing changes to the validator.

3

Set the validation level to constraint.

Run collMod to set the validationLevel to constraint. The validationAction must be error or errorAndLog:

db.runCommand( {
   collMod: "movies",
   validationLevel: "constraint",
   validationAction: "error"
} )

You can't change the validator in the same collMod operation that upgrades the validationLevel to constraint. Set the validation rules before you run this command. To change the rules later, downgrade the level to strict, modify the rules, and then upgrade back to constraint.

Because the validationLevel is constraint, MongoDB applies the validation rules to all document inserts and updates, regardless of whether an existing document met the rules before the upgrade.

When you set the level to constraint, MongoDB scans all existing documents in the collection and fails the collMod operation if any document violates the validator. This scan can be computationally expensive for large collections. If the operation fails, update the violating documents to pass the validator before you continue.

4

Insert a valid document.

The following insert command adds a document that includes a title field with a string value, which satisfies the validation rule:

db.movies.insertOne(
   { title: "Sunrise", year: 1927 }
)
5

Observe results.

The insert succeeds because the document satisfies the validation rules. MongoDB returns output similar to the following:

{
  acknowledged: true,
  insertedId: ...
}

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

Back

Specify Query Operators

Next

Handle Invalid Documents

On this page