Enforce a Document Schema¶

Overview¶

You can control the shape and contents of documents in a collection by defining a document schema. Schemas are regular documents that adhere to the same JSON schema specification as the schema validation built into the core MongoDB server. You can use schemas to control the type of a field's value, require specific fields, and validate changes before committing the results of insert and update operations.

This guide walks through creating a document schema for a collection in a linked MongoDB Atlas cluster.

Note

Data Lakes Do Not Support Schemas

Data Lake data sources do not support rules. You can only access a Data Lake data source in a system function.

Procedure¶

1

Navigate to the Collection Schema Screen¶

You can define the document schema for a collection from the MongoDB rules page in the Realm UI. To get to the rules page, click Rules beneath Data Access in the left navigation menu. On the Rules page, select the collection for which you want to define the schema from the menu then click the Schema tab.

2

Generate a Schema¶

Realm can sample a subset of documents in the collection and automatically generate a schema for you based on the sample.

To automatically generate a schema, click the Regenerate Schema button. By default, Realm randomly samples up to 1,000 documents from all documents in the collection, but you can configure the number of documents to sample and specify a query to focus the schema on specific documents. To change the number of documents in the sample, specify your desired number in the Generate Schema input box. You may sample up a maximum of 50,000 documents. The process may take up to a minute depending on the number and contents of the sampled documents.

To modify which documents and fields to include in the sample, click Advanced (Optional) and specify a standard MongoDB query, projection, and/or sort filter in the Define a Query input boxes. Use the query and sort filters to sample a specific subset of documents and use the projection filter to sample a specific subset of fields from each document.

When you're satisfied with your sample configuration, click Generate Schema. Realm will immediately begin to sample documents and generate a collection schema based on your configuration.

3

Add Field-Level Schema Definitions¶

The schema for each collection is a single JSON Schema document. The root-level type of each collection schema is a BSON object schema that represents a document in the collection. You can define additional schemas for document fields within the root schema's properties field.

Note

The fields available in a JSON schema object depends on the type of value that the schema defines. See the document schema types reference page for details on all of the available schema types.

Example

A group is using Realm to run a voting app where users aged 13 or older can submit a ranked list of their favorite colors. They store the votes in a MongoDB collection named votes where each document represents a single person's vote. Each vote must include the person's name, age, and an array of their favorite colors. Each color has a rank, name, and a hexCode. The following is a typical document in the votes collection:

{
  "name": "Jane Doe",
  "age": 42,
  "favoriteColors": [
    { "rank": 1, "name": "RebeccaPurple", "hexCode": "#663399" },
    { "rank": 2, "name": "DodgerBlue", "hexCode": "#1E90FF" },
    { "rank": 3, "name": "SeaGreen", "hexCode": "#2E8B57" },
  ]
}

The group can use the following schema to guarantee that the listed constraints are satisfied for each document in the votes collection:

{
  "bsonType": "object",
  "required": ["name", "age", "favoriteColors"],
  "properties": {
    "name": {
      "bsonType": "string"
    },
    "age": {
      "bsonType": "int",
      "minimum": 13,
      "exclusiveMinimum": false
    },
    "favoriteColors": {
      "bsonType": "array",
      "uniqueItems": true,
      "items": {
        "bsonType": "object",
        "properties": {
          "rank": { "bsonType": "int" },
          "name": { "bsonType": "string" },
          "hexCode": {
            "bsonType": "string",
            "pattern": "^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$"
          }
        }
      }
    }
  }
}

4

Add Change Validation Expressions¶

In addition to configuring the content of each field, you can validate changes to documents by defining a validation expression in the validate field of a schema. Validation expressions can use the %%prev and %%prevRoot expansions to access a field or document's values before the insert or update operation occurred.

Example

Consider a collection where the document's owner_id field represents the owner of each document. The business rules for this collection specify that once a document has an owner, the value of owner_id should never change. We can enforce this constraint with the following validation expression that ensures that update operations do not change the owner_id value unless its to assign an owner where there was none previously:

"owner_id": {
  "validate": {
    "%or": [
      { "%%prev": { "%exists": false } },
      { "%%prev": "%%this" }
    ]
  }
}

We could also use the %%prevRoot expansion to create the following equivalent validation expression:

"owner_id": {
  "validate": {
    "%or": [
      { "%%prevRoot.owner_id": { "%exists": false } },
      { "%%prevRoot.owner_id": "%%root.owner_id" }
    ]
  }
}

5

Save the Schema¶

After you have configured the schema, click Save. After saving, Realm immediately begins enforcing the schema for all future queries.

Note

Existing documents that do not match the schema are not automatically updated or validated, so future changes to these documents may cause schema validation failures.

6

Validate Documents Against the Schema¶

Once you have saved the collection schema, you can validate that existing documents in the collection conform to the schema. Realm uses the same approach to sample documents for validation as it does for automatic schema generation.

To validate a collection against its current schema, click the Validate tab and configure the document sample. Just like with schema generation, you can specify the number of documents to sample as well as a MongoDB query filter, and/or sort document to modify which documents and fields Realm includes in the sample.

Once you have configured the sample, click the Run Validation button. Realm will sample documents from the collection and validate each document against the schema. Once the validation is complete, Realm shows a table that lists any validation errors.

Each row of the table represents a specific type of validation error for a particular field and indicates the number of documents that failed to validate in that way.

To see the specific documents that caused a given validation error, click the Copy Query button for that error. This copies a standard MongoDB query that you can use to find the documents in the mongo shell, MongoDB compass, or the Atlas Data Explorer. You can also click the Failed Documents button to download the raw validation data.

Give Feedback

← MongoDB Rules & Schemas Document Schemas →