WorkOS Docs Homepage
Fine-Grained Authorization
API referenceDashboardSign In

Schema

Define application authorization logic independently from application code using a domain-specific language (DSL).

Overview

A schema is the fundamental building block of any authorization model in FGA. Like a database schema, each schema in FGA defines what kinds of resources exist in an application. More importantly, a schema also defines what permissions users can have on those resources and how permissions can be inherited under certain conditions.

Every schema is defined using the FGA schema language, a domain-specific language (DSL) designed to express authorization logic in a developer-friendly format.

Managing authorization logic as a schema makes it easy to evolve your authorization logic independently from your application logic over time. You can manage a schema alongside application code with a version control system like Git and apply it using the CLI:

Once applied, a new schema takes effect immediately. In other words, any change in authorization logic will immediately be reflected in subsequent permission checks and queries.

Schema Language

Version

Each schema must start with a version declaration. This version declaration dictates the version of the schema language the transpiler will use to convert the schema into its JSON representation. As we add support for new features and functionality to the schema language, we will release new versions of it. Versioning the language in this way allows us to ensure backwards compatibility as we roll out these enhancements. See a full changelog of schema versions here.

Resource Types

Resource types are the building blocks of your authorization model. They represent different types of entities in your application. For example users, organizations, stores, items, etc. See more information about resource types here.

To define a resource type, use the type keyword followed by the name of the resource type.

Relations

Relations are a specific type of connection between two resources. Relations define how a subject can access a resource. For instance, the user resource type might define a manager relation. The manager relation authorizes certain users to access employee information for a user.

To define a relation for a resource type, use the relation keyword followed by the name of the relation. Optionally, you can add the type(s) of resources the service can assign to the relation.

Use brackets [] after the relation name for resource type checking. The resource type can be empty, a single type, or an array of types. Type checking occurs at runtime when your application calls the service create warrants. The server validates that warrants have proper subject types. The service also checks types when applying a new schema to confirm that inheritance rules are valid.

Use empty resource types to define computed relationships with no direct subjects. Such as a relation inherited from other relations.

Version 0.1 of the schema language does not support type safety on relations.

In this example, the manager relation indicates that only a user can be a manager of another user.

In this example, the computed relation is inherited if either the editor or manager relation exists. You cannot assign a subject to the computed relation directly.

Inheritance Rules

Use inheritance rules to define how certain relations are granted implicitly based on the existence of other relations. They are useful for expressing hierarchical relationships without having to explicitly define every possible relation as a warrant.

There are two types of inheritance rules:

  • Relation Inheritance: Rules that are inherited if a separate relation exists on the same resource. e.g. admins are also managers
  • Resource Inheritance: Rules that are inherited if a separate relation exists on a different resource. e.g. owners of parent are owners of child

To define an inheritance rule, use the inherit keyword followed by the name of the inherited relation. On the next line add a condition that the subject should meet in order for the inheritance to occur.

In this example, the viewer relation is inherited if the editor relation exists for a subject.

Relation Inheritance

Use relation inheritance to inherit from another relation within the same resource type. This is useful when you want to create hierarchical relationships. One common use case is to inherit the viewer relation if the editor relation exists.

To define a relation inheritance rule, specify the relation to inherit, and the relation to inherit based on.

In this example, the viewer relation is inherited if the editor relation exists. The editor relation is inherited if the owner relation exists.

Resource Inheritance

Use resource inheritance to inherit from a relation in another resource type. This is useful when you want to create hierarchical relationships between different resource types.

To define a resource inheritance rule, specify the relation, the resource type to inherit from, and the relation to inherit based on.

In this example, the owner relation on an item is inherited if all of the following conditions are met

  • The subject has the owner relation on the parent.
  • The subject owner parent is a store.

Logical Operators

Use logical operators to combine multiple inheritance conditions. The supported operators are all_of, any_of, and none_of. They behave the same as JSON resource type inheritance rules.

In this example, the editor relation is inherited if either of the following conditions are met:

  • The owner relation exists on the item type (relation inheritance).
  • The manager relation exists on the owner if the owner is a user (resource inheritance).

You can also nest logical operators to define complex relationships between resource types. Here’s an example:

In this example, the schema defines an editor relationship that is granted if any of the following conditions are met:

  • The subject is an owner.
  • The subject is an editor on the parent store.
  • The subject is both a viewer on the parent store and a manager on the owner user.

Comments

Comments are prefixed with //. Comments are ignored by the transpiler.

Example

Here is an example schema that incorporates resource types, relations, inheritance rules, and logical operators:

Changelog

v0.2

  • Add support for resource-type relation type safety

v0.1

  • Initial implementation of the schema language
  • Supported features:
    • Transpiler version
    • Resource types
    • Relations
    • Inheritance rules
    • Resource inheritance
    • Logical operators
WarrantsWarrants specify relationships between resources in your application
Up next