> ## 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.

# Modeling Parent-Child Objects

> Indicate relationships between objects, and how users' relationships to one object can affect their relationship with another

In Auth0 FGA, a user's [relationship](https://docs.fga.dev/fga-concepts.md#what-is-a-relationship) with an [object](https://docs.fga.dev/fga-concepts.md#what-is-an-object) can affect their relationship with another object. For example, an `editor` of a `folder` can also be an `editor` of all `documents` that `folder` is a `parent` of.

**When to use**

Object-to-object relationships can combine with a configured authorization model to indicate that a user's relationship with one object may influence the user's relationship with another object. They can also eliminate the need to modify relationships between objects using [user groups](https://docs.fga.dev/modeling/basics/user-groups.md#step-3).

The follow are examples of simple object-to-object relationships:

* `managers` of an `employee` have access to `approve` requests the `employee` has made
* users who have a repository admin role (`repo_admin`) in an organization automatically have `admin` access to all repositories in that organization
* users who are `subscribed` to a `plan` get access to all the `features` in that `plan`

## Before you start

Familiarize yourself with basic [Auth0 FGA Concepts](https://docs.fga.dev/fga-concepts.md):

<details>
  <summary>
    Assume that you have the following [authorization model](https://docs.fga.dev/fga-concepts.md#what-is-an-authorization-model).\\

    You have two types:

    * `folder` that users can be related to as an `editor`
    * `document` that users can be related to as an `editor`
  </summary>

  ***

  In addition:

  ### Direct access

  Creating an authorization model and a relationship tuple can grant a user access to an object. To learn more, [read about Direct Access](https://docs.fga.dev/modeling/basics/modeling-basics.md)

  ### Auth0 FGA concepts

  * A [Type](https://docs.fga.dev/fga-concepts.md#what-is-a-type): a class of objects that have similar characteristics
  * A [User](https://docs.fga.dev/fga-concepts.md#what-is-a-user): an entity in the system that can be related to an object
  * A [Relation](https://docs.fga.dev/fga-concepts.md#what-is-a-relation): a string defined in the type definition of an authorization model that defines the possibility of a relationship between an object of the same type as the type definition and a user in the system
  * An [Object](https://docs.fga.dev/fga-concepts.md#what-is-an-object): represents an entity in the system. Users' relationships to it can be define through relationship tuples and the authorization model
  * A [Relationship Tuple](https://docs.fga.dev/fga-concepts.md#what-is-a-relationship-tuple): a group stored in Auth0 FGA that consists of a user, a relation, and an object
  * [Union Operator](https://docs.fga.dev/modeling/configuration-language.md#the-union-operator): can be used to indicate that the user has multiple ways of being related to an object
</details>

[The Playground
Try this guide out on the Auth0 FGA Playground](https://play.fga.dev/)

## Step by step

The following walkthrough models (a) folders that contain documents and (b) that a user who has editor access to a given folder has editor access to all documents in that folder.

For `editors` of a `folder` to be `editors` of a containing `document`, you must:

1. Update the authorization model to allow a `parent` relationship between `folder` and `document`
2. Update the `editor` relation in the `document` type definition to support cascading from `folder`

The following three steps indicate and verify that `bob` is an `editor` of `document:meeting_notes.doc` because `bob` is an `editor` of `folder:notes`:

3. Create a new *relationship tuple* to indicate that **bob** is a `editor` of **folder:notes**
4. Create a new *relationship tuple* to indicate that **folder:notes** is a `parent` of **document:meeting\_notes.doc**
5. Check to see if **bob** is an `editor` of **document:meeting\_notes.doc**

### 01. Update the Athorization Model to allow a parent relationship between folder and document

As documented in [Modeling Concepts: Object to Object Relationships](https://docs.fga.dev/modeling/concepts/object-to-object-relationships.md), the following update to the authorization model allows a `parent` relation between a `folder` and a `document`:

> [!NOTE]
>
> The `document` type now has a `parent` relation, indicating that other objects can be `parent`s of `document`s

### 02. Update the editor relation in the document type definition to support cascading from folder

To allow cascading relations between `folder` and `document`, update the authorization model:

> [!NOTE]
>
> `editor` of a `document` can be the following:
>
> 1. users that are directly assigned as editors
> 2. users that are related to any `parent` of this document as `editor` (editors of the parent)

After making these changes, anyone related to a `folder` that is a `parent` of a `document` as an `editor` is also an `editor` of that `document`.

### 03. Create a new relationship tuple to indicate that `bob` is an `editor` of `folder:notes`

To leverage the new cascading relation, create a relationship tuple stating that `bob` is an `editor` of `folder:notes`

> [!WARNING]
>
> Use unique ids for each object and user within your application domain when creating relationship tuples for Auth0 Fine-Grained Authorization (FGA). We are using first names and simple ids to illustrate an easy-to-follow example.

### 04. Create a new relationship tuple to indicate that `folder:notes` is a `parent` of `document:meeting_notes.doc`

Now that `bob` is an `editor` of `folder:notes`, we need to indicate that **folder:notes** is a `parent` of `document:meeting_notes.doc`

### 05. Check if `bob` is an `editor` of `document:meeting_notes.doc`

After changing the authorization model and adding two new relationship tuples, verify that your configuration is correct by running the following check: **is bob an editor of document:meeting\_notes.doc**.

> Note: There are no other relationship tuples in the store that dictate a direct relation between `bob` and `document:meeting_notes.doc`. The check succeeds because of the cascading relation.

The chain of resolution is:

* `bob` is an `editor` of `folder:notes`
* `folder:notes` is a `parent` of `document:meeting_notes.doc`
* `editors` of any `parent` `folder` of `document:meeting_notes.doc` are also `editors` of the `document`
* therefore `bob` is an `editor` of `document:meeting_notes.doc`

> [!WARNING]
>
> When searching tuples that are related to the object (the word after `from`, also called the tupleset), Auth0 Fine-Grained Authorization (FGA) will not do any evaluation and only considers concrete objects (of the form `<object_type>:<object_id>`) that were directly assigned. Auth0 Fine-Grained Authorization (FGA) will throw an error if it encounters any rewrites, a `*`, a type bound public access (`<object_type>:*`), or a userset (`<object_type>:<object_id>#<relation>`).
>
> For more information on this topic, see [Referencing Relations on Related Objects](https://docs.fga.dev/modeling/configuration-language.md#referencing-relations-on-related-objects).

## Related Sections

Check the following sections for more on how to model for parent and child objects.

[Modeling Concepts: Object to Object Relationships
Learn about how to model object to object relationships in Auth0 FGA.](https://docs.fga.dev/modeling/concepts/object-to-object-relationships.md)

[Modeling Google Drive
See how to make folders parents of documents, and to make editors on the parent folders editors on documents inside them..](https://docs.fga.dev/modeling/advanced/use-cases/gdrive.md#01-individual-permissions)

[Modeling GitHub
See how to grant users access to all repositories owned by an organization.](https://docs.fga.dev/modeling/advanced/use-cases/github.md#01-permissions-for-individuals-in-an-org)