$jsonSchema
On this page
Definition
$jsonSchema
The
$jsonSchema
operator matches documents that satisfy the 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 of the 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 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
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 the
specified 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 write
operations to find documents in the collection that satisfy the specified
schema:
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 specified
schema, use the $jsonSchema
expression in a $nor
expression. 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 a
collection named students
and uses the $jsonSchema
operator 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 insert
operation will fail 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 the following error:
MongoServerError: Document failed validation Additional information: { failingDocumentId: ObjectId("61aa577f666a50a8fccd7ec2"), details: { operatorName: '$jsonSchema', schemaRulesNotSatisfied: [ { operatorName: 'properties', propertiesNotSatisfied: [ { propertyName: 'gpa', description: 'must be a double if the field exists', details: [ [Object] ] } ] } ] } }
After changing the gpa
to a double, the insert succeeds:
db.students.insertOne( { name: "Alice", year: NumberInt(2019), major: "History", gpa: Double(3.0), address: { city: "NYC", street: "33rd Street" } } )
Query Conditions
You can use $jsonSchema
in query conditions for read and write
operations to find documents in the collection that satisfy the specified
schema.
For example, create a sample collection inventory
with the
following 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 the
collection that satisfy the schema:
db.inventory.find( { $jsonSchema: myschema } ) db.inventory.aggregate( [ { $match: { $jsonSchema: myschema } } ] )
You can use $jsonSchema
with the $nor
to find all
documents 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, 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.
Available Keywords
Note
MongoDB implements a subset of keywords available in JSON Schema. For a complete list of omissions, see Omissions.
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". MongoDB's implementation of the JSON Schema does not support the
"integer" type. Use the |
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 Defaults to |
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 are not 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 typeint
orlong
with thebsonType
keyword.Hypermedia and linking properties of JSON Schema, including the use of JSON References and JSON Pointers.
Unknown keywords.