• Realm >
• Reference

Application Configuration Files

Overview

MongoDB Realm uses JSON files and source code files to define and configure every component of an application. Each component has a specific configuration file schema and every application uses a standard file structure to organize the configuration files.

When Will I Use Configuration Files?

Every Realm app is composed of a collection of configuration files, so you use application configuration files whenever you create or modify a Realm app. If you use the Realm UI then you rarely deal directly with the configuration files themselves, but other deployment methods, like Realm CLI and GitHub allow you to define and edit the configuration files directly.

Directory Structure

The following figure shows a high-level view of a Realm app’s directory structure:

copy

yourRealmApp/
├── realm.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

File Structure

yourRealmApp/
└── realm.json

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

Configuration

copy

realm.json

{
  "app_id": "",
  "name": "",
  "security": {
    "allowed_request_origins": ["<Origin URL>"]
  },
  "hosting": {
    "enabled": <boolean>,
    "custom_domain": "<Custom Domain Name>",
    "app_default_domain": "<Default Domain Name>"
  },
  "custom_user_data_config": {
    "enabled": <Boolean>
    "mongo_service_id": "<MongoDB Service ID>",
    "database_name": "<Database Name>",
    "collection_name": "<Collection Name>",
    "user_id_field": "<Field Name>"
  }
  "deployment_model": "<Deployment Model Type>",
  "location": "<Deployment Cloud Region Name>",
  "config_version": <Version Number>
}

Field	Description
app_id String	The application’s App ID.
name String	The application’s name. App Name Limitations Application names must be between 1 and 32 characters and may only contain ASCII letters, numbers, underscores, and hyphens.
security Document	A document that contains configuration options for application-level security features. "security": { "allowed_request_origins": ["<Origin URL>"] } Field Name Description allowed_request_origins Array<String> An array of URLs that incoming requests may originate from. If you define any allowed request origins, then Realm blocks any incoming request from an origin that is not listed. Request origins are URLs with the following form: copy <scheme>://<host>[:port]
hosting Document	A document that contains configuration options for all hosted files: "hosting": { "enabled": <boolean>, "custom_domain": "<Custom Domain Name>", "app_default_domain": "<Default Domain Name>" } Field Name Description enabled Boolean If true, indicates that your application can host static files. 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. Realm automatically sets this value and you cannot change it.
config_version Number	The schema version that all configuration files in the application conform to. This value is machine generated and you typically should not manually set or modify it.
custom_user_data_config Document	A document that contains configuration options for custom user data. "custom_user_data_config": { "enabled": <Boolean> "mongo_service_id": "<MongoDB Service ID>", "database_name": "<Database Name>", "collection_name": "<Collection Name>", "user_id_field": "<Field Name>" } Field Name Description enabled Boolean If true, Realm associates each user with a document that contains their data stored in the specified collection. mongo_service_id String The service ID of the linked MongoDB Atlas cluster that contains the custom user data. You can find this value in the id field of the service configuration file. database_name String The name of the database that contains the custom user data collection. collection_name String The name of the collection that contains the custom user data. user_id_field String The name of the field in each custom data document that contains the user ID of the application user the document describes.
deployment_model String	The application’s deployment model. The following values are valid: Deployment Model Value Global Deployment "GLOBAL" Local Deployment "LOCAL"
location String	The name of the cloud region that the application is deployed in. Local applications process all application requests and database writes in this region. Global applications process all database writes in this region, but serve other application requests in the nearest deployment region.

Authentication Providers

File Structure

yourRealmApp/
└── auth_providers/
    └── <provider name>.json

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

Each provider is defined in its own JSON file named after the provider. For detailed information on configuring and using a specific authentication provider, see that provider’s reference page.

Configuration

copy

<provider name>.json

{
  "id": "<Provider ID>",
  "name": "<Provider Name>",
  "type": "<Provider Type>",
  "disabled": <Boolean>,
  "config": {
    "<Configuration Option>": <Configuration Value>
  },
  "secret_config": {
    "<Configuration Option>": "<Secret Name>"
  },
  "metadata_fields": [{
    "required": <Boolean>,
    "name": "Field Name"
  }]
}

Field	Description
id String	A value that uniquely identifies the authentication provider. Realm automatically generates a unique ID for a provider when you create it.
name String	The name of the authentication provider.
type String	The type of the authentication provider. Valid Options: "anon-user" "local-userpass" "api-key" "oauth2-apple" "oauth2-google" "oauth2-facebook" "custom-token" "custom-function"
config Document	A document that contains configuration values that are specific to the authentication provider. The existence of this field and its exact configuration fields depend on the provider type.
secret_config Document	A document where each field name is a private configuration field for the provider and the value of each field is the name of a Secret that stores the configuration value.
metadata_fields Array<Document>	An array of documents where each document defines a metadata field that describes the user. The existence of this field and the exact format of each metadata field document depends on the provider type.
disabled Boolean	If true, this authentication provider is not enabled for your application and cannot be used.

Functions

File Structure

yourRealmApp/
└── functions/
    └── <function name>/
        ├── config.json
        └── source.js

Realm 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 its source code defined in source.js.

