Docs: Improve documentation on indirect relation permission

[sonalys]

Description

I think it would be good for the library to include examples on authorization regarding indirect relationships.
Example:

• Entities: Organization, User, Folder
• Relations: user -> member -> organization, user -> owner -> folder, folder -> organization -> organization
• Permissions:
  • CanRead: user -> owner -> folder or user -> member -> organization

This is a somewhat essential functionality that ensures some situations works smoothly:

A request in which you only have the userID and folderID, and can authorize through the indirect organization relation without needing the organizationID.

At the moment it's not very clear to someone who is not knowledgeable into the library or zanzibar overall, how that would be implemented.

[pthm]

Here is how you could model what you are describing:

model
    schema 1.1

  type user

  type organization
    relations
      define member: [user]

  type folder
    relations
      define organization: [organization]
      define owner: [user]
      define can_read: owner or member from organization

The key part is member from organization: When checking can_read on a folder:

• Check if the user is the owner of the folder
• OR follow the organization relation and check if the user is a member of that organization

With just userID and folderID the check_permission call will:

• Look up which organization the folder belongs to (via the organization relation)
• Check if the user is a member of that organization

Tuples:
user:alice, member, organization:acme
folder:docs, organization, organization:acme
user:bob, owner, folder:docs

Authorization checks:

• check_permission('user:alice', 'can_read', 'folder:docs') → ✅ (via member from organization)
• check_permission('user:bob', 'can_read', 'folder:docs') → ✅ (via owner)
• check_permission('user:charlie', 'can_read', 'folder:docs') → ❌

Some relevant documentation from the OpenFGA modelling guides:

• https://openfga.dev/docs/modeling/parent-child - Modelling permissions that cascade through parent - child relationships

More relevant documentation:

• https://openfga.dev/docs/modeling/building-blocks/object-to-object-relationships - Foundational concepts
• https://openfga.dev/docs/configuration-language - Full DSL syntax reference including the from operator
• https://openfga.dev/docs/modeling/advanced/gdrive - Real-world example using parent-child patterns

---

You're right that the current Melange specific documentation assumes some level of familiarity with OpenFGA and its modelling concepts / language.

I hoped that this would be somewhat clear and users could refer to the OpenFGA official docs to learn the modelling language rather than re-writing it for Melange as it is the same. The only caveat is that Melange does not support conditionals (ABAC) or some other tooling functionality like modular models, Compatibility is documented here: https://melange.sh/docs/reference/openfga-compatibility/