Role document definition

Field name Value type Description

Field name	Value type	Description
`name`	String	Role name. It can be any string except for `events`, `sets`, or `self` and any string that includes the `%` percent character.
`membership`	Array	One or more optional membership configurations. These configurations dynamically define which documents have the `privileges`. Fauna evaluates this array only for queries that include a `Token` document. See Membership configuration.
`privileges`	Array	One or more optional privilege configurations. A configuration defines the `actions` permitted for a `resource`. The array is a whitelist]. All queries use role privileges to authorize actions. The default `privileges` is that no actions are permitted. See the Privilege configuration.
`coll`	Collection	Document collection name.
`ts`	Time	Most recent document update timestamp.
`data`	Object	(Optional) Object with metadata fields.

name

Role name. It can be any string except for events, sets, or self and any string that includes the % percent character.

membership

Array

One or more optional membership configurations. These configurations dynamically define which documents have the privileges. Fauna evaluates this array only for queries that include a Token document. See Membership configuration.

privileges

Array

One or more optional privilege configurations. A configuration defines the actions permitted for a resource. The array is a whitelist]. All queries use role privileges to authorize actions. The default privileges is that no actions are permitted. See the Privilege configuration.

coll

Collection

Document collection name.

ts

Time

Most recent document update timestamp.

data

Object

(Optional) Object with metadata fields.

Membership configuration

A membership is an array that dynamically grants the privileges. Each array element specifies a collection resource and an optional predicate.

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

The resource is a String referencing a Collection name. All the collection documents make up the role membership. A resource can be any Fauna collection, though typically, it is a user-defined collection of Fauna users. Multiple roles can reference the same resource.

The predicate is an optional field. It specifies a read-only lambda predicate Function. The predicate evaluates the resource document and returns a Boolean value that indicates if the caller querying is allowed the privilege.

For example, Fauna Key collection can be the resource, and the predicate function can evaluate the key name to grant privileges only to key documents with the string report_process in their name.

Privilege configuration

A privileges array configures one or more resource and the actions permitted on that resource.

  privileges: [{
    resource: "Collection",
    actions: {
          delete: false
          create: 'data => "Foo" == data.name',
          call: '(arg1, arg2) => arg1 == 1 && arg2 == 2'
      }
    }
  ...

A resource name is a String type referencing a collection, user-defined function (UDF), or database name. If referencing a collection, the resource can be a user-defined Collection or the name of a native collection. The native collections are the following:

AccessProvider
Collection
Credential
Database
Function
Key
Role
Token

The actions apply only to the resource and its contents. Actions do not apply to the contents of the contents.

For example, setting resource: Collection grants or denies privileges on all of the user-defined collections but not to the documents in those collections. To grant permissions to documents in a collection, define a collection by name as a resource.

The actions is an Object with one or more key-value pairs. The available actions vary depending on the target resource. The key can be any of the following:

Key Grants Available resources

Key	Grants	Available resources
`create`	Create object.	Documents and core schemas, including databases, collections, indexes, functions, and keys.
`delete`	Delete object.	Documents and core schemas, including databases, collections, indexes, functions, and keys.
`read`	Read documents.	Documents.
`write`	Write documents.	Documents.
`call`	A user-defined function (UDFs).	User-defined functions.

create

Create object.

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

delete

Delete object.

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

read

Read documents.

Documents.

write

Write documents.

Documents.

call

A user-defined function (UDFs).

User-defined functions.

Each key takes a value that must be a Boolean or a read-only lambda predicate function that returns a Boolean. A value of true grants the key permission, and false denies it. The predicate must be in long form syntax.

Multiple privileges can be defined on separate roles for a given resource. When a query tries to act on a resource, the action is processed if any privilege grants the action.

Predicate functions execute with read-only server-level permissions, regardless of the access level of the caller. They execute this way because the function needs access to all declared resources to verify privilege.

Each permission key requires distinct function parameters. For example, the write key requires a function with two parameters, while a read function requires one parameter. The following table lists each possible key and the requirements for its corresponding function:

Key Parameter types Description

Key	Parameter types	Description
`create`	Object	Object with the new document data.
`create_with_id`	Object	Object with the new document data.
`delete`	String, Object	Reference to the document or a document object to be deleted.
`read`	String, Object	Reference to the document or a document object to be read.
`write`	Object, Object	An `Object` with the original document data and an `Object` with the new document data to be written.
`call`	Array	Parameters to be passed to the user-defined function.

create

Object

Object with the new document data.

create_with_id

Object

Object with the new document data.

delete

String, Object

Reference to the document or a document object to be deleted.

read

String, Object

Reference to the document or a document object to be read.