Rule Expressions

On this page

Overview

Restrictions
Expression Syntax
Embedded Expressions
Multi-Field Expressions
Expression Evaluation
Expansions
Logical Expansions
Value Expansions
Environment Expansions
Request Expansions
User Expansions
MongoDB Document Expansions
Service Expansions
Operators
Convert EJSON Values
Call a Function
Check Existence
Compare Values

Atlas Device Sync, Data API, and HTTPS Endpoints are deprecated. Refer to the deprecation page for details.

Overview

A rule expression is a JSON object that you write to control data access with permissions. Each expression defines the conditions under which a user can take some action. For example, you can write an expression to control whether a user can read or write data in a MongoDB document or a synced realm.

App Services evaluates a rule expression, usually with a document as input, to get a true or false result.

You can define simple, static expressions that use hardcoded values:

A "static" expression that only evaluates to true if the input document's "id" field matches the given hardcoded ID "aaaabbbbccccddddeeeeffff"

{ "id": "aaaabbbbccccddddeeeeffff" }

You can also write expressions that support arbitrary logic to express dynamic requirements and complex or custom workflows. A dynamic expression can include variables that reflect the current context, called expansions, and can use built-in operators to transform data. The following example evaluates to true if the input document's owner field equals the user's id and the remote IP address of the request can be found in an array of allowed IP addresses that is stored as a value:

A "dynamic" expression that varies based on the requesting user and their IP location

{
  "owner": "%%user.id",
  "%%request.remoteIPAddress": {
    "$in": "%%values.allowedClientIPAddresses"
  }
}

Restrictions

When using Device Sync, expressions have special restrictions. See Sync-Compatible Expressions.

Expression Syntax

An expression is either a boolean value (i.e. true or false) or a JSON object.

Expression object field names can be a value, an expansion, or an operator. Each field must contain one of a value, an expansion, or a nested expression.

Expression objects have the following format:

{
  <Value | Expansion | Operator>: <Value | Expression>,
  ...
}

Embedded Expressions

You can embed multiple expression documents in the fields of another expression document to handle complex evaluation logic. App Services evaluates expressions depth-first, post-order: that is, it starts at the bottom of the expression tree and works back to the root-level fields by evaluating each expression after all of its embedded expressions.

Example

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

Multi-Field Expressions

When you have more than one field in an expression, that expression evaluates to true if and only if every field in the expression evaluates to true. In other words, App Services treats multiple fields in a single expression as an "AND" operation.

Example

This third-party service rule 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": "%%user.id"
}

Expression Evaluation

App Services 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. An empty expression ({}) 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.

Note

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": "https://www.example.com" } defaults to evaluating the value against %%args.url in a service rule and %%root.url in a MongoDB rule.

Expansions

An expansion is a variable that represents a dynamic value in an expression. Expansions are denoted by two percent signs followed by the expansion name. They are:

%%root, which represents the data in a MongoDB document.
%%user, which represents a user interacting with your app.
%%request, which represents an incoming request.
%%values, which represents a static value.
%%environment, which represents your app's environment.
%%args, which represents the arguments that were passed to a service action.

When your app evaluates an expression, it replaces each expansion in the expression with a specific value determined by your app's configuration and the context at the time of evaluation.

Example

The following example uses the %%user and %%root expansions in an "apply when" expression:

"applyWhen": {
   "%%user.custom_data.status": "ACTIVE",
   "%%root.owners": "%%user.id"
}

Note

Some expansions, like %%user, are available in all expressions. Others are limited to specific contexts, like %%root which is not Sync compatible and is only available in expressions that operate on a document.

When using Device Sync, expansions have special restrictions. See Sync-Compatible Expansions.

Logical Expansions

%%true: Type: boolean
Usable In: Any Expression
Evaluates to true. Use this to assert that a nested expression must evaluate to true.

%%false: Type: boolean
Usable In: Any Expression
Evaluates to false. Use this to assert that a nested expression must evaluate to false.

Value Expansions

%%values

Type: object

Usable In: Any Expression

Represents your application's values. Each field of the object maps a value name to its corresponding JSON value or secret.

Example

The following expression evaluates to true if the value admin_ids is a list that contains the user's account ID:

{
  "%%user.id": { "$in": "%%values.admin_ids" }
}

Environment Expansions

%%environment

Type: object

Usable In: Any Expression

Represents the current App environment. You can read the environment name (tag) and access environment values.

Each property of the object maps the name of an environment value to its value in the current environment.

{
  "tag": "<Environment Name>"
  "values": {
    "<ValueName>": <Value>
  }
}

Example

The following is a rule expression that evaluates to true if the current environment is "production" and the "baseUrl" environment value is defined:

{
  "%%environment.tag": "production",
  "%%environment.values.baseUrl": { "%exists": true }
}

Request Expansions

%%request

Type: object

Usable In: Any Expression

Represents the incoming request.

{
  "httpMethod": "<HTTP Method>",
  "httpReferrer": "<HTTP Referer Header>",
  "httpUserAgent": "<HTTP User Agent>",
  "rawQueryString": "<URL Query String>",
  "remoteIPAddress": "<IP Address>",
  "requestHeaders": {
    "<Header Name>": ["<Header Value>", ...]
  },
  "service": "<Service Name>",
  "action": "<Endpoint Function or Service Action Name>",
  "webhookUrl": "<HTTPS Endpoint Route>"
}

User Expansions

%%user

Type: object

Usable In: Any Expression

Represents the user that initiated the request. The user object contains account information, metadata from authentication providers, and custom data from your app.

{
  "id": "<User Account ID>",
  "type": "<normal | server>",
  "data": {
    "<Field Name>": <Value>,
    ...
  }
  "custom_data": {
    "<Field Name>": <Value>,
    ...
  }
  "identities": [
    {
      "providerType": "<Auth Provider Name>",
      "id": "<Provider User ID"
    }
    ...
  ]
}

