$jsonSchema

Definition

• $jsonSchema

New in version 3.6.

The $jsonSchema operator matches documents that satisfythe specified JSON Schema.

The $jsonSchema operator expression has the following syntax:

{ $jsonSchema: <JSON Schema object> }

Where the JSON Schema object is formatted according to draft 4 ofthe JSON Schema standard.

{ <keyword1>: <value1>, ... }

For example:

{
  $jsonSchema: {
     required: [ "name", "major", "gpa", "address" ],
     properties: {
        name: {
           bsonType: "string",
           description: "must be a string and is required"
        },
        address: {
           bsonType: "object",
           required: [ "zipcode" ],
           properties: {
               "street": { bsonType: "string" },
               "zipcode": { bsonType: "string" }
           }
        }
     }
  }
}

For a list of keywords supported by MongoDB, see Available Keywords.

Note

MongoDB supports draft 4 of JSON Schema, including corespecification andvalidation specification,with some differences. See Extensions andOmissions for details.

For more information about JSON Schema, see theofficial website.

Behavior

Feature Compatibility

The featureCompatibilityVersion must be set to"3.6" or higher in order to use $jsonSchema.

Document Validator

You can use $jsonSchema in a document validator to enforce thespecified schema on insert and update operations:

db.createCollection( <collection>, { validator: { $jsonSchema: <schema> } } )
db.runCommand( { collMod: <collection>, validator:{ $jsonSchema: <schema> } } )

Query Conditions

You can use $jsonSchema in query conditions for read and writeoperations to find documents in the collection that satisfy the specifiedschema:

db.collection.find( { $jsonSchema: <schema> } )
db.collection.aggregate( [ { $match: { $jsonSchema: <schema> } } ] )
db.collection.updateMany( { $jsonSchema: <schema> }, <update> )
db.collection.deleteOne( { $jsonSchema: <schema> } )

To find documents in the collection that do not satisfy the specifiedschema, use the $jsonSchema expression in a $norexpression. For example:

db.collection.find( { $nor: [ { $jsonSchema: <schema> } ] } )
db.collection.aggregate( [ { $match: { $nor: [ { $jsonSchema: <schema> } ] } }, ... ] )
db.collection.updateMany( { $nor: [ { $jsonSchema: <schema> } ] }, <update> )
db.collection.deleteOne( { $nor: [ { $jsonSchema: <schema> } ] } )

Examples

Schema Validation

The following db.createCollection() method creates acollection named students and uses the $jsonSchemaoperator to set schema validation rules:

db.createCollection("students", {
   validator: {
      $jsonSchema: {
         bsonType: "object",
         required: [ "name", "year", "major", "address" ],
         properties: {
            name: {
               bsonType: "string",
               description: "must be a string and is required"
            },
            year: {
               bsonType: "int",
               minimum: 2017,
               maximum: 3017,
               description: "must be an integer in [ 2017, 3017 ] and is required"
            },
            major: {
               enum: [ "Math", "English", "Computer Science", "History", null ],
               description: "can only be one of the enum values and is required"
            },
            gpa: {
               bsonType: [ "double" ],
               description: "must be a double if the field exists"
            },
            address: {
               bsonType: "object",
               required: [ "city" ],
               properties: {
                  street: {
                     bsonType: "string",
                     description: "must be a string if the field exists"
                  },
                  city: {
                     bsonType: "string",
                     "description": "must be a string and is required"
                  }
               }
            }
         }
      }
   }
})

Given the created validator for the collection, the following insertoperation will fail because gpa is an integer when the validatorrequires a double.

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

The operation returns the following error:

WriteResult({
   "nInserted" : 0,
   "writeError" : {
      "code" : 121,
      "errmsg" : "Document failed validation"
   }
})

After changing the gpa to a double, the insert succeeds:

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

The operation returns the following:

WriteResult({ "nInserted" : 1 })

Query Conditions

You can use $jsonSchema in query conditions for read and writeoperations to find documents in the collection that satisfy the specifiedschema.

For example, create a sample collection inventory with thefollowing documents:

db.inventory.insertMany([
   { item: "journal", qty: NumberInt(25), size: { h: 14, w: 21, uom: "cm" }, instock: true },
   { item: "notebook", qty: NumberInt(50), size: { h: 8.5, w: 11, uom: "in" }, instock: true },
   { item: "paper", qty: NumberInt(100), size: { h: 8.5, w: 11, uom: "in" }, instock: 1 },
   { item: "planner", qty: NumberInt(75), size: { h: 22.85, w: 30, uom: "cm" }, instock: 1 },
   { item: "postcard", qty: NumberInt(45), size: { h: 10, w: 15.25, uom: "cm" }, instock: true },
   { item: "apple", qty: NumberInt(45), status: "A", instock: true },
   { item: "pears", qty: NumberInt(50), status: "A", instock: true }
])

Next, define the following sample schema object:

let myschema =  {
      required: [ "item", "qty", "instock" ],
      properties: {
         item: { bsonType: "string" },
         qty: { bsonType: "int" },
         size: {
            bsonType: "object",
            required: [ "uom" ],
            properties: {
               uom: { bsonType: "string" },
               h: { bsonType: "double" },
               w: { bsonType: "double" }
            }
          },
          instock: { bsonType: "bool" }
      }
 }

You can use $jsonSchema to find all documents in thecollection that satisfy the schema:

db.inventory.find( { $jsonSchema: myschema } )
db.inventory.aggregate( [ { $match: { $jsonSchema: myschema } } ] )

You can use $jsonSchema with the $nor to find alldocuments that do not satisfy the schema:

db.inventory.find( { $nor: [ { $jsonSchema: myschema } ] } )

Or, you can update all documents that do not satisfy the schema:

db.inventory.updateMany( { $nor: [ { $jsonSchema: myschema } ] }, { $set: { isValid: false } } )

Or, you can delete all documents that do not satisfy the schema:

db.inventory.deleteMany( { $nor: [ { $jsonSchema: myschema } ] } )

JSON Schema

MongoDB supports draft 4 of JSON Schema, includingcore specificationand validation specification,with some differences. See Extensions and Omissions for details.

For more information about JSON Schema, see theofficial website.

Available Keywords

Note

MongoDB implements a subset of keywords available in JSON Schema.For a complete list of omissions, see Omissions.

Extensions

MongoDB’s implementation of JSON Schema includes the addition of the bsonTypekeyword, which allows you to use all BSON types in the$jsonSchema operator. bsonType accepts the same string aliases usedfor the $type operator.

Omissions

The following are not supported in MongoDB’s implementation of JSON Schema:

• Hypertext definitionsin draft 4 of the JSON Schema spec.
• The keywords:
  • $ref
  • $schema
  • default
  • definitions
  • format
  • id
• The integer type. You must use the BSON type int or longwith the bsonType keyword.
• Hypermedia and linking properties of JSON Schema, including the use ofJSON References and JSON Pointers.
• Unknown keywords.