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

Choose How to Handle Invalid Documents

On this page

  • Context
  • Option 1: Reject Invalid Documents
  • Option 2: Allow Invalid Documents, but Record Them in the Log
  • Learn More

You can specify how MongoDB handles documents that violate violation rules. When an operation would result in an invalid document, MongoDB can either:

  • Reject any insert or update that violates the validation criteria. This is the default behavior.

  • Allow the operation to proceed, but record the violation in the MongoDB log.

Rejecting invalid documents ensures that your schema stays consistent. However, in certain scenarios you may want to allow invalid documents, such as a data migration containing documents from before a schema was established.

Context

Your schema's validationAction option determines how MongoDB handles invalid documents:

Validation Action
Behavior
error
(Default) MongoDB rejects any insert or update that violates the validation criteria.
warn
MongoDB allows the operation to proceed, but records the violation in the MongoDB log.

Option 1: Reject Invalid Documents

The following procedure shows how to create a schema validation that rejects invalid documents.

1

Create a collection with validationAction: "error".

Create a contacts collection with a JSON schema validator that has validationAction: "error":

db.createCollection( "contacts", {
   validator: { $jsonSchema: {
      bsonType: "object",
      required: [ "phone" ],
      properties: {
         phone: {
            bsonType: "string",
            description: "must be a string and is required"
         },
         email: {
            bsonType : "string",
            pattern : "@mongodb\\.com$",
            description: "must be a string and end with '@mongodb.com'"
         }
      }
   } },
   validationAction: "error"
} )

The error validationAction causes MongoDB to reject any invalid documents and prevent them from being inserted into the collection.

2

Attempt to insert an invalid document.

Attempt to insert the following document:

db.contacts.insertOne(
   { name: "Amanda", email: "amanda@xyz.com" }
)

The document violates the validation rule because:

  • The email field does not match the regular expression pattern. The email field must end in @mongodb.com.

  • It is missing the required phone field.

The operation fails with the following error:

MongoServerError: Document failed validation
Additional information: {
  failingDocumentId: ObjectId("6377cca4aac957f2b77ea955"),
  details: {
    operatorName: '$jsonSchema',
    schemaRulesNotSatisfied: [
      {
        operatorName: 'properties',
        propertiesNotSatisfied: [
          {
            propertyName: 'email',
            description: "must be a string and end with '@mongodb.com'",
            details: [
              {
                operatorName: 'pattern',
                specifiedAs: { pattern: '@mongodb\\.com$' },
                reason: 'regular expression did not match',
                consideredValue: 'amanda@xyz.com'
              }
            ]
          }
        ]
      },
      {
        operatorName: 'required',
        specifiedAs: { required: [ 'phone' ] },
        missingProperties: [ 'phone' ]
      }
    ]
  }
}

Option 2: Allow Invalid Documents, but Record Them in the Log

The following procedure shows how to create a schema validation that allows invalid documents, but records invalid documents in the MongoDB log.

1

Create a collection with validationAction: "warn".

Create a contacts2 collection with a JSON schema validator that has validationAction: "warn":

db.createCollection( "contacts2", {
   validator: { $jsonSchema: {
      bsonType: "object",
      required: [ "phone" ],
      properties: {
         phone: {
            bsonType: "string",
            description: "must be a string and is required"
         },
         email: {
            bsonType : "string",
            pattern : "@mongodb\\.com$",
            description: "must be a string and end with '@mongodb.com'"
         }
      }
   } },
   validationAction: "warn"
} )

The warn validationAction allows invalid documents to be inserted into the collection. Invalid documents are recorded in the MongoDB log.

2

Attempt to insert an invalid document.

Attempt to insert the following document:

db.contacts2.insertOne(
   { name: "Amanda", email: "amanda@xyz.com" }
)

The document violates the validation rule because:

  • The email field does not match the regular expression pattern. The email field must end in @mongodb.com.

  • It is missing the required phone field.

3

Check the logs for the invalid document.

To view the MongoDB logs in a readable format, run the following command:

db.adminCommand(
   { getLog:'global'} ).log.forEach(x => { print(x) }
)

The MongoDB log includes an entry similar to the following object:

{
   "t": {
      "$date": "2022-11-18T13:30:43.607-05:00"
   },
   "s": "W",
   "c": "STORAGE",
   "id": 20294,
   "ctx": "conn2",
   "msg": "Document would fail validation",
   "attr": {
      "namespace": "test.contacts2",
      "document": {
         "_id": {
            "$oid": "6377cf53d59841355cac1cd0"
         },
         "name": "Amanda",
         "email": "amanda@xyz.com"
      },
      "errInfo": {
         "failingDocumentId": {
            "$oid": "6377cf53d59841355cac1cd0"
         },
         "details": {
            "operatorName": "$jsonSchema",
            "schemaRulesNotSatisfied": [{
               "operatorName": "properties",
               "propertiesNotSatisfied": [{
                  "propertyName": "email",
                  "description": "must be a string and end with '@mongodb.com'",
                  "details": [{
                     "operatorName": "pattern",
                     "specifiedAs": {
                        "pattern": "@mongodb\\.com$"
                     },
                     "reason": "regular expression did not match",
                     "consideredValue": "amanda@xyz.com"
                  }]
               }]
            }, {
               "operatorName": "required",
               "specifiedAs": {
                  "required": ["phone"]
               },
               "missingProperties": ["phone"]
            }]
         }
      }
   }
}

Learn More

  • Log Messages

  • Specify Validation Level for Existing Documents

Back

Specify Validation Level for Existing Documents