{"id":103508,"date":"2024-08-21T08:26:00","date_gmt":"2024-08-21T08:26:00","guid":{"rendered":"https:\/\/www.red-gate.com\/simple-talk\/?p=103508"},"modified":"2024-11-14T22:03:23","modified_gmt":"2024-11-14T22:03:23","slug":"introducing-schema-validation-in-mongodb","status":"publish","type":"post","link":"https:\/\/www.red-gate.com\/simple-talk\/featured\/introducing-schema-validation-in-mongodb\/","title":{"rendered":"Introducing Schema Validation in MongoDB"},"content":{"rendered":"

This article is part of Robert Sheldon's continuing series on Mongo DB. To see all of the items in the series, click here<\/a>.<\/strong><\/p>\n\n

Similar to other NoSQL database systems, MongoDB is known for its flexible and variable schema models, unlike relational database systems in which well-defined schemas are essential to ensuring data integrity. In MongoDB, you can add documents to a collection that contain different fields or that include the same fields but with different data types or value ranges. You can even add documents that are completely unrelated. As long as you use proper Binary JSON (BSON) formatting, just about anything goes.<\/p>\n

In some cases, however, this flexibility can get to be a little too much, and you might want to impose restrictions on a collection\u2019s documents. In this way, you can better control how data is stored and presented so your applications experience the data in a consistent and reliable manner. For example, you might want to ensure that all documents added to a collection include the name<\/code> field and that the field always takes a string<\/code> value.<\/p>\n

You can impose such restrictions on a collection\u2019s documents by defining schema validation rules that specify the acceptable fields and their values. MongoDB\u2019s validation capabilities are flexible and simple to implement and can be easily modified when needed. You can also create rules at a very granular level, even if it\u2019s only a single field value. MongoDB applies the rules to new documents as they\u2019re inserted into the collection and to existing documents when they\u2019re updated. If a document violates those rules, MongoDB rejects the operation.<\/p>\n

In this article, I demonstrate how to define validation rules on a collection. The article provides multiple examples of schema definitions that contain different types of validation rules. This is the first of two articles on schema validation. By the end of this article, you should have a good sense of how validation rules work and how to add them to your collections.<\/p>\n

Note: For the examples in this article, I used the same MongoDB Atlas and MongoDB Compass environments I used for the previous articles in this series. Refer to the first article for more specifics about setting up these environments.<\/p>\n

Introducing the JSON Schema object<\/h2>\n

You can use a MongoDB Shell command to define schema validation on a collection. You can also use the GUI features in MongoDB Compass, but you still need to understand how to build the validation rules themselves, and MongoDB Shell is a good place to start.<\/p>\n

When adding schema validation to a collection, you must use the validator<\/code> method to create a JSON Schema object, which defines the validation rules. As part of this process, you must also use the $jsonSchema<\/code> operator to build the actual rules.<\/p>\n

You can define the JSON Schema object when you first add your collection to the database or after the collection already exists. In either case, the format you use for invoking the validator<\/code> method is the same. The following syntax shows this format, which starts with calling the validator<\/code> method:<\/p>\n

validator: { $jsonSchema: { <JSON Schema object> } }<\/pre>\n
As the syntax shows, you pass the $jsonSchema<\/code> operator in as an argument to the validator<\/code> method. The $jsonSchema<\/code> operator, which is enclosed in curly brackets, defines the JSON Schema object, which is also enclosed in curly brackets.<\/p>\n
The schema object itself is based on draft 4 of the JSON Schema standard<\/a>. MongoDB omits several elements from the standard, while also extending it to support MongoDB\u2019s BSON data types. A full explanation of the JSON Schema standard and its implementation in MongoDB is beyond the scope of this article, but you can find more information about how MongoDB implements the JSON Schema in the MongoDB topic $jsonSchema<\/a>.<\/p>\n
A good way to learn how to define validation rules is to see them in action. To this end, I\u2019ve created a series of examples that demonstrate the core components that go into a collection\u2019s schema validation object. The examples use the hr<\/code> database and candidates<\/code> collection, but you can use any database or collection, preferably one that\u2019s empty and not deployed to a production environment.<\/p>\n
If you want to try out these examples yourself, I recommend that you stick with the hr<\/code> database and candidates<\/code> collection to keep things simple. At this point in the series, you should have no trouble creating a database and collection. Refer to previous articles in this series if necessary.<\/p>\n
When I created the examples, I used the version of MongoDB Shell that\u2019s embedded in the MongoDB Compass GUI. I like this version of Shell because I can easily verify changes to my documents by viewing them in the Compass GUI. That said, if you have MongoDB Shell installed on your system, you can instead use your system\u2019s command-line interface (CLI) to try out these examples. The results are the same in either case.<\/p>\n
For this article, I created the examples based on an existing collection (candidates<\/code>), rather than defining them when creating the collection. This approach makes it easier to run through the examples without needing to drop the collection before re-creating it. It also makes it easier to reuse the statement as you refine the rules.<\/p>\n
Adding validation rules to a MongoDB collection<\/h2>\n
To add validation rules to the candidates<\/code> collection, we\u2019ll start by using the runCommand<\/code> database method to call the collMod<\/code> database command. The command let\u2019s us add options to a collection, which in this case, are the validation rules. We\u2019ll use the command to call the validator<\/code> method and, subsequently, the $jsonSchema<\/code> operator, which defines the JSON Schema object. The following example demonstrates how all this works:<\/p>\n
db.runCommand( { collMod: \"candidates\",\n  validator: {\n    $jsonSchema: {\n      bsonType: \"object\",\n      title: \"candidates validation\",\n      required: [ \"name\", \"dob\", \"position\" ],\n      properties: {\n        \"name\": {\n          bsonType: \"string\",\n          description: \"Field required and must be a string.\"\n        },\n        \"dob\": {\n          bsonType: \"date\",\n          description: \"Field required and must be a date.\"\n        },\n        \"position\": {\n          bsonType: \"object\",\n          required: [ \"title\", \"dept\" ],\n          properties: {\n            \"title\": {\n              bsonType: \"string\",\n              description: \"Field required and must be a string.\" \n            },\n            \"dept\": { \n              bsonType: \"string\",\n              enum: [ \"R&D\", \"Marketing\", \"IT\", \"HR\", \"Finance\" ],\n              description: \"Field required and must be one of the specified values.\" \n            },\n            \"skills\": { \n              bsonType: \"array\",\n              description: \"Field must be an array, if included.\"\n            },\n            \"yrs_exp\": { \n              bsonType: \"int\",\n              minimum: 3,\n              description: \"Field must be an int greater than 4, if included.\"\n            }\n          }\n        }\n      }\n    }\n  }\n});<\/pre>\n
The entire statement is passed into MongoDB Shell as a single command. As noted earlier, the command adds the validation rules to an existing collection (candidates<\/code>). If you want to add the rules when creating the collection, you must include the validator<\/code> object as an argument to the createCollection<\/code> method. The MongoDB topic Specify JSON Schema Validation<\/a> shows an example of how this is done.<\/p>\n
Returning to the example above, the first three lines of the command are fairly standard when defining validation rules:<\/p>\n
    \n
  1. Invoke the runCommand<\/code> method on the database object associated with the hr<\/code> database. The method runs the collMod<\/code> database command. The command\u2019s first argument is the candidates<\/code> collection.<\/li>\n
  2. Specify the validator<\/code> method as the second argument to the collMod<\/code> command.<\/li>\n
  3. Specify the $jsonSchema<\/code> operator as an argument to the validator<\/code> method.<\/li>\n<\/ol>\n
    The remaining code, enclosed in curly brackets, defines the JSON Schema object that is returned by the $jsonSchema<\/code> operator. A JSON Schema object is essentially a JSON document. Each line is a schema element that contains a keyword, followed by a value, much like a JSON document in which each field is followed by the field value. The elements are organized hierarchically. In this case, the following four elements at the top of the hierarchy:<\/p>\n