Navigation
  • Rules >
  • MongoDB Service Rules

MongoDB Service Rules

For a MongoDB Service, you must set up rules to control access to fields for read and write operations. If a rule evaluates to true, read and write operation can access the fields for which the rule applies. If a rule evaluates to false, access is denied.

MongoDB Authorization

MongoDB Stitch rules do not override the read and write access (i.e. authorization) that may have been set up separately in MongoDB. That is, MongoDB Stitch rules determine whether the fields are readable or writable; not whether the client has authorization to read or write to a particular database or collection.

Add Namespace

Important

You must create a rule for each collection you wish to access.

To add a rule for a collection, from the Rules tab, click the New button, and enter the the database and collection names.

Default Rules

Read Rule

To view the read rule, click on the Top-Level Document in the Field Rules view.

By default, the collection has the following read rule for the top-level document:

{
  "owner_id": "%%user.id"
}

With this rule, read and write operations can access all fields in a document if the document contains an owner_id field whose value equals the user ID (%%user.id) of the client issuing the read. If the owner_id field in the document does not equal the client user id, no field in the document is readable.

MongoDB Stitch applies the MongoDB Service read rules to filter documents for read and write operations. The read rules are in addition to any query predicates issued in the read and write operations.

If a rule determines that a field is readable:

  • Read and write operations can query on the field.
  • Read operations can include the field in their results.

If a rule determines that a field is not readable:

  • Read and write operations cannot query on the field; query predicates on that field will not match any documents for read or write operations.
  • Read operations will omit the field in their results.

For examples, see Read Rule Examples.

Write Rule

To view the write rule, click on the Top-Level Document in the Field Rules view.

By default, the collection has the following write rule for the top-level document:

{
  "owner_id": "%%user.id"
}

With this rule, the write operation must result in a document where the owner_id equals the user ID of the client issuing the write. If the value of owner_id does not match the client user ID, MongoDB Stitch blocks the write.

MongoDB Stitch applies the write rules to determine whether a write operation is permissible. The client can modify those fields for which the write rule evaluates to true.

Important

For write operations, MongoDB Stitch clients can access fields that are readable as determined by the read rules. See MongoDB Service Read Rule for more information on read rules.

If a write operation modifies multiple documents and one of the document violates the write rules, the write operation stops upon error and does not continue processing any remaining documents.

For examples, see Write Rule Examples.

Validation Rule

To view a validation rule, click on the owner_id in the Field Rules view.

By default, the collection has the following validation rule specified on the owner_id field that determines whether a write operation is permissible:

{
  "%or": [
    { "%%prev": "%%user.id" },
    { "%%prev": { "%exists": false } }
  ]
}

With this rule, a write operation is valid if either:

  • The write operation modifies a document where the value of owner_id previous to the write operation (%%prev) equals the user ID (%%user.id) of the client issuing the write. An example of this kind of write operation is a client modifying a document that it previously inserted, or
  • The write operation modifies a document where there was no value for the owner_id field (%exists) previous to the write operation (%%prev). An example of this kind of write operation is an insert of a new document.

For a MongoDB Service, you can specify validation rules for update and insert operations. If the update and insert operations do not pass the validation rule, MongoDB Stitch fails the operations.

For details, see MongoDB Service Validation.

Filter

By default, the collection has the following filter rule:

When Match Expression
{ "%%true": true } { "owner_id": "%%user.id" }

This filter indicates that when %%true equals true (i.e. always), apply the following filter { "owner_id": "%%user.id" } to the read and write operations. This filter is in addition to the query predicates for read and write operations.

For a MongoDB Service, you can specify filters that are applied to documents when a specified condition is met. These filters are in addition to the query predicates for read and write operations.

For details, see MongoDB Service Filters.

Rules Interaction

You can specify rules for any and all fields in a document or for specific fields (and their descendants).

Important

When applying read/write rules, the rules at the highest level applies. For a read/write rule for a field to take effect, no rules must exist at a higher level.

For instance, if you have rules both for the document and for specific fields, the document rule determines access to all fields and overrides any specific field rules. Or if you have a rule for a field and a separate rule for one of its nested fields, the rule for the field determines access to all its nested fields and overrides the specific rule for its nested field.

Example

Given documents with the following fields:

{
   _id: 1,
   "title": "Report: Pies",
   "about": { "subject": "pies", "counts": { "pages": 5, "words": 100 } },
   "views":20
}

If a read rule exists for the field about and another rule exists for the field about.counts, the rule for the field about determines the read access for all the fields in about, including the field counts and its nested fields. If instead you want to specify a rule for about.counts.pages, omit rules for about and about.counts.

To specify a rule that applies to any and all fields:

  • Specify the rule on the document. To specify the rule on the document, click on the outermost curly braces, i.e. { or }, for the document.
  • Set Allow All Other Fields to enabled.

