Docs Menu

Docs Home → Develop Applications → MongoDB Manual

Specify JSON Schema Validation

On this page

  • Context
  • Restrictions
  • Steps
  • Additional Information
  • Learn More

JSON Schema is a vocabulary that allows you to annotate and validate JSON documents. You can 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

Steps

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

1

Create a collection with validation.

Create a students collection and use the $jsonSchema operator to set schema validation rules. 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

←  Schema ValidationSpecify Allowed Field Values →

On this page