Expansions are special variables for use with Stitch rules.


The following expansions are available in any rule in any Stitch app.

Name Type Description
boolean True.
boolean False.
document Holds user information. See %%user object.
any Expand a value (e.g.
returned value Execute a function defined in the MongoDB Stitch app.


The following expansions are for use in MongoDB service rules rules. %%this and %%prev represent document fields, while %%root and %%prevRoot represent documents. %%prev and %%prevRoot represent the original values of fields and documents which are changed after write operations.

Name Type Description
any Field value as it exists at the end of a database operation.
document Root document as it exists at the end of a database operation.
any Field value referenced in a rules expression before it is changed by a write operation (insert, update, delete).
document Root document referenced in a rules expression before it is changed by a write operation.

The %%user Object

The %%user object has several fields with information about the app user.

Name Type Description
String User’s ID.
String Evaluates to "server" if the user request comes via an API key. Evaluates to "normal" for other user requests (via OAuth2, SAML, local, or anonymous).
document User metadata, including name and email (via login authentication).
array A list of all identities associated with a MongoDB Stitch user. An identity consists of a unique identifier given to a user by an authorization provider along with the provider’s name.


The %%user Object

The %%user object is useful for identifying users in database rules. When an app user logs in to an app, the %%user object is populated with the user’s authentication information, which can include name and ID.

The following database rule example evaluates to true only if the owner_id field value matches the value of and the owner_name field value matches the value of

  "owner_id": "",
  "owner_name": ""

An app can allow certain actions, such as updating and deleting, to be taken only by a document’s owner. Other users may only have permission to perform other actions, such as reading. The above rule allows the app to distinguish between the owner and other users.

MongoDB Validation Rule

The following example is a MongoDB validation rule. It evaluates to valid if either:

  • The document already exists
  • The value specified in the name field of the document is not in the name array which is part of the named value myBoards.
  "%or": [
      "%%prevRoot": {
        "%exists": %%true
      "": {
        "%nin": ""


The %%this object refers to the current document or field. This expansion is typically used to construct field and document-level permissions on a database collection. For example, the following MongoDB service write rule verifies that the value of a field is greater than 3 before allowing a write to the collection.

{ "%%this": { "%gt": 3 } }

Calling a Function

The result of a function can be used in a rule. Functions are called with the %function expansion. The following example evaluates to valid if the user’s id is found in a predefined admins value.

The following function is defined as checkAuth:

exports = function() {
   var admins = context.values.get("admins");
   return (admins.indexOf(context.user._id) !== -1);

The function returns true if and only if the current user’s id is contained in the admins value.

A rule can use this function to check authentication as follows:

   "%%true": {
     "%function": {
         "name": "checkAuth",
         "arguments": []