Defining a Schema

The ReBAC schema is comprised of three main components:

Namespaces: Top-level entities in your application, like documents, folders, and organizations
Relation definitions: Define the possible relationships between namespaces, like a user being a member of an organization
Relations: The actual relationships between specific entities, like a specific user being a member of a particular organization

The general flow of defining a schema involves creating namespaces and relation definitions.

Schema Templates

The templates will only appear if you do not have a pre-existing schema present. You can remove the schema by clicking the delete (trashcan) button in the top right corner of the schema editor.

The Descope Console provides several pre-built schema templates to help you get started quickly. You can access these templates in the Console under the FGA tab.

Understanding the DSL (Domain-Specific Language)

The ReBAC schema uses a Domain-Specific Language (DSL) to define your authorization model. Understanding the DSL syntax is essential for creating effective schemas.

Schema Structure

Every schema begins with a model declaration:

model AuthZ 1.0

This declares that you're using the AuthZ 1.0 model format.

Types

Types represent the entities in your system. They are the building blocks of your authorization model:

type user
type account
type folder

Types can be simple (like user) or complex with relations and permissions (like account or folder).

Relations

Relations define direct relationships between entities. They specify who or what can have a particular relationship with a resource.

Basic Relations

type account
  relation owner: user
  relation manager: user

This defines that an account can have an owner relation to a user, and a manager relation to a user.

Union Relations (OR)

You can define that a relation can be satisfied by multiple types using the union operator (|):

type account
  relation owner: user | group

This means an account's owner can be either a user or a group.

Relation References

You can reference relations from other types using the # operator:

type account
  relation owner: user | Group#member

This means an account's owner can be:

A direct user
A Group that has a member relation (which resolves to users who are members of that group)

Self-Referential Relations

Types can reference themselves to create hierarchical structures:

type folder
  relation parent: folder

This allows folders to have parent folders, creating a folder hierarchy.

Permissions

Permissions define what actions can be performed. They are computed from relations and can reference other permissions.

Basic Permissions

type account
  relation owner: user
  permission can_close: owner

This defines a can_close permission that is granted to the account's owner.

Permission Composition (OR)

Permissions can be composed using the union operator (|):

type account
  relation owner: user
  relation manager: user
  permission can_withdraw: owner | manager

This means can_withdraw is granted if the user is either the owner OR the manager.

Permission Chaining

Permissions can reference other permissions:

type account
  relation owner: user
  relation manager: user
  permission can_withdraw: owner | manager
  permission can_view: can_withdraw | beneficiary

The can_view permission is granted if:

The user has can_withdraw permission (which means they're owner or manager), OR
The user is a beneficiary

Traversing Relations

You can traverse relations using dot notation:

type account
  relation managed_by: branch
 
type branch
  relation manager: user
 
type account
  permission can_withdraw: managed_by.manager

This means can_withdraw is granted to users who are managers of the branch that manages the account.

Complex Permission Examples

type folder
  relation parent: folder
  relation owner: user
  relation editor: user
  
  permission can_edit: editor | parent.owner | parent.can_edit

This permission is granted if:

The user is a direct editor of the folder, OR
The user is the owner of the parent folder, OR
The user has can_edit permission on the parent folder (which recursively checks up the hierarchy)

DSL Syntax Summary

Syntax	Description	Example
`type <name>`	Define a type	`type user`
`relation <name>: <type>`	Define a relation	`relation owner: user`
`\|`	Union (OR) operator	`user \| group`
`#`	Relation reference	`Group#member`
`.`	Traverse relation	`parent.owner`
`permission <name>: <expression>`	Define a permission	`permission can_edit: owner`

Complete Schema Example

For a complete, real-world schema example, see the Google Drive example which demonstrates a document platform with hierarchical folder structures, file permissions, and permission inheritance.

Managing Your Schema

You can learn how to insert your schema into Descope and manage it on the Managing a Schema page.

Was this helpful?

On this page