To specify a document level rule that applies only to listed fields and their descendants:

  • Specify the rule on the document. To specify the rule on the document, click on the outermost curly braces, i.e. { or }, for the document.

  • Set the Allow All Other Fields in the main document to disabled.

  • In the document, add all the fields that you wish to apply this rule. For each listed field, you must specify its Field Type. If a listed field is an embedded document (i.e. Field Type is Object), you can explicitly add its embedded fields and/or set its Allow All Other Fields accordingly. See Fields Specification for details.

    Tip

    If you want to specify a rule for an embedded field but not the embedded document itself, do not specify a rule at the document level but specify rules at the embedded field level. See Specify rules for specific fields and deny access to unlisted fields.

To specify rules for various fields (and their descendants if any) and deny access to any other fields:

  • Ensure that a rule does not exists at document level.
  • Set the Allow All Other Fields disabled at the document level.
  • In the document, add the field(s) and specify the rules for each field or fields. A rule for a field applies to all its embedded fields, if any. If a listed field is an embedded document, you can either add all its fields or set its Allow All Other Fields to enabled. See Fields Specification for details.

Fields Specification

In the Rules for a namespace, you can explicitly specify the fields in the document and optionally, specify a corresponding rule for a field.

To explicitly specify a field, click + Add, type in the field name, and hit Enter key:

  • If the field is an embedded document, select Field Type of Object.
    • If a write operation attempts to store a primitive value or an array in the field, MongoDB Stitch throws an error.
    • If the stored field value is not a document, a read operation does not return the field.
  • If the field is an array, select Field Type of Array.
    • If a write operation attempts to store a primitive value or a document in the field, MongoDB Stitch throws an error.
    • If the stored field value is not an array, a read operation does not return the field.
  • If the field is not an embedded document or an array, select Field Type of Any.
    • If a write operation attempts to store a document or an array in the field, MongoDB Stitch throws an error.
    • If the stored field value is not a primitive type, a read operation does not return the field.

Embedded Documents and Fields

If the field is an embedded document, select Field Type of Object.

For example, if the documents of a collection contain an embedded document author with content such as the following:

"author": { "first": "P.", "last": "Crust" }
  1. Add the author field.

  2. Select Field Type of Object.

    Note

    If a write operation specifies a primitive-type value for author, MongoDB Stitch returns an error.

  3. For the embedded document, you can list its embedded fields as well

    as enable/disable its Allow All Other Fields setting. For example, you can add the fields "first" and "last" to the author document and set Allow All Other Fields to:

    • enabled to allow unlisted fields in the author document.
    • disabled to allow no other fields in the author document.

Rules Syntax

You can specify rules as JSON documents. MongoDB query expression operators (with the exception of the %text and the geospatial operators) are available for rule expressions.

{
  <field1>: <value1|expression1>,
  <field2>: <value2|expression2>,
  ...
}

To access elements of an array or access fields in an embedded document, use dot notation. For list of MongoDB query operators available, see Query Selectors.

You can also preface the <field> name with an expansion (%%<keyword>):

{
  "<expansion>.<field1>":  <value1|expression1>,
  "<expansion>.<field2>":  <value2|expression2>,
  ...
}

Tip

  • When a field is referenced at the top-level of a document rule, a field name <field> without any expansion is shorthand for %%root.<field>:

    • In a read rule, %%root refers to the document being read.
    • In a write or validation rule, %%root refers to the document after the write operation.

    However , if a compound rule includes nested expressions, you must explictly include the expansion for a field in the nested expressions.

  • When specifying a rule at a field level, you can use %%this to refer to the field; e.g., { "%%this": <value> }.

    • In a read rule for a document, %%this refers to the document being read.
    • In a read rule for a field, %%this refers to the field.
    • In a write rule or validation rule for a document, %%this refers to the document after the write operation.
    • In a write rule for a field, %%this refers to the field after the write operation.

The following table lists some syntax examples:

Syntax Examples Description
{} An empty JSON document evaluates to true. If specified as a document rule, all documents satisfy this read/write rule. If specified as a field rule, the field is always readable/writeable.
{ "%%true": true } The expression always evaluates to true as the value of the expansion %%true equals the boolean true. If specified as a document rule, all documents satisfy this read/write rule. If specified as a field rule, the field is always readable/writeable.
{ "%%true": false } The expression always evaluates to false as the reserved expansion value %%true does not equal the boolean false. If specified as a document rule, no document satisfies this read/write rule. If specified as a field rule, the field is never readable/writeable.
{
  "<field1>": <value1|exp1>,
  "<field2>": <value2|exp2>,
  ...
}

or

{
   "<expansion1>.<field1>": <value1|exp1>,
   "<expansion2>.<field2>": <value2|exp2>,
   ...
}
The compound document/field rule evaluates to true if all conditions are satisfied.
{
  "%or": [
     { "<expansion>.<field1>": <value1|exp1> },
     { "<expansion>.<field2>": <value2|exp2> },
     ...
  ]
}

The compound document/field rule evaluates to true if any of the specified conditions is satisfied.

Note

You must include expansions %%<keyword> to reference fields in the nested rule expressions.