Docs Home → 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支持JSONSchema的草案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. When a document fails validation, MongoDB includes these fields in the error output.

2

Confirm that the validation prevents invalid documents.

The following insert operation fails because gpa is an integer when the validator requires a double.

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:

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:

db.students.find()

MongoDB returns the inserted document:

[
  {
    _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.

For example, consider a sales collection with this schema validation:

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:

  • lineItems.discountedPrice must be less than lineItems.price. This rule is specified using the $lt operator.

  • The items field must be an array. This rule is specified using $jsonSchema.

Learn More了解更多信息