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

Event 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 application event that the trigger listens for.

Valid Options:

  • "DATABASE"
  • "AUTHENTICATION"
function_name string The name of the Stitch function that the trigger executes whenever it fires. The trigger automatically passes the event object that caused it to fire as the only argument to this function.
disabled boolean If true, the trigger will not listen for any events and will not fire.
config document

A document with fields that map to additonal configuration options for the trigger. The contents of this document depend on the type of application event the trigger observes.

See the trigger configuration reference section for details and examples of the configuration values for each event type.

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.