Docs Menu

Rule Templates & Examples

On this page

MongoDB Realm determines if a role applies to a given document by evaluating the Apply When expression that you define for each role.

This section contains examples of Apply When expressions for common scenarios.

To apply an expression to a role, find the scenario that most closely matches your use case and then copy and paste the provided template into the role. You may need to modify placeholder values (denoted by <angle brackets>) in the template to match your collection or otherwise adapt the template to fit your needs.

Note

You can also use the Apply When expressions on this page for external services and sync rules.

This expression evaluates to true if the active user's unique id value matches the value of the specified field.

{
"<Owner ID Field>": "%%user.id"
}

This expression evaluates to true if the active user's unique id value matches one or more values in the specified array field.

{
"<Array Field>": "%%user.id"
}

This expression evaluates to true if the active user has any email address listed in their internal user object.

{
"%%user.data.email": { "%exists": true }
}

This expression evaluates to true if the active user's email address matches the specified email address.

{
"%%user.data.email": "<Email Address>"
}

This expression evaluates to true if the active user's email address matches the value of the specified field.

{
"%%root.email": "%%user.data.email"
}

This expression evaluates to true if the active user's email address matches one or more string values in the specified array field.

{
"<Array Field>": "%%user.data.email"
}

This expression evaluates to true if the Function isAuthorizedUser returns true when passed the active user's id value.

Note

You can call any MongoDB Realm Function from a JSON expression using the %function operator.

{
"%%true": {
"%function": {
"name": "isAuthorizedUser",
"arguments": ["%%user.id"]
}
}
}

MongoDB Realm uses a role's permissions configuration to determine if the active user can insert or delete a document as well as which fields in the document they can read and write.

This section contains templates that define role permissions for common scenarios. To apply a set of permissions to a role, find the scenario that most closely matches your use case. Update the role's permissions table to match the provided screenshot or copy and paste the provided template into the collection's advanced mode configuration. Make sure that you modify any placeholder values (denoted by <angle brackets>) in the template to match your needs.

To allow a role to read any field, set the document-level read field to true.

A role with permission to read all document fields
{
"name": "<Role Name>",
"apply_when": <JSON Expression>,
"insert": <boolean>,
"delete": <boolean>,
"read": true,
}

To allow a role to read or write any field, set the document-level write field to true. Document-level writes require read permission, so the role will be able to read all fields.

A role with permission to read and write all document fields
{
"name": "<Role Name>",
"apply_when": <JSON Expression>,
"insert": <boolean>,
"delete": <boolean>,
"write": true,
}

To allow a role to read all fields, set the document-level read field to true. To specify a field that the role can write to, set the write field to true in the field's configuration document, which is embedded in the fields document.

A role with permission to write to specific fields
{
"name": "<Role Name>",
"apply_when": <JSON Expression>,
"insert": <boolean>,
"delete": <boolean>,
"read": true,
"fields": {
"<Field Name>": { "write": true },
...
}
}

To allow a role to read or write any field, set the document-level write field to true. Document-level writes require read permission, so the role will be able to read all fields.

To prevent the role from inserting new documents, set the document-level insert field to false.

A role that lacks permission to insert new documents
A role with permission to read and write all document fields
{
"name": "<Role Name>",
"apply_when": <JSON Expression>,
"insert": false,
"delete": <boolean>,
"write": true,
}

To allow a role to write to any field except for those you specify, set the corresponding field-level write fields to false in the fields document and set the additional_fields.write field to true.

A role with permission to write to some but not all fields
{
"name": "<Role Name>",
"apply_when": <JSON Expression>,
"insert": <boolean>,
"delete": <boolean>,
"read": true,
"fields": {
"<Field Name>": {
"read": true,
"write": false
},
...
},
"additional_fields": { "write": true }
}

The use cases described in this section require you to use advanced functionality that is not supported by the default collection rules editor in the Realm UI. To use this template, convert to advanced mode or import a collection rule configuration with Realm CLI.

To allow a role to insert new documents but otherwise prevent them from reading or modifying any data, set insert to true and set the value of document-level write to a rule expression that evaluates to true only if the document didn't exist prior to the operation.

{
"name": "insertOnly",
"apply_when": <JSON Expression>,
"delete": false,
"insert": true,
"write": {
"%%prevRoot": { "%exists": false }
},
"additional_fields": {}
}
Note

You must specify a JSON expression for write to prevent users from reading data. To insert a document a role must also have write permission for all fields in the document; however, setting write directly to true would also give the role read permission. The JSON expression ensures that the role only has read permission for the initial document insert.

To allow a role to read or write some but not all fields of an embedded document, add embedded documents that match the path of the embedded field to the fields document.

{
"name": "canReadEmbeddedField",
"apply_when": {},
"delete": true,
"insert": true,
"fields": {
"someEmbeddedDocument": {
"fields": {
"someEmbeddedField": {
"read": true,
"write": true
}
}
}
},
"additional_fields": {}
}
Note

MongoDB Realm applies any read and write permissions defined for a given field to all embedded fields that the field contains regardless of any permissions defined for those fields.

Give Feedback
MongoDB logo
© 2021 MongoDB, Inc.

About

  • Careers
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2021 MongoDB, Inc.