Navigation

Advanced Mode for Rules

On this page

While the Stitch UI provides access to most of the features and options you need to configure rules for a collection, there are times when you need finer-grained control. Advanced Mode allows you to manually configure all aspects of a collection rule by providing you with the underlying JSON document.

Warning

Once you convert a collection rule to Advanced Mode, you may not be able to switch back to editing in Basic Mode for this collection. Be sure that the changes you make conform to the schema defined in this document.

MongoDB rules make use of the MongoDB Stitch expression variables. In addition to the base expansions, you can also use the MongoDB-Specific expansions.

Rules JSON Reference

A collection’s rules consist of 3 parts: Roles, Filters, and Schema Validation. Each of these parts is represented by an object in the JSON document and is explained in detail below.

{
   "roles": [
   {
      "name": "created_only",
      "apply_when": {
         "createdBy": "%%user.id"
      },
      "insert": false,
      "delete": false,
      "read": true,
      "write": true,
      "fields": {
         "user_name": {
            "read": true,
            "write": true
         }
      },
      "additional_fields": {
         "read": false,
         "write": true
      }
   },
   {
      ...
   }
   ],
   "filters": [
      {
         "name": "filter 1",
         "query": {},
         "apply_when": {}
      },
      {
         "name": "filter 2",
         "query": {},
         "apply_when": {}
      }
   ],
   "schema": {}
}

Roles

The Roles array contains a Role object for each role defined on the collection. The Role object contains the following fields:

Field Required/Optional Description
name Required The name of the role. Must be less than 100 characters long.
apply_when Required A MongoDB expression or Stitch function that evaluates to true or false and determines when this role will be applied.
read Optional A MongoDB expression or Stitch function that evaluates to true or false. The read field determines if the document can be displayed to the user. Read permissions are inherited, so a read value set at the document level applies to all fields in the document and cannot be overridden.
write Optional

A MongoDB expression or Stitch function that evaluates to true or false. The write field determines if the document can be modified by the user. Write permissions are inherited, so a write value set at the document level applies to all fields in the document and cannot be overridden.

Note

If write is enabled on the document, read is implied.

insert Optional

A MongoDB expression or Stitch function that evaluates to true or false. The insert field determines if a document can be inserted by the user.

Note

All fields that are inserted must also be writeable.

delete Optional A MongoDB expression or Stitch function that evaluates to true or false. The delete field determines if a document can be deleted by the user.
fields Optional

The fields object specifies read and write rules on specific fields within the document. Each object contains the name of the field on which the permissions apply and the permissions themselves:

"fields": {
  "field_name": {
     "read": true,
     "write": false
  },
  "another_field_name": {
     "read": false
  },
}

Note

Permissions defined at the field level only apply if there are no document-level permissions that override them.

additional_fields Optional

Sets read and write permissions on unspecified fields. This allows you to set general rules for fields without defining the rules at the document level (which can’t be overridden).

"additional_fields": {
     "read": true,
     "write": false
}

Filters

Filters apply additional predicates to the query to MongoDB when the defined expressions evaluate to true. The filters array contains filter objects, which have two fields: apply_when and query:

"filters": [
      {
         "apply_when": true,
         "query": {"sharedWith.id": "%%user.id"}]
      }
],
Field Required/Optional Description
apply_when Required An expression that evaluates to true or false. When true, the filter is applied.
query Required A MongoDB query, which can include Stitch expansions. When apply_when is true, the value specified in the query field is added on to the query sent to MongoDB.

Schema

The Schema object determines if the document, or parts of the document, are valid. It uses the MongoDB JSON Schema.

Stitch supports all of the JSON Schema keywords, as well as allowing you to call a Stitch function as part of the validation. For example, to call a function named isRole, which takes a single argument, you could use the following code within your schema block:

"primaryPhys": {
      "bsonType": "objectId",
      "allOf": [
         {
         "validate": {
            "%function": {
               "name": "isRole",
               "arguments": ["%%value", "doctor"]
               }
            }
         },
      ]
}