> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fga.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Modular Models

> Modular Models

Authorization is application-specific. In an organization with multiple teams building different applications or modules, each team should be able to define and evolve their authorization policies independently.

Modular models allows splitting your authorization model across multiple files and modules, improving upon some of the challenges that may be faced when maintaining an authorization model within a company, such as:

* A model can grow large and difficult to understand.
* As more teams begin to contribute to a model, the ownership boundaries may not be clear and code review processes might not scale.

With modular models, a single model can be split across multiple files in a project and organized in a way that makes sense for the project or teams collaborating on it. For example, modular models allows ownership for reviews to be expressed using a feature like [GitHub's](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners), [GitLab's](https://docs.gitlab.com/ee/user/project/codeowners/) or [Gitea's](https://docs.gitea.com/usage/code-owners) code owners.

> [!NOTE]
>
> To use modular models you need to use [FGA CLI](https://github.com/openfga/cli) to maintain authorization models. The Auth0 FGA dashboard will not let you update an authorization model that uses modular models.

## Key Concepts

### `fga.mod`

The `fga.mod` file is the project file for modular models. It specifies the schema version for the final combined model and lists the individual files that make up the modular model.

| Property | Description |
| - | - |
| `schema` | The schema version to be used for the combined model |
| `contents` | The individual files that make up the modular model |

### Modules

Auth0 FGA modules define the types and relations for a specific application module or service.

Modules are declared using the `module` keyword in the DSL, and a module can be written across multiple files. A single file cannot have more than one module.

### Type Extensions

As teams implement features, they might find that core types they are dependent upon might not contain all the relations they need. However, it might not make sense for these relations to be owned by the owner of that type if they aren't needed across the system.

Modular models solves that problem by allowing individual types to be extended within other modules to to share those relations.

The following are requirements for type extension:

* The extended type must exist
* A single type can only be extended once per file
* The relations added must not already exist, or be part of another type extension

## Example

The following example shows how an authorization model for a SaaS compny with a issue tracking and wiki software can implement modular models.

### Core

If there is a core set of types owned by a team that manages the overall identity for the company, the following provides the basics: users, organizations and groups that can be used by each product area.

FGA model · DSL

### Issue tracking

The issue tracking software separates out the project- and issue-related types into separate files. Below, we also extend the `organization` type to add a relation specific to the issue tracking feature: the ability to authorize who can create a project.

FGA model · DSL

FGA model · DSL

### Wiki

The wiki model is managed in one file until it grows. We can also extend the `organization` type again to add a relation tracking who can create a space.

FGA model · DSL

### `fga.mod`

To deploy this model, create the `fga.mod` manifest file, set a schema version, and list the individual module files that comprise the model.

```yaml theme={null}
schema: '1.2'
contents:
  - core.fga
  - issue-tracker/projects.fga
  - issue-tracker/tickets.fga
  - wiki.fga
```

### Putting it all together

With individual parts of the modular model in place, write the model to Auth0 FGA and run tests against it. Below is an example of what to run in the CLI:

```shell theme={null}
fga model write --store-id=$FGA_STORE_ID --file fga.mod
```

This model can now be queried and have tuples written to it, just like a singular file authorization model.

### Viewing the model

When using the CLI to view the combined model DSL with `fga model get --store-id=$FGA_STORE_ID`, the DSL is annotated with comments defining the source module and file for types, relations and conditions.

For example, the `organization` type shows that the type is defined in the `core.fga` file as part of the `core` module, the `can_create_project` relation is defined in `issue-tracker/projects.fga` as part of the `issuer-tracker` module, and the `can_create_space` relation is defined in the `wiki.fga` file as part of the `wiki` module.

FGA model · DSL