Concepts: Objects & Relations

A Relation is a defined name in a Namespace that indicates the relationship between two objects.

Typically a relation is used to represent a role (such as read or write) between a resource object (e.g. a document) and a user, indicating that the user has that role on the object.

Relations are also used to represent non-role based relationships between objects, such as a user belonging to a group.

Defining a relation#

A relation is defined in a Namespace:

name: "thetenant/myresource"
relation { name: "thenameoftherelation" }

Relation rules#

By default, a relation is resolved in Check and Expand by only returning the tuples found directly on the relation.

Relations can have their rules changed, however, by defining a userset_rewrite under the relation:

relation {
name: "read"
userset_rewrite {
union {
child { _this {} }
child {
computed_userset { relation: "write" }

In the above example, the relation read has its userset redefined to be the union of _this (the relation itself) and the userset from write, which indicates that all users granted write permission should also be granted, implicitly, the read permission as well.


An object is the item "stored under" a relation by Writing a tuple with that relation and object ID.

For example, given a resource "myresource" with object ID myresource, we could write that it is under an organization by writing a tuple such as:


In the above example tuple, theorganization and myresource are the objects, with theorganization being an object of the namespace organization, and myresource being an object of the namespace resource.

The ... relation#

The ... relation is a special relation implicitly defined on all namespaces.

It is used to reference a namespace as a whole, typically when you have a namespace defined to represent a user or resource and want to include that user or resource in another relation.