Docs Menu

JSON Expressions

On this page

  • Overview
  • Expression Syntax
  • Evaluation
  • Expression Composition
  • Embedded Expressions
  • Multi-Field Expressions

A JSON expression is a dynamic EJSON document that you use to define service rules in MongoDB Realm. Realm evaluates expressions to boolean values and uses the result to determine whether or not to allow specific actions.

JSON Expressions use expression variables to represent dynamic, runtime information, such as the logged in user that called an action (%%user) or the arguments that were passed the action (%%args). Each field name in an expression must be an expansion.

Expressions documents have the following general format:

<field1>: <value1|expression1>,
<field2>: <value2|expression2>,

MongoDB Realm evaluates expressions by first replacing expansions with their runtime values and then evaluating each field of the expanded expression document to a boolean expression. If all fields in an expression evaluate to true, the expression also evaluates to true.

Expression fields evaluate based on the following rules:

  • If an expanded field name matches its value, it evaluates to true.
  • If a field's value is an embedded expression, it evaluates to the same value as the embedded expression. See embedded expressions.

If a rule does not explicitly use the %%args or %%root expansion, expression field names default to checking for arguments or document fields of the same name. For example, the expression { "url": "" } defaults to evaluating the value against %%args.url in a service rule and %%root.url in a MongoDB rule.

You can combine multiple expressions to enforce complex and nuanced conditions. There are two ways to compose expressions:

You can embed multiple expression documents in the fields of another expression document to handle complex evaluation logic. MongoDB Realm evaluates expressions depth-first, i.e. it evaluates the most-deeply embedded documents first and works back to the root-level fields.


This expression evaluates to true only if the number provided as the someNumber argument falls in a specific range.

"%%args.someNumber": {
"%and": [
{ "$gt": 0 },
{ "$lte": 42 }

Expressions with multiple fields are analogous to an AND operation on the evaluated value of each field.


This expression evaluates to true only if both the url argument was provided and the body.userId argument matches the id of the user that called the action.

"%%args.url": { "%exists": true },
"%%args.body.userId": ""
Give Feedback
© 2021 MongoDB, Inc.


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