%%user.id: Type: string
Usable In: Any Expression
The authenticated user's id.

%%user.type: Type: "normal" | "server"
Usable In: Any Expression
The type of user that initiated the request. Evaluates to "server" for API key users and "normal" for all other users.

%%user.custom_data

Type: object

Usable In: Any Expression

The user's custom data. The exact contents vary depending on your custom user data configuration.

Example

"custom_data": {
  "primaryLanguage": "English",
}

%%user.data

Type: object

Usable In: Any Expression

The user's metadata. The exact contents will vary depending on the authentication provider identities associated with the user.

Example

"data": {
  "name": "Joe Mango",
  "email": "joe.mango@example.com"
}

%%user.identities

Type: object[]

Usable In: Any Expression

A list of all authentication provider identities associated with the user. An identity consists of a unique identifier given to a user by an authorization provider along with the provider's type:

Example

"identities": [
  {
    "id": "5bce299457c70db9bd73b8-aajddbkuvomsvcrjjfoxs",
    "providerType": "local-userpass"
  }
]

MongoDB Document Expansions

%%this: Type: any
Usable In: MongoDB Atlas Data Sources
The value of a particular field as it exists at the end of a database operation.

%%prev: Type: any
Usable In: MongoDB Atlas Data Sources
The value of a particular field before it is changed by a write operation.

%%root: Type: object
Usable In: MongoDB Atlas Data Sources
The full document as it exists at the end of a database operation.

%%prevRoot: Type: object
Usable In: MongoDB Atlas Data Sources
The full document before it is changed by a write operation.

Example

The following is a MongoDB schema validation expression that evaluates to true if either the document previously existed (i.e. the action is not an insert) or the document's status field has a value of "new":

{
  "%or": [
    { "%%prevRoot": { "%exists": %%true } },
    { "%%root.status": "new" }
  ]
}

Service Expansions

%%args

Type: object

Usable In: Third-Party Services [Deprecated]

A document containing the values passed as arguments to a service action. You can access each argument by its parameter name.

Example

The following is a Twilio service rule that evaluates to true if the sender's phone number (the from argument) matches a specific value:

{
  "%%args.from": "+15558675309"
}

%%partition: Type: string | number | BSON.ObjectId
Usable In: Partion-based Sync
(Partition-Based Sync only.) The partition key value of the current partition being evaluated.

Operators

An expression operator represents an action or operation within an expression. Operators take in one or more arguments and evaluate to a result value. The type and value of the result depends on the operator you use and the arguments you pass to it.

Expression operators are denoted by strings that begin with either a single percent sign (%) or a dollar sign ($). You can use them in any expression.

Convert EJSON Values

The following operators allow you to convert values between EJSON and JSON representations:

%stringToOid

Converts a 12-byte or 24-byte string to an EJSON objectId object.

Example

{
  "_id": {
    "%stringToOid": "%%user.id"
  }
}

%oidToString

Converts an EJSON objectId object to a string.

Example

{
  "string_id": {
    "%oidToString": "%%root._id"
  }
}

%stringToUuid

Converts a 36-byte string to an EJSON UUID object.

Example

{
  "_id": {
    "%stringToUuid": "%%user.id"
  }
}

%uuidToString

Converts an EJSON UUID object to a string.

Example

{
  "string_id": {
    "%uuidToString": "%%root._id"
  }
}

Important

No Inner Operations

%stringToUuid, %uuidToString, %stringToOid, and %oidToString do not evaluate JSON operators. You must provide either a literal string/EJSON object or an expansion that evaluates to one.

Call a Function

The following operators allow you to call functions in your App Services application:

%function

Calls a function with the specified name and arguments. Evaluates to the value that the function returns.

Example

{
  "%%true": {
    "%function": {
      "name": "isEven",
      "arguments": [42]
    }
  }
}

Check Existence

The following operators allow you to determine if a value exists in an object or array:

$exists

Checks if the field it is assigned to has any value. Evaluates to a boolean representing the result.

Example

{
  "url": { "$exists": true }
}

$in

Checks a specified array of values to see if the array contains the value of the field that this operator is assigned to. Evaluates to a boolean representing the result.

Example

{
  "url": {
    "$in": [
      "https://www.example.com",
      "https://www.mongodb.com"
    ]
  }
}

$nin

Checks a specified array of values to see if the array does not contain the value of the field that this operator is assigned to. Evaluates to a boolean representing the result.

Example

{
  "url": {
    "$nin": [
      "https://www.example.com",
      "https://www.mongodb.com"
    ]
  }
}

Compare Values

The following operators allow you to compare values, including expanded values:

$eq

Checks if the field it is assigned to is equal to the specified value. Evaluates to a boolean representing the result.

Example

{ "score": { "$eq": 42 } }

$ne

Checks if the field it is assigned to is not equal to the specified value. Evaluates to a boolean representing the result.

Example

{ "numPosts": { "$ne": 0 } }

$gt

Checks if the field it is assigned to is strictly greater than the specified value. Evaluates to a boolean representing the result.

Example

{ "score": { "$gt": 0 } }

$gte

Checks if the field it is assigned to is greater than or equal to the specified value. Evaluates to a boolean representing the result.

Example

{ "score": { "$gte": 0 } }

$lt

Checks if the field it is assigned to is strictly less than the specified value. Evaluates to a boolean representing the result.

Example

{ "score": { "$lt": 0 } }

$lte

Checks if the field it is assigned to is less than or equal to the specified value. Evaluates to a boolean representing the result.

Example

{ "score": { "$lte": 0 } }

Back

Role-based Permissions

Filter Incoming Queries