/ /

/ /

Specify JSON Schema Validation

JSON Schema is a vocabulary that lets you annotate and validate JSON documents. Use JSON Schema to specify validation rules for your fields in a human-readable format.

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.

Connect to your MongoDB deployment.

To connect to a local MongoDB instance or MongoDB Atlas deployment using mongosh, see Connect to a Deployment or Connect via mongosh.

Create a collection with validation.

In mongosh, run the following command to create a students collection and use the $jsonSchema operator to set schema validation rules:

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

Use title and description fields to explain validation rules that aren't immediately clear. When a document fails validation, MongoDB includes these fields in the error output.

Confirm that the validation prevents invalid documents.

Run the following command. The 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"
   }
} )

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'
              }
            ]
          }
        ]
      }
    ]
  }
}

Tip

By default, mongosh prints nested objects up to six levels deep. To print all nested objects to their full depth, set inspectDepth to Infinity.

config.set("inspectDepth", Infinity)

Insert a valid document.

If you change the gpa field value to a double type, the insert operation succeeds. Run the following command to insert the valid document:

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

Query for the valid document.

To confirm that you've successfully inserted the document, run the following command to query the students collection:

db.students.find()

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

Tip

If you're connected to an Atlas deployment, you can also view and filter for the document in the Atlas UI.

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.

Back

Schema Validation

Specify Field Values

Context

Restrictions

Steps

Connect to your MongoDB deployment.

Create a collection with validation.

Tip

Clarify Rules with Title and Description Fields

Confirm that the validation prevents invalid documents.

Tip

Insert a valid document.

Query for the valid document.

Tip

Additional Information

Learn More

Earn a Skill Badge