Navigation

$jsonSchema

Definition

$jsonSchema

New in version 3.6: The $jsonSchema operator matches documents that validate against the given JSON Schema.

{ $jsonSchema: <schema> }

Note

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

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

Behavior

$jsonSchema can be used in a document validator, which enforces that inserted or updated documents are valid against the schema. It can also be used to query for documents with the find command or $match aggregation stage.

Warning

featureCompatibilityVersion must be set to "3.6" or higher in order to use $jsonSchema in a document validator. Any such validator must be removed, either by dropping the collection or by using collMod, before downgrading to version 3.4 of the server.

Available Keywords

Keyword Type Definition Behavior
bsonType all types string alias or array of string aliases Accepts same string aliases used for the $type operator
enum all types array of values Enumerates all possible values of the field
type all types string or array of unique strings Enumerates the possible JSON types of the field. Available types are “object”, “array”, “number”, “boolean”, “string”, and “null”.
allOf all types array of JSON Schema objects Field must match all specified schemas
anyOf all types array of JSON Schema objects Field must match at least one of the specified schemas
oneOf all types array of JSON Schema objects Field must match exactly one of the specified schemas
not all types a JSON Schema object Field must not match the schema
multipleOf numbers number Field must be a multiple of this value
maximum numbers number Indicates the maximum value of the field
exclusiveMaximum numbers boolean If true and field is a number, maximum is an exclusive maximum. Otherwise, it is an inclusive maximum.
minimum numbers number Indicates the minimum value of the field
exclusiveMinimum numbers boolean If true, minimum is an exclusive minimum. Otherwise, it is an inclusive minimum.
maxLength strings integer Indicates the maximum length of the field
minLength strings integer Indicates the minimum length of the field
pattern strings string containing a regex Field must match the regular expression
maxProperties objects integer Indicates the field’s maximum number of properties
minProperties objects integer Indicates the field’s minimum number of properties
required objects array of unique strings Object’s property set must contain all the specified elements in the array
additionalProperties objects boolean or object

If true, additional fields are allowed. If false, they are not. If a valid JSON Schema object is specified, additional fields must validate against the schema.

Defaults to true.

properties objects object A valid JSON Schema where each value is also a valid JSON Schema object
patternProperties objects object In addition to properties requirements, each property name of this object must be a valid regular expression
dependencies objects object Describes field or schema dependencies
additionalItems arrays boolean or object If an object, must be a valid JSON Schema
items arrays object or array Must be either a valid JSON Schema, or an array of valid JSON Schemas
maxItems arrays integer Indicates the maximum length of array
minItems arrays integer Indicates the minimum length of array
uniqueItems arrays boolean If true, each item in the array must be unique. Otherwise, no uniqueness constraint is enforced.
title N/A string A descriptive title string with no effect.
description N/A string A string that describes the schema and has no effect.

Extensions

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

Omissions

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

  • Hypertext definitions in 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 long with the bsonType keyword.
  • Hypermedia and linking properties of JSON Schema, including the use of JSON References and JSON Pointers.
  • Unknown keywords.

Examples

Schema Validation

The following db.createCollection() method creates a collection named students and uses the $jsonSchema operator to set multiple rules for the schema design:

db.createCollection("students", {
   validator: {
      $jsonSchema: {
         bsonType: "object",
         required: [ "name", "year", "major", "gpa" ],
         properties: {
            name: {
               bsonType: "string",
               description: "must be a string and is required"
            },
            gender: {
               bsonType: "string",
               description: "must be a string and is not required"
            },
            year: {
               bsonType: "int",
               minimum: 2017,
               maximum: 3017,
               exclusiveMaximum: false,
               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 and is required"
            }
         }
      }
   }
})

Given the created validator for the collection, the following insert operation will fail because gpa is an integer when the validator requires a double.

db.students.insert({
   name: "Alice",
   year: NumberInt(2019),
   major: "History",
   gpa: NumberInt(3)
})

The opration returns the following error:

WriteResult({
   "nInserted" : 0,
   "writeError" : {
      "code" : 121,
      "errmsg" : "Document failed validation"
   }
})
←   $expr $mod  →