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

Deprecated

Importing sensitive information via secrets.json has been deprecated in favor of creating Secrets and referencing them via the from_secret and secret_config fields. Existing applications created before the release of Secrets have been automatically updated to use this pattern. Values that were stored in secrets.json are now Secrets that use the following naming scheme:

__<Service or Auth Provider Name>-<Configuration Field Name>
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.
secret_config document A document where each field name is a private configuration field for the auth provider and the value of each field is the name of a Secret that stores the configuration value.
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.
secret_config document A document where each field name is a private configuration field for the service and the value of each field is the name of a Secret that stores the configuration value.

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.
roles

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

{
   "name": "<Role Name>",
   "apply_when": <JSON Expression>,
   "insert": <boolean|JSON Expression>,
   "delete": <boolean|JSON Expression>,
   "read": <boolean|JSON Expression>,
   "write": <boolean|JSON Expression>,
   "fields": {
      "<Field Name>": {
         "read": <boolean|JSON Expression>,
         "write": <boolean|JSON Expression>,
         "fields": <Fields Document>
      },
      ...
   },
   "additional_fields": {
     "read": <boolean|JSON Expression>,
     "write": <boolean|JSON Expression>
   },
}
Field Required/Optional Description
name Required The name of the role. Role names are useful for identifying and distinguishing between roles. Limited to 100 characters or fewer.
apply_when Required A JSON Expression that evaluates to true when this role should be applied.
read
Optional
Default: false

A boolean or JSON Expression that evaluates to true if the role has permission to read all fields in the document.

Document-level read permissions take priority over any field-level permissions. If a role has a document-level read rule, it applies to all fields in the document and cannot be overridden. To define specific field-level rules with a default fallback, use additional_fields instead.

write
Optional
Default: false

A boolean or JSON Expression that evaluates to true if the role has permission to add, modify, or remove all fields in the document.

Document-level write permissions take priority over any field-level permissions. If a role has a document-level write rule, it applies to all fields in the document and cannot be overridden. To define specific field-level rules with a default fallback, use additional_fields instead.

Implicit Read Permission

Any time a role has write permission for a particular scope it also has read permission even if that is not explicitly defined.

MongoDB Expansions

You can use MongoDB expansions, like %%root and %%prevRoot, in write JSON expressions.

insert
Optional
Default: false

A boolean or JSON Expression that evaluates to true if the role has permission to insert a new document into the collection.

Note

Document-level insert permission does not imply that a role can insert any document. The role must also have write permission for all fields in an inserted document for the insert to succeed.

delete
Optional
Default: false
A boolean or JSON Expression that evaluates to true if the role has permission to delete a document from the collection.
fields
Optional
Default: {}

A document where the value of each field defines the role’s field-level read and write permissions for the corresponding field in a queried document.

"fields": {
  "<Field Name>": {
     "read": <boolean|JSON Expression>,
     "write": <boolean|JSON Expression>,
     "fields": <Fields Document>
  },
  ...
}

Permission Priority

Document-level read or write permissions override all field-level permissions of the same type. If permissions are defined for a field that contains an embedded document, those permissions override any permissions defined for the document’s embedded fields.

fields.<Field Name>.read
Optional
Default: false
A boolean or JSON Expression that evaluates to true if the role has permission to read the field.
fields.<Field Name>.write
Optional
Default: false
A boolean or JSON Expression that evaluates to true if the role has permission to add, modify, or remove the field.
fields.<Field Name>.fields
Optional
Default: {}

A fields document that defines read and write permissions for fields that are embedded within this field in a queried document.

See the Field-level Permissions for Embedded Documents role pattern for more information.

additional_fields
Optional
Default: {}

A document that defines the role’s field-level read and write permissions for any fields in a queried document that don’t have explicitly defined permissions.

"additional_fields": {
  "read": <boolean|JSON Expression>,
  "write": <boolean|JSON Expression>
}
additional_fields.read
Optional
Default: false
A boolean or JSON Expression that evaluates to true if the role has permission to read any field that does not have a field-level permission definition.
additional_fields.write
Optional
Default: false
A boolean or JSON Expression that evaluates to true if the role has permission to add, modify, or remove any field that does not have a field-level permission definition.
schema

A Document Schema. The root level schema must be an object schema, which has the following form:

{
  "bsonType": "object",
  "properties": {
    "<Field Name>": <Schema Document>
  }
}
filters

An array of Query 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 for identifying and distinguishing 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 MongoDB query filter that contains additional query predicates to merge into incoming queries that the filter applies to.

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

{
  "id": "<Value ID>",
  "name": "<Value Name>",
  "from_secret": <boolean>,
  "value": <Stored JSON Value|Secret Name>
}
Field Type Description
id ObjectId An ObjectId that uniquely identifies the value.
name string A unique name for the value. This name is how you refer to the value in functions and rules.
from_secret boolean Default: false. If true, the Value exposes a Secret instead of a plain-text JSON value.
value string, array, or object

The stored data that Stitch exposes when the Value is referenced.

If from_secret is false, value can be a standard JSON string, array, or object.

If from_secret is true, value is a string that contains the name of the Secret that the value exposes.

←   stitch-cli Stitch Errors  →