Docs Menu

Docs HomeMongoDB 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.

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.

You can't specify schema validation for:

  • Collections in the admin, local, and config databases

  • System collections

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 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

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

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

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

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.

←  Schema ValidationSpecify Allowed Field Values →
Share Feedback
© 2022 MongoDB, Inc.

About

  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2022 MongoDB, Inc.