OpenFGA Best Practices

Use this skill to design and review OpenFGA models end to end: define types and relations, write tuples, derive can_* permissions, choose usersets and inheritance patterns, and validate behavior with .fga.yaml tests and CLI checks.

Quick Start Example

Minimal model:

model
  schema 1.1

type user

type organization
  relations
    define admin: [user]
    define member: [user] or admin

type document
  relations
    define organization: [organization]
    define owner: [user]
    define can_edit: owner or admin from organization
    define can_view: can_edit or member from organization

Example tuples:

organization:acme#admin@user:alice
document:roadmap#organization@organization:acme
document:roadmap#owner@user:bob

Example test targets:

• check that user:alice can view and edit document:roadmap
• check that user:bob can edit their own document
• list_users for document:roadmap#can_view
• list_objects for documents user:alice can edit

How to Use

When a workflow step points to a rule ID, open the matching file in references/ for detailed guidance and examples.

Note: SDK references (sdk-*.md) are only needed for integration tasks — skip them during pure model authoring and testing.

Rule Index

Core

Relations

Design

Roles

Optimization

Testing

SDKs (for integration tasks only)

Recommended Workflow

1. Model the resource graph. Define types, direct relations, inheritance edges, and can_* permissions. Rules to check first: core-*, relation-*, design-permissions, design-hierarchy.

2. Add tuples and test intent. Add representative tuples and cover expected behavior with check, list_objects, and list_users tests. Rules to check next: core-tuples, test-fga-yaml, test-check-assertions, test-list-objects, test-list-users.

3. Review parent-child creation and deletion paths. Verify each parent -> child edge has create permissions on the parent and that no child permission is directly grantable unless intended. Rules to check: design-create-on-parent, relation-direct, design-permissions.

4. Simplify before removing schema. Before deleting any type or relation, confirm it is not referenced by permissions, tuples, or tests. If a simplification breaks a reference: restore the relation or update the model/tests, then re-run this step. Rules to check: optimize-simplify, optimize-tuples, optimize-type-restrictions.

5. Validate the model. Run:

fga model validate --file stores/<store>/model.fga

If validation fails: read the reported relation or type errors, fix the model, and re-run validation before continuing.

6. Run the store tests. Run:

fga model test --tests stores/<store>/store.fga.yaml

If tests fail: update tuples, assertions, or permission definitions, then re-run tests until all checks and list queries pass.

7. Only then finalize delivery. For touched stores, finish only after validation and tests are green. Final rule to check: workflow-validate.

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md