Configuration

copy

config.json

{
  "id": "<Function ID>",
  "name": "<Function Name>",
  "private": <Boolean>,
  "can_evaluate": <Rule Expression>,
  "disable_arg_logs": <Boolean>,
  "run_as_system": <Boolean>,
  "run_as_user_id": "<Realm User ID>",
  "run_as_user_id_script_source": "<Function Source Code>"
}

Field	Description
id String	A value that uniquely identifies the function. Realm automatically generates a unique ID for a function when you create it.
name String	The name of the function. The name must be unique among all functions in your application.
private Boolean	If true, this function may only be accessed from incoming webhooks, rules, and named functions.
can_evaluate Document	A rule expression that evaluates to true when the function is allowed to execute in response to a given request.
disable_arg_logs Boolean	If true, Realm omits the arguments provided to a function from the function execution log entry.
run_as_system Boolean	If true, this function runs as the system user. This overrides any values defined for run_as_user_id and run_as_user_id_script_source.
run_as_user_id String	The unique ID of a Realm User that the function always executes as. Cannot be used with run_as_user_id_script_source.
run_as_user_id_script_source String	A stringified function that runs whenever the function is called and returns the unique ID of a Realm User that the function executes as. Cannot be used with run_as_user_id.

Source Code

copy

source.js

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

External Services

File Structure

yourRealmApp/
└── services/
    └── <services name>/
        ├── config.json
        ├── incoming_webhooks/
        │   ├── config.json
        │   └── source.js
        └── rules/
            └── <rule name>.json

Services, including both MongoDB services and external services, are defined the /services directory. Each service maps to its own sub-directory with the same name as the service.

Each service directory contains a service configuration file (config.json), a sub-directory of service rule configurations (/rules), and a sub-directory of webhook configurations (/incoming_webhooks) if the service supports webhooks.

Service Configuration

copy

config.json

{
  "id": "<Service ID>",
  "name": "<Service Name>",
  "type": "<Service Type>",
  "config": {
    "<Configuration Option>": <Configuration Value>
  },
  "secret_config": {
    "<Configuration Option>": "<Secret Name>"
  },
}

Field	Description
id String	A string that uniquely identifies the service. Realm automatically generates a unique ID for a service when you create it.
name String	The name of the service. The name may be at most 64 characters long and can only contain ASCII letters, numbers, underscores, and hyphens.
type String	The type of the service. Valid Options: "mongodb-atlas" "http" "aws" "twilio" "github" "gcm"
config Document	A document with fields that map to additional configuration options for the service. The exact configuration fields depend on the service type. MongoDB Atlas Service HTTP Service Configuration AWS Service Configuration Twilio Service Configuration GitHub Service Configuration
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.

External Service Rules

Rules for a specific external 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.

copy

<rule name>.json

{
  "id": "<Rule ID>",
  "name": "<Rule Name>",
  "actions": ["<Service Action Name>"],
  "when": <JSON Rule Expression>
}

Field	Description
id String	A string that uniquely identifies the rule. Realm automatically generates a unique ID for a rule when you create it.
name String	The name of the service rule. The name may be at most 64 characters long and can only contain ASCII letters, numbers, underscores, and hyphens.
actions Array<String>	A list of service actions that the rule applies to. The specific actions available depend on the service type.
when Document	A rule expression that evaluates to true when the rule applies to a given request.

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.

copy

<db.collection>.json

{
  "id": "<Rule ID>",
  "database": "<Database Name>",
  "collection": "<Collection Name>",
  "roles": [<Query Role>],
  "schema": <Document Schema>,
  "filters": [<Query Filter>],
}

