Role document definition

A Role document is accessed by its name and defines privileges and membership associated with a Collection or user-defined function (UDF).

Fields

Field name Value type Description

name

String

(required) Unique role name. The name can’t be events, sets, or self and can’t include the percent (%) character.

membership

Array

(optional) One or more Membership definitions. Fauna evaluates this array only for queries that include a Token document.

privileges

Array

(optional) One or more Privilege definitions, which define the actions permitted on a resource.
Default: No actions are permitted.

coll

Collection

Collection name.

ts

Time

Most recent document update timestamp.

data

Object

(optional) User-defined metadata.

Membership definition

A membership defines privileges for a group. Each array element represents a group and specifies the privileges of the group.

Example definition of two groups:

membership: [
  {
    resource: "Users",
    predicate: 'user => user.isAdmin'
  },
  {
    resource: "Managers"
  },
  ...
]

The required resource references a Collection. Multiple roles can reference the same resource.

The optional predicate specifies a read-only predicate. The predicate evaluates the resource to evaluate if the originator has sufficient query privileges. The predicate must be in long-form syntax. See Anonymous functions.

Privilege definition

The privileges field references a Collection, user-defined Function, or a DatabaseDef resource and defines the actions allowed on that resource.

privileges: [
  {
    resource: "Store",
    actions: {
      create: true,
      read: true,
      write: true,
      delete: true
    }
  },
  {
    resource: "Product",
    actions: {
      create: true,
      read: true,
      write: true,
      delete: true
    }
  },
  ...
]

If referencing a collection, the resource can be a user-defined Collection or the name of one of the following native collections:

  • AccessProvider

  • Collection

  • Credential

  • Database

  • Function

  • Key

  • Role

  • Token

The actions definition applies only to the named resource.

An action is a key:value pair that enables or disables the action by setting the action to true, false, or defining a predicate, and a valid action varies depending on the type of resource:

Action Permission Applicable resource

call

Permit calling a UDF.

UDFs

create

Permit resource creation.

Documents and core schemas, including databases, collections, indexes, functions, and keys

delete

Permit resource deletion.

Documents and core schemas, including databases, collections, indexes, functions, and keys

history_read

(not currently implemented) Permit reads on historical versions of a resource.

Documents

history_write

(not currently implemented) Permit writes to historical versions of a resource.

Documents

read

Permit reads on a resource.

Documents

unrestricted_read

Permit reading an index without considering read permissions.

Indexes

write

Permit writes to a resource.

Documents

Multiple privileges can be defined for separate roles, for a given resource. On a query, the query is processed if any of the privileges grants the action.

Predicate functions

Predicate functions execute with read-only server-level permissions, regardless of the access level of the caller. Predicates have the following parameter requirements depending on the kind of actions:

Action Parameter type Parameter description

create

Object

Document to create. Includes document metadata.

delete

Object

Document to delete. Includes document metadata.

read

Object

Document to read. Includes document metadata.

write

Object, Object

Original document and the document to write. Each object includes document metadata.

call

Array

Parameters to pass to the user-defined function.

See also

Role.create()

Is this article helpful? 

Tell Fauna how the article can be improved:
 Visit Fauna's forums or email docs@fauna.com

Thank you for your feedback!