Docs Home → Develop Applications → MongoDB Manual

Specify JSON Schema Validation指定JSON架构验证

On this page本页内容

JSON Schema is a vocabulary that allows you to annotate and validate JSON documents. JSON模式是一个词汇表，允许您注释和验证JSON文档。You can use JSON schema to specify validation rules for your fields in a human-readable format.您可以使用JSON模式以人类可读的格式为字段指定验证规则。

Context上下文

MongoDB supports draft 4 of JSON Schema, including core specification and validation specification, with some differences. MongoDB支持JSON模式的草案4，包括核心规范和验证规范，但存在一些差异。For details, see Extensions and Omissions.有关详细信息，请参阅扩展和省略。

For more information about JSON Schema, see the official website.有关JSON模式的更多信息，请参阅官方网站。

Restrictions限制

You can't specify schema validation for:不能为以下项指定架构验证：

Steps步骤

In this example, you create a students collection with validation rules and observe the results after you attempt to insert an invalid document.在本例中，您使用验证规则创建students集合，并在尝试插入无效文档后观察结果。

1

Create a collection with validation.创建带有验证的集合。

Create a students collection and use the $jsonSchema operator to set schema validation rules. 创建一个students集合，并使用$jsonSchema运算符设置模式验证规则。For Example:例如：

db.createCollection("students", {
   validator: {
      $jsonSchema: {
         bsonType: "object",
         title: "Student Object Validation",
         required: [ "address", "major", "name", "year" ],
         properties: {
            name: {
               bsonType: "string",
               description: "'name' must be a string and is required"
            },
            year: {
               bsonType: "int",
               minimum: 2017,
               maximum: 3017,
               description: "'year' must be an integer in [ 2017, 3017 ] and is required"
            },
            gpa: {
               bsonType: [ "double" ],
               description: "'gpa' must be a double if the field exists"
            }
         }
      }
   }
} )
Tip提示

Clarify Rules with Title and Description Fields用标题和描述字段澄清规则

You can use title and description fields to provide an explanation of validation rules when the rules are not immediately clear. 当规则未立即清除时，您可以使用title和description字段提供验证规则的解释。When a document fails validation, MongoDB includes these fields in the error output.当文档验证失败时，MongoDB会在错误输出中包含这些字段。

2

Confirm that the validation prevents invalid documents.确认验证可防止无效文档。

The following insert operation fails because gpa is an integer when the validator requires a double.以下插入操作失败，因为当validator需要double时，gpa是整数。

db.students.insertOne( {
   name: "Alice",
   year: Int32( 2019 ),
   major: "History",
   gpa: Int32(3),
   address: {
      city: "NYC",
      street: "33rd Street"
   }
} )

The operation returns this error:操作返回此错误：

MongoServerError: Document failed validation


Additional information: {
  failingDocumentId: ObjectId("630d093a931191850b40d0a9"),
  details: {
    operatorName: '$jsonSchema',
    title: 'Student Object Validation',
    schemaRulesNotSatisfied: [
      {
        operatorName: 'properties',
        propertiesNotSatisfied: [
          {
            propertyName: 'gpa',
            description: "'gpa' must be a double if the field exists",
            details: [
              {
                operatorName: 'bsonType',
                specifiedAs: { bsonType: [ 'double' ] },
                reason: 'type did not match',
                consideredValue: 3,
                consideredType: 'int'
              }
            ]
          }
        ]
      }
    ]
  }
}
3

Insert a valid document.插入有效文档。

The insert succeeds after you change the gpa field to a double:将gpa字段更改为double后，插入成功：

db.students.insertOne( {
   name: "Alice",
   year: NumberInt(2019),
   major: "History",
   gpa: Double(3.0),
   address: {
      city: "NYC",
      street: "33rd Street"
   }
} )
4

Query for the valid document.查询有效文档。

To confirm that the document was successfully inserted, query the students collection:要确认文档已成功插入，请查询students集合：

db.students.find()

MongoDB returns the inserted document:MongoDB返回插入的文档：

[
  {
    _id: ObjectId("62bb413014b92d148400f7a5"),
    name: 'Alice',
    year: 2019,
    major: 'History',
    gpa: 3,
    address: { city: 'NYC', street: '33rd Street' }
  }
]

Additional Information其他信息

You can combine JSON Schema validation with query operator validation.您可以将JSON模式验证与查询运算符验证相结合。

For example, consider a sales collection with this schema validation:例如，考虑具有此模式验证的sales集合：

db.createCollection{ "sales", {
  validator: {
    "$and": [
      // Validation with query operators
      {
        "$expr": {
          "$lt": ["$lineItems.discountedPrice", "$lineItems.price"]
        }
      },
      // Validation with JSON Schema
      {
        "$jsonSchema": {
          "properties": {
            "items": { "bsonType": "array" }
          }
        }
      }
    ]
  }
}

The preceding validation enforces these rules for documents in the sales collection:前面的验证对sales集合中的文档强制执行以下规则：

  • lineItems.discountedPrice must be less than lineItems.price. 必须小于lineItems.price。This rule is specified using the $lt operator.此规则使用$lt运算符指定。

  • The items field must be an array. items字段必须是数组。This rule is specified using $jsonSchema此规则使用$jsonSchema指定

Learn More

←  Schema ValidationSpecify Allowed Field Values →