Field	Description
id String	A string that uniquely identifies the trigger. Realm automatically generates a unique ID for a trigger when you create it.
database String	The name of the database that holds the collection.
collection String	The name of the collection.
roles Array<Document>	An array of Query Role configuration documents, which have the following form: copy { "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 Description name String The name of the role. Role names are useful for identifying and distinguishing between roles. Limited to 100 characters or fewer. apply_when Document A JSON Expression that evaluates to true when this role should be applied. read Boolean or Document 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 Boolean or Document 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 Boolean or Document 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 Boolean or Document Default: false A boolean or JSON Expression that evaluates to true if the role has permission to delete a document from the collection. fields Document 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. copy "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 Boolean or Document Default: false A boolean or JSON Expression that evaluates to true if the role has permission to read the field. fields.<Field Name>.write Boolean or Document 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 Document 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 Document 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. copy "additional_fields": { "read": <Boolean|JSON Expression>, "write": <Boolean|JSON Expression> } additional_fields.read Boolean or Document 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 Boolean or Document 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 Document	A Document Schema. The root level schema must be an object schema, which has the following form: copy { "bsonType": "object", "properties": { "<Field Name>": <Schema Document> } }
filters Array<Document>	An array of Query Filter configuration documents, which have the following form: copy { "name": "<Filter Name>", "apply_when": <JSON Expression>, "query": <Query Document>, "projection": <Projection Document> } Field Description name String 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 MongoDB Realm 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 %%user, %%values, and %function. query Document 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: copy { "score": { "$gt": 20 } } projection Document Required. A MongoDB projection document that specifies additional field projections to merge into incoming queries that the filter applies to. Projection Conflicts MongoDB projections can be either inclusive or exclusive, i.e. they can either return only specified fields or withhold fields that are not specified. If multiple filters apply to a query, the filters must all specify the same type of projection, or the query will fail. Example A filter that withholds the _internal field from all documents could use the following filter projection: copy { "_internal": 0 }

Incoming Webhooks

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

Incoming webhooks use the same configuration format as function but have additional configuration parameters.

Configuration

copy

config.json

{
  "id": "<Function ID>",
  "name": "<Function Name>",
  "private": <Boolean>,
  "can_evaluate": <Rule Expression>,
  "disable_arg_logs": <Boolean>,
  "run_as_system": <Boolean>,
  "run_as_user_id": "<Realm User ID>",
  "run_as_user_id_script_source": "<Function Source Code>",
  "respond_result": <Boolean>,
  "options": {
    "httpMethod": "<HTTP Method>",
    "validationMethod": "<Webhook Validation Method>",
    "secret": "<Webhook Secret>"
  }
}

Field	Description
id String	A value that uniquely identifies the function. Realm automatically generates a unique ID for a function when you create it.
name String	The name of the function. The name must be unique among all functions in your application.
private Boolean	If true, this function may only be accessed from incoming webhooks, rules, and named functions.
can_evaluate Document	A rule expression that evaluates to true when the function is allowed to execute in response to a given request.
disable_arg_logs Boolean	If true, Realm omits the arguments provided to a function from the function execution log entry.
run_as_system Boolean	If true, the webhook function runs as the system user. This overrides any values defined for run_as_user_id and run_as_user_id_script_source.
run_as_user_id String	The unique ID of a Realm User that the function always executes as. Cannot be used with run_as_user_id_script_source.
run_as_user_id_script_source String	A stringified function that runs whenever the webhook is called and returns the unique ID of a Realm User that the function executes as. Cannot be used with run_as_user_id.
respond_result Boolean	If true, Realm includes the webhook function return value as the body of the HTTP response it sends to the client that initiated the webhook request.
options Document	A document that contains configuration options for the webhook. copy { "httpMethod": "<HTTP Method>", "validationMethod": "<Webhook Validation Method>", "secret": "<Webhook Secret>" } Field Description httpMethod String The HTTP method type that the webhook accepts. Incoming webhook requests must use this method. validationMethod String The name of the request validation method that the webhook uses. Valid options: "VERIFY_PAYLOAD" "SECRET_AS_QUERY_PARAM" "NO_VALIDATION" secret String The secret value used to validate incoming webhook requests.

Source Code

copy

source.js

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

Triggers

File Structure

yourRealmApp/
└── triggers/
    └── <trigger name>.json

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

copy

<trigger name>.json

{
  "id": "<Trigger ID>",
  "name": "<Trigger Name>",
  "type": "<Trigger Type>",
  "function_name": "<Trigger Function Name>",
  "config": {
    "<Configuration Option>": <Configuration Value>
  },
  "disabled": <Boolean>,
}

Field	Description
id String	A string that uniquely identifies the Trigger. Realm automatically generates a unique ID for a trigger when you create it.
name String	The name of the Trigger. The name may be at most 64 characters long and can only contain ASCII letters, numbers, underscores, and hyphens.
type String	The type of application event that the trigger listens for. Valid Options: "DATABASE" "AUTHENTICATION" "SCHEDULED"
function_name String	The name of the Realm Function that the Trigger executes whenever it fires. The Trigger automatically passes arguments to the function depending on the Trigger type.
config Document	A document with fields that map to additional configuration options for the trigger. The exact configuration fields depend on the trigger type. Database Trigger Configuration Authentication Trigger Configuration Scheduled Trigger Configuration
disabled Boolean	If true, the trigger will not listen for any events and will not fire.

Hosting

File Structure

yourRealmApp/
└── hosting/
    ├── metadata.json
    └── files/
        └── <files to host>

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

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

copy

metadata.json

[
  {
    "path": "<File Resource Path>",
    "attrs": [{
      "name": "<Attribute Type>",
      "value": "<Attribute Value>"
    }]
  }
]

Field	Description
path String	The resource path of the file.
attrs Array<Document>	An array of documents where each document represents a single metadata attribute. Attribute documents have the following form: copy Metadata Attribute Document { "name": "<Attribute Type>", "value": "<Attribute Value>" } Field Description name String The name of the metadata attribute. This should be one of the file metadata attributes that Realm supports. value String The value of the metadata attribute.

Note

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

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

Values

File Structure

yourRealmApp/
└── values/
    └── <value name>.json

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

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

Configuration

copy

<value name>.json

{
  "id": "<Value ID>",
  "name": "<Value Name>",
  "from_secret": <boolean>,
  "value": <Stored JSON Value|Secret Name>
}

Field	Description
id String	A string that uniquely identifies the value. Realm automatically generates a unique ID for a value when you create it.
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 Realm 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.

←   JSON Expressions MongoDB Cloud Users  →

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.