Schema Validation

Existing Documents

The validationLevel option determines which operations MongoDB applies the validation rules:

• If the validationLevel is strict (the default), MongoDB applies validation rules to all inserts and updates.

• If the validationLevel is moderate, MongoDB applies validation rules to inserts and to updates to existing documents that already fulfill the validation criteria. With the moderate level, updates to existing documents that do not fulfill the validation criteria are not checked for validity.

For example, create a contacts collection with the following documents:

db.contacts.insert([
   { "_id": 1, "name": "Anne", "phone": "+1 555 123 456", "city": "London", "status": "Complete" },
   { "_id": 2, "name": "Ivan", "city": "Vancouver" }
])

Issue the following command to add a validator to the contacts collection:

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

The contacts collection now has a validator with the moderate validationLevel:

• If you attempted to update the document with _id: 1, MongoDB would apply the new validation rules since the existing document matches the criteria.

• In contrast, MongoDB will not apply validation rules to updates to the document with _id: 2 as it does not meet the validation rules.

Starting in MongoDB version 5.0, the validator returns detailed error information when a validation condition isn't met. The error output is exhaustive - all errors are reported, not just the first one.

In the next example, neither of the updates is consistent with the validation rule we created above that requires name to be a string.

db.contacts.update(
   { _id: 1 },
   { $set: { name: 10 } }
)
db.contacts.update(
   { _id: 2 },
   { $set: { name: 20 } }
)

The output below shows that the document with _id: 1 fails validation with a detailed explanation, as shown in the errInfo object. The update succeeds for the document with _id: 2 since this document did not meet the initial criteria when validation was added.

// _id: 1
WriteResult({
  "nMatched" : 0,
  "nUpserted" : 0,
  "nModified" : 0,
  "writeError" : {
    "code" : 121,
    "errmsg" : "Document failed validation",
    "errInfo" : {
       "failingDocumentId" : 1,
       "details" : {
         "operatorName" : "$jsonSchema",
         "schemaRulesNotSatisfied" : [
         {
           "operatorName" : "properties",
           "propertiesNotSatisfied" : [
              {
              "propertyName" : "name",
              "details" : [
                  {
                    "operatorName" : "bsonType",
                    "specifiedAs" : {
                       "bsonType" : "string"
                        },
                    "reason" : "type did not match",
                    "consideredValue" : 10,
                    "consideredType" : "double"
                  }
                 ]
               }
             ]
           }
         ]
      }
     }
   }
})
// _id: 2
WriteResult({ "nMatched" : 1, "nUpserted" : 0, "nModified" : 1 })

To disable validation entirely, you can set validationLevel to off.

Accept or Reject Invalid Documents

The validationAction option determines how MongoDB handles documents that violate the validation rules:

• If the validationAction is error (the default), MongoDB rejects any insert or update that violates the validation criteria.

• If the validationAction is warn, MongoDB logs any violations but allows the insertion or update to proceed.

For example, create a contacts2 collection with the following JSON Schema validator:

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 match the regular expression pattern"
         },
         status: {
            enum: [ "Unknown", "Incomplete" ],
            description: "can only be one of the enum values"
         }
      }
   } },
   validationAction: "warn"
} )

With the warn validationAction, MongoDB logs any violations but allows the insertion or update to proceed.

For example, the following insert operation violates the validation rule:

db.contacts2.insertOne( { name: "Amanda", status: "Updated" } )

However, since the validationAction is warn only, MongoDB only logs the validation violation message and allows the operation to proceed. Run the following command to view the MongoDB logs:

db.adminCommand( { getLog: "global" } )

Depending on collection usage, this command might return a lot of data. The validation error (one long line in the log, reformatted here for readability) contains information like this:

"{\"t\":{\"$date\":\"2021-01-20T15:59:57.305+00:00\"},
 \"s\":\"W\",
 \"c\":\"STORAGE\",
 \"id\":20294,
 \"ctx\":\"conn1\",
 \"msg\":\"Document would fail validation\",
 \"attr\":{\"namespace\":\"test.contacts2\",
   \"document\":{\"_id\":{\"$oid\":\"6008537d42e0d23385568881\"},
         \"name\":\"Amanda\",
         \"status\":\"Updated\"},
    \"errInfo\":{\"failingDocumentId\":{\"$oid\":\"6008537d42e0d23385568881\"},
         \"details\":{\"operatorName\":\"$jsonSchema\",
              \"schemaRulesNotSatisfied\":[
                  {\"operatorName\":\"properties\",
                    \"propertiesNotSatisfied\":[
                        {\"propertyName\":\"status\",
                         \"details\":[
                              {\"operatorName\":\"enum\",
                               \"specifiedAs\":{\"enum\":[
                                    \"Unknown\",
                                    \"Incomplete\"]},
                          \"reason\":\"value was not found in enum\",
                          \"consideredValue\":\"Updated\"}]}]},
 {\"operatorName\":\"required\",
 \"specifiedAs\":{\"required\":[\"phone\"]},
     \"missingProperties\":[\"phone\"]}]}}}}"