Specify JSON Schema Validation

Context

MongoDB supports draft 4 of JSON Schema, including core specification and validation specification, with some differences. For details, see Extensions and Omissions.

For more information about JSON Schema, see the official website.

Restrictions

You can't specify schema validation for:

• Collections in the admin, local, and config databases

• System collections

If you have Client-Side Field Level Encryption or Queryable Encryption enabled on a collection, validation is subject to the following restrictions:

• For CSFLE, when running collMod, the libmongocrypt library prefers the JSON encryption schema specified in the command. This preference enables setting a schema on a collection that does not yet have one.

• For Queryable Encryption, any JSON schema that includes an encrypted field results in a query analysis error.

Steps

In this example, you create a students collection with validation rules and observe the results after you attempt to insert an invalid document.

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

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

db.students.find()

[
  {
    _id: ...,
    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 uses the $lt operator.

• The items field must be an array. This rule uses $jsonSchema.

Learn More

• For a complete list of allowed JSON Schema keywords, see Available Keywords.

• To restrict what values a certain field can contain, see Specify Allowed Field Values.

• To avoid issues with JSON Schema validation, see Tips for JSON Schema Validation.