Docs Menu

Docs HomeMongoDB Manual

Modify Schema Validation

On this page

  • Context
  • Steps
  • Results
  • Learn More

After you add schema validation to a collection, you can modify your schema validation 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.

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

If you update a collection's validation rules, documents inserted prior to the validation change may no longer be valid. How MongoDB handles these invalid documents depends on your validationLevel. By default, MongoDB applies validation checks to all documents, regardless of when they were inserted.

The following procedure creates a collection with validation rules and then modifies those rules. You will observe the results when inserting an invalid and valid document.

1

Create a users collection with validation rules:

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

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: {
name: {
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.

The following examples show what happens when you insert a valid and invalid document into the users collection, and how to handle previously valid documents that are no longer valid as a result of changes to the validation rules.

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

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

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.

←  View Existing Validation RulesSpecify Validation Level for Existing Documents →
Share Feedback
© 2023 MongoDB, Inc.

About

  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2023 MongoDB, Inc.