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
├── triggers/
│   └── <trigger name>.json
├── hosting/
│   ├── metadata.json
│   └── files/
│       └── <files to host>
└── 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 that has the following form:

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

A document containing hosting configuration options that has the following form:

"hosting": {
  "enabled": <boolean>,
  "custom_domain": "<Custom Domain Name>",
  "app_default_domain": "<Default Domain Name>"
}
Field Name Description
enabled Boolean. Indicates whether hosting is enabled for your application.
custom_domain String. A custom domain name for your application’s hosted files.
app_default_domain String. The default domain for your application’s hosted files. This value is automatically set by Stitch and cannot be changed.
deployment_model string

The deployment model for the application. The following values are valid:

Deployment Model Value
Global Deployment "GLOBAL"
Local Deployment "LOCAL"
location string

The name of the cloud region that your application is deployed in.

For local applications this region is where all application requests and database write operations are processed.

For global applications this region is where database write operations are processed but not necessarily where application requests are processed.

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 Description
id An ObjectId that uniquely identifies the rule.
database The name of the database that holds the collection.
collection The name of the collection.
filters

An array of filter configuration documents, which have the following form:

{
  "name": "<Filter Name>",
  "apply_when": <JSON Expression>,
  "query": <Query Document>
}
Field Description
name Required. The name of the filter. Filter names are useful to help you identify and distinguish between filters. Limited to 100 characters or fewer.
apply_when

Required. A JSON expression that determines when this filter applies to a given query.

Important

Stitch evaluates and applies filters before it reads any documents, so you cannot use MongoDB document expansions in a filter’s Apply When expression. However, you can use other expression variables such as %%true, %%user, and %%values.

query

Required. A document that contains additional query predicates to merge into incoming queries that the filter applies to. This document has the same structure as a query document passed directly to a CRUD operation.

Example

A filter that withholds documents that have a score below 20 could use the following filter query:

{ "score": { "$gt": 20 } }

Triggers

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 additional configuration options for the trigger. The contents of this document depend on the type of application event the trigger observes.

See the database trigger configuration or authentication trigger configuration reference sections for details and examples of the configuration values for each event type.

Hosting

Files that you want to host on Stitch should be included in your application’s /hosting/ directory. Each file will be uploaded with the metadata defined in metadata.json.

Metadata Configuration

You can configure the metadata for each hosted file in metadata.json. This metadata configuration file is an array of documents that each correspond to a single hosted file’s metadata attributes. Metadata configuration files have the following form:

metadata.json
[
  {
    "path": "<File Resource Path>",
    "attrs": [
       ...,
       <Attribute Definition>
    ],
  },
  ...
]
Field Description
path Required. The resource path of the file.
attrs

Required. An array of documents where each document represents a single metadata attribute. Attribute documents have the following form:

Metadata Attribute Document
{
  "name": "<Attribute Type>",
  "value": "<Attribute Value>"
}
Field Description
name The name of the metadata attribute. This should be one of the file metadata attributes that Stitch supports.
value The value of the metadata attribute.

Note

If you do not specify a Content-Type attribute for a file, Stitch will attempt to automatically add a Content-Type attribute to it based on the file extension.

For example, Stitch would automatically add the attribute Content-Type: application/html to the file myPage.html.

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.
←   stitch-cli Stitch Errors  →