Navigation

Expression Variables

Overview

You can use special variables in JSON expressions to represent dynamic values and operations. There are two types of expression variables: expansions and operators.

Expansions

Expansions represent dynamic values that Stitch replaces when it evaluates an expression. Expansion variables begin with two percent signs (%%).

General Logic

You can use the following expansions in any JSON expression to represent boolean values.

Name Type Description
%%true
boolean Always evaluates to true. This is useful when comparing with a function (%function) that returns a boolean value.
%%false
boolean Always evaluates to false. This is useful when comparing with a function (%function) that returns a boolean value.

Application Components

You can use the following expansions in any JSON expression to represent components of your application.

Name Type Description
%%values
any

An object that includes all global values that you’ve defined in your Stitch application. You can access a specific value from this object.

Example

The following is a MongoDB schema validation expression that evaluates to true if the document’s secret field matches the used-defined value named secretString:

{
  "%%root.secret": "%%values.secretString"
}
%%request
object An object that includes context request information about the external HTTP request that triggered the function call.

Authenticated User

The %%user expansion represents the currently authenticated user and allows you to access their information. You can use this expansion to create expressions that evaluate based on the user that initiated a request or action.

Name Type Description
%%user
Document A document containing information and data about the authenticated user.
%%user.id
String The authenticated user’s id.
%%user.type
String The type of user that initiated the request. Evaluates to "server" for API key users and "normal" for all other users.
%%user.custom_data
Document

The user’s custom data. The exact contents vary depending on the custom user data available.

Example

"custom_data": {
  "primaryLanguage": "English",
}
%%user.data
Document

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

Example

"data": {
  "name": "Joe Schmoe",
  "email": "joe.schmoe@example.com"
}
%%user.identities
Array of Documents

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

Example

The following is a MongoDB role’s Apply When expression that evaluates to true only if a document’s owner_id and owner_name values match the values of %%user.id and %%user.data.name:

{
  "owner_id": "%%user.id",
  "owner_name": "%%user.data.name"
}

MongoDB Documents

You can use the following expansions in MongoDB Rules and Document Schema validation expressions:

Name Type Description
%%this
any The value of a particular field as it exists at the end of a database operation.
%%prev
any The value of a particular field as it exists before it is changed by a write operation.
%%root
Document The full document as it exists at the end of a database operation.
%%prevRoot
Document The full document as it exists 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.name": "new" }
  ]
}

Service Actions

You can use the following expansions in external service rules:

Name Type Description
%%args
any 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 ruel that evaluates to true if the sender’s phone number (the from argument) matches a specific value:

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

Operators

Operators represent run time operations that Stitch executes when it evaluates an expression. Operator variables begin with one percent sign (%).

Application Components

The following operators allow you access other components of your Stitch application and are available in all JSON expressions:

Operator Description
%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]
    }
  }
}

Existence Operators

The following operators allow you to determine if a value exists in a given context and are available in all JSON expressions:

Operator Description
%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"
    ]
  }
}

Comparison Operators

The following operators allow you to compare values, including expanded values, and are available in all JSON expressions:

Operator Description
%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 } }
%neq

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

Example

{ "numPosts": { "%neq": 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 } }