Navigation

Application File Schema

Overview

MongoDB Stitch applications are stored according to a specific file and directory schema.

The following figure shows a high-level view of a Stitch application’s directory structure:

yourStitchApp/
├── stitch.json
├── secrets.json
├── auth_providers/
│   └── <provider name>.json
├── functions/
│   └── <function name>/
│       ├── config.json
│       └── source.js
├── services/
│   └── <service name>/
│       ├── config.json
│       ├── incoming_webhooks/
│       │   ├── config.json
│       │   └── source.js
│       └── rules/
│           └── <rule name>.json
└── values/
    └── <value name>.json

Application Configuration

Application-level configuration information is defined in a single document named stitch.json stored in your application’s root directory.

stitch.json

Field Type Description
app_id string

The App ID for your Stitch Application.

If app_id is not specified on import, stitch-cli will prompt you to create a new application.

name string The name of your Stitch Application.
config_version number The version of the Application File Schema used in the application directory. This value is machine generated and should not be changed manually.
security document

A document containing security configuration options. The following example shows all possible fields:

"security": {
  "allowed_request_origins": [<string>]
}

Sensitive Information

Fields containing sensitive information (e.g. the client secret for a third-party service) are defined separately from their respective entity in a single JSON file named secrets.json stored in your application’s root directory.

Note

Sensitive fields can be imported into Stitch but are never exported. Any existing secrets that aren’t included in secrets.json will remain unchanged after an import.

secrets.json

Each top-level field key in secrets.json maps to an application component with sensitive fields. The value for each top-level field is a document that contains one embedded document for each entity with sensitive fields.

Each embedded document takes the following form:

"<entity name>": {
   "<secret key>": "<secret value>"
}

The following document is an example secrets.json that shows sensitive fields for an entity of each component type:

{
  "auth_providers": {
    "oauth2-facebook": {
      "clientSecret": "abcdefghijklmnop"
    }
  },
  "services": {
    "myTwilioService": {
      "auth_token": "abcdefghijklmnop"
    }
  }
}

Authentication Providers

Authentication providers are defined in your application’s /auth_providers/ directory.

Each provider is defined in its own JSON file named after the provider.

Configuration

<provider name>.json

The table below lists fields that are common across all authentication provider documents. For detailed information on configuring and using a specific authentication provider, see that provider’s reference page.

Field Type Description
id ObjectId An ObjectId that uniquely identifies the authentication provider.
name string The authentication provider name.
type string The authentication provider type.
config document A document containing configuration information for the service.
disabled boolean If true, this authentication provider is not enabled for your application and cannot be used.

Functions

Stitch functions are defined in a sub-directory of your application’s /functions/ directory. Each function maps to its own subdirectory with the same name as the function.

Each function is configured in config.json and has source code defined in source.js within its directory.

Configuration

config.json

Field Type Description
id ObjectId An ObjectId that uniquely identifies the function.
name string The function name.
private boolean If true, this function may only be accessed from incoming webhooks, rules, and named functions.

Source Code

source.js

exports = function() {
  // function code
};

Services

Services are defined in a sub-directory of your application’s /services/ directory. Each service maps to its own sub-directory named after the service.

Each service is configured in config.json within its directory. Incoming webhooks for the service are defined in the /incoming_webhooks/ sub-directory and service rules are defined in the /rules/ sub-directory.

Configuration

config.json

Field Type Description
id ObjectId An ObjectId that uniquely identifies the service.
name string The name of the service.
type string The type of the service.
config document A document with fields that map to configuration options for the service.

Incoming Webhooks

Incoming webhooks for a specific service are defined in the /<service name>/incoming_webhooks/ sub-directory.

Each incoming webhook is configured in config.json and has function source code defined in source.js within its directory.

Configuration

config.json

Field Type Description
id ObjectId An ObjectId that uniquely identifies the document.
name string The name of the webhook.
run_as_user_id string The User ID of the Stitch User that should run the function.
run_as_user_id_script_source string A stringified javascript function that returns a Stitch User ID.
respond_result boolean If true, the webhook will return its function result to the calling client.

Source Code

source.js

exports = function() {
  // webhook function code
};

Service Rules

Rules for a specific service are defined in the /<service name>/rules/ sub-directory.

Each rule maps to its own JSON file with the same name as the rule.

<rule name>.json

Field Type Description
id ObjectId An ObjectId that uniquely identifies the document.
name string The name of the service rule.
actions array of strings A list of service actions that are allowed.
when document The rule definition document.

MongoDB Collection Rules

MongoDB collection rules have a different schema than other service rules. Each collection’s rules are stored in a JSON file with the same name as the collection namespace.

<db.collection>.json

Field Type Description
id ObjectId An ObjectId that uniquely identifies the rule.
namespace string The dot-notation namespace of the collection, e.g. myDb.coll.
filters array An array of documents, one for each filter on the collection. Filter documents have two keys, match_expression and when, that each take a rule expression as the value.
read document The top-level document read rule for the collection.
write document The top-level document write rule for the collection.
valid document The top-level document validation rule for the collection.
fields document

A document containing read, write, and validation rules for specific fields. Each field with additional rules maps to a field in this document. Rules for each field are defined in an embedded document containing rule expressions. The document has the following form:

{
  <field name>: {
    "read": <rule expression>,
    "write": <rule expression>,
    "valid": <rule expression>
  },
  ...
}
other_fields document

A document containing default read, write, and validation rule expressions for all fields that weren’t explicitly defined. The document has the following form:

{
  "read": <rule expression>,
  "write": <rule expression>,
  "valid": <rule expression>
}

Triggers

Database triggers are defined in your application’s /triggers/ directory.

Each trigger is defined in its own JSON file with the same name as the trigger.

Configuration

<trigger name>.json

Field Type Description
id ObjectId An ObjectId that uniquely identifies the trigger.
name string The name of the trigger.
type string The type of the trigger. The only valid value for this field is "DATABASE".
function_name string The name of the Stitch function that the trigger executes whenever it fires. The trigger automatically passes the change event that caused it to fire as the only argument to this function.
disabled document If true, Stitch will not listen for changes in the collection and the trigger will not fire. Stitch will only open change streams for collections with at least one enabled trigger.
config document A document with fields that map to additonal configuration options for the trigger.

The config document has the following fields:

Field Type Description
operation_types Array

A list of one or more change event types that cause the trigger to fire. The following change event types are valid:

  • INSERT
  • UPDATE
  • REPLACE
  • DELETE
database Array The name of the MongoDB database that contains the collection the trigger observes.
collection Array The name of the collection for which the trigger listens to change events.
service_name Array The name of the Stitch MongoDB Service that the trigger is associated with.
match Document A $match expression document that the trigger uses to filter change events. The trigger will only fire if the expression evaluates to true for a given change event.
full_document Boolean

If true, indicates that UPDATE change events should include the most current majority-committed version of the modified document in the fullDocument field.

Note

This option only affects UPDATE change events. INSERT and REPLACE events always include the fullDocument field. DELETE events never include the fullDocument field. For more information, see the change events reference page.

Warning

Update operations executed from MongoDB Compass or the MongoDB Atlas Data Explorer fully replace the previous document. As a result, update operations from these clients will generate REPLACE change events rather than UPDATE events.

Values

Values are defined in your application’s /values/ directory.

Each value is defined in its own JSON file named after the value.

Definition

<value name>.json

Field Type Description
id ObjectId An ObjectId that uniquely identifies the value.
name string The name of the value.
value string, array, or document The value being stored.
private boolean If true, this value may only be accessed from incoming webhooks, rules, and named functions.