Schema Validation架构校验

Validation on Existing Documents现有文件的验证

To perform validation checks on existing documents, use the validate command or the db.collection.validate() shell helper.要对现有文档执行验证检查，请使用validate命令或db.collection.validate()shell助手。

The validationLevel option determines which operations MongoDB applies the validation rules:validationLevel选项确定MongoDB应用验证规则的操作：

• If the validationLevel is strict (the default), MongoDB applies validation rules to all inserts and updates.如果validationLevel是strict（默认），MongoDB将验证规则应用于所有插入和更新。
• If the validationLevel is moderate, MongoDB applies validation rules to inserts and to updates to existing documents that already fulfill the validation criteria. 如果validationLevel为moderate，MongoDB将验证规则应用于已满足验证标准的现有文档的插入和更新。With the moderate level, updates to existing documents that do not fulfill the validation criteria are not checked for validity.对于moderate级别，不检查不符合验证标准的现有文档更新的有效性。

For example, create a contacts collection with the following documents:例如，使用以下文档创建contacts集合：

db.contacts.insertMany([
   { "_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:发出以下命令将验证程序添加到contacts集合：

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

The contacts collection now has a validator with the moderate validationLevel:contacts集合现在有一个具有moderate验证级别的验证器：

• If you attempted to update the document with _id: 1, MongoDB would apply the new validation rules since the existing document matches the criteria.如果您尝试使用_id:1更新文档，MongoDB将应用新的验证规则，因为现有文档符合条件。
• In contrast, MongoDB will not apply validation rules to updates to the document with _id: 2 as it does not meet the validation rules.相反，MongoDB不会将验证规则应用于_id:2文档的更新，因为它不符合验证规则。

Starting in MongoDB version 5.0, the validator returns detailed error information when a validation condition isn't met. 从MongoDB 5.0版开始，当不满足验证条件时，验证器返回详细的错误信息。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.在下一个示例中，两个更新都不符合我们在上面创建的验证规则，该规则要求name为字符串。

db.contacts.updateOne(
   { _id: 1 },
   { $set: { name: 10 } }
)
db.contacts.updateOne(
   { _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. 下面的输出显示_id:1的文档验证失败，并给出了详细解释，如errInfo对象所示。The update succeeds for the document with _id: 2 since this document did not meet the initial criteria when validation was added.对于_id:2的文档，更新成功，因为添加验证时该文档不符合初始条件。

// _id: 1
MongoServerError: Document failed validation
Additional information: {
failingDocumentId: 1,
details: {
   operatorName: '$jsonSchema',
   schemaRulesNotSatisfied: [
      {
      operatorName: 'properties',
      propertiesNotSatisfied: [
         {
            propertyName: 'name',
            description: 'name must be a string and is required',
            details: [
            {
               operatorName: 'bsonType',
               specifiedAs: { bsonType: 'string' },
               reason: 'type did not match',
               consideredValue: 10,
               consideredType: 'int'
            }
            ]
         }
      ]
      }
   ]
}
}
// _id: 2
{
   acknowledged: true,
   insertedId: null,
   matchedCount: 1,
   modifiedCount: 0,
   upsertedCount: 0
}

To disable validation entirely, you can set validationLevel to off.要完全禁用验证，可以将validationLevel设置为off。

Accept or Reject Invalid Documents接受或拒绝无效文件

The validationAction option determines how MongoDB handles documents that violate the validation rules:validationAction选项确定MongoDB如何处理违反验证规则的文档：

• If the validationAction is error (the default), MongoDB rejects any insert or update that violates the validation criteria.如果validationAction为error（默认），MongoDB将拒绝任何违反验证标准的插入或更新。
• If the validationAction is warn, MongoDB logs any violations but allows the insertion or update to proceed.如果validationAction为warn，MongoDB将记录任何违规行为，但允许继续插入或更新。

For example, create a contacts2 collection with the following JSON Schema validator:例如，使用以下JSON模式验证器创建contacts2集合：

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

For example, the following insert operation violates the validation rule:例如，以下插入操作违反了验证规则：

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

However, since the validationAction is warn, MongoDB only logs the validation violation message and allows the operation to proceed. Run the following command to view the MongoDB logs:但是，由于validationAction是warn，MongoDB只记录验证违规消息并允许操作继续。运行以下命令查看MongoDB日志：

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\"]}]}}}}"

Use Title and Description Fields to Clarify Validation Rules使用标题和描述字段来澄清验证规则

Starting in MongoDB 5.1, when a document fails schema validation, MongoDB includes the validation title and description in the error response. 从MongoDB 5.1开始，当文档未能通过模式验证时，MongoDB会在错误响应中包含验证title和description。You can use these fields to provide a clearer explanation of the validation when the rules are not immediately clear, such as when using regular expressions.当规则不立即明确时，例如使用正则表达式时，您可以使用这些字段来更清楚地解释验证。

Consider a users collection with the following schema validation:考虑具有以下架构验证的users集合：

db.runCommand( {
   collMod: "users",
   validator: { $jsonSchema: {
      bsonType: "object",
      title: "Email validation",
      properties: {
         email: {
            "bsonType": "string",
            "pattern": "^@mongodb\.com$",
            "description": "Email address must end with '@mongodb.com'"
         },
      }
   } },
   validationLevel: "moderate"
} )

The pattern field indicates that all email fields must end with @mongodb.com. pattern字段表示所有email字段必须以@mongodb.com结尾。If you try to insert a document that does not match the pattern, MongoDB includes the validation title and description in the error output:如果您尝试插入与模式不匹配的文档，MongoDB会在错误输出中包含验证title和description：

Input:

db.users.insertOne( { "name": "Amelia Morrison", "email": "a.morrison@nwsueicn.com" } )

Output:输出：

MongoServerError: Document failed validation
Additional information: {
  failingDocumentId: ObjectId("614a10bab93bbd15dd2e2eb6"),
  details: {
    operatorName: '$jsonSchema',
    title: 'Email validation',
    schemaRulesNotSatisfied: [
      {
        operatorName: 'properties',
        propertiesNotSatisfied: [
          {
            propertyName: 'email',
            description: "Email address must end with '@mongodb.com'",
            details: [
              {
                operatorName: 'pattern',
                specifiedAs: { pattern: '^@mongodb.com$' },
                reason: 'regular expression did not match',
                consideredValue: 'a.morrison@nwsueicn.com'
              }
            ]
          }
        ]
      }
    ]
  }
}