Wiki.Quizz.vn

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== OpenFGA DSL Syntax: Keywords vs Names ======

In the DSL there are two kinds of words: **keywords** you must type exactly, and
**names** you make up (or point to). Symbols like '':'' and ''[ ]'' are also fixed.

===== Keywords (fixed — you cannot change them) =====

Built-in words. Spell them exactly.

^ Keyword ^ What it does ^
| ''model'' | Starts the file. |
| ''schema'' | Comes with the version, like ''schema 1.1''. |
| ''type'' | Starts a new type. |
| ''relations'' | Starts the list of relations for a type. |
| ''define'' | Starts one relation. |
| ''or'', ''and'', ''but not'' | Combine relations. |
| ''from'' | Inherit through a link. |

===== Names (values — you choose these) =====

Words //you// invent to fit your app.

  * **Type names**: ''user'', ''document'', ''folder'', ''organization''. You could call them ''person'' or ''file'' instead.
  * **Relation names**: ''owner'', ''editor'', ''viewer'', ''parent'', ''member''. You pick these too.

There is a small twist. Sometimes you //create// a name, and sometimes you
//refer// to a name you already made.

  * ''define viewer: ...'' → here you **create** the name ''viewer''.
  * ''... or owner'' → here you **refer** to ''owner'', which must already exist.
  * ''[user]'' → ''user'' must be a type you already defined.

===== Symbols (fixed punctuation) =====

  * '':'' after a relation name — required.
  * ''[ ]'' around allowed types — required for a direct relation.
  * ''#'' — used in tuples, like ''group:eng#member'' (not in the model itself).

===== One line, broken into parts =====

Take this line:

<code>
define viewer: [user] or owner
</code>

^ Token ^ Kind ^ Note ^
| ''define'' | keyword | fixed word |
| ''viewer'' | name | you **create** it here |
| '':'' | symbol | required |
| ''['' | symbol | required |
| ''user'' | name | a type that must already exist |
| '']'' | symbol | required |
| ''or'' | keyword | fixed word |
| ''owner'' | name | a relation that must already exist |

===== The general shape =====

Uppercase = keywords (fixed). ''<...>'' = names you supply.

<code>
MODEL
  SCHEMA 1.1

TYPE <your type name>
  RELATIONS
    DEFINE <your relation name>: [<allowed type>] OR <another relation>
</code>

===== The keywords as concepts =====

Each keyword plays one clear role. Think of building the model top to bottom:
first the file, then a type, then its relations, then each rule.

==== model ====

**Concept:** the start of the whole file. It wraps everything.

You write it once, at the very top. Nothing lives outside it.

<code>
model
  schema 1.1
</code>

==== schema ====

**Concept:** the DSL version number. It tells OpenFGA which grammar to use.

Always pair it with a version, like ''1.1''. Put it right under ''model''.

<code>
schema 1.1
</code>

==== type ====

**Concept:** a //kind of thing// in your system.

A type is a category of object, like a user, a document, or a folder. You will
have one ''type'' block for each kind of thing. The name after ''type'' is yours to
choose.

<code>
type document
</code>

Read it as: **"documents are a kind of thing in this system."**

==== relations ====

**Concept:** the heading that opens the list of links for a type.

It has no rule of its own. It just says "the rules for this type start here."
Everything indented under it belongs to that type.

<code>
type document
  relations
    define owner: [user]
    define viewer: [user] or owner
</code>

Read it as: **"here come the relations that documents can have."**

==== define ====

**Concept:** one single rule (one relation).

Each ''define'' line creates one named link and says who can have it. You will have
many ''define'' lines under ''relations''.

<code>
define owner: [user]
</code>

Read it as: **"define a link called //owner//; a user can be assigned to it."**

==== or / and / but not ====

**Concept:** ways to combine relations into one rule.

  * ''or'' — this **or** that (widest access).
  * ''and'' — this **and** that (both required).
  * ''but not'' — this **except** that (takes access away).

<code>
define editor: [user] or owner
define can_delete: owner and admin
define viewer: [user] but not blocked
</code>

==== from ====

**Concept:** inherit access through a link to another object.

It lets access flow between objects. You name a link to follow, then a relation
to check on the other side.

<code>
define viewer: viewer from parent
</code>

Read it as: **"you are a viewer here if you are a viewer of the //parent//."**

===== How they nest =====

The keywords stack inside each other, shown by indentation:

<code>
model                         ← the whole file
  schema 1.1                  ← the DSL version
                              
  type document               ← a kind of thing
    relations                 ← its links start here
      define owner: [user]    ← one rule
      define editor: [user] or owner   ← one rule, using "or"
</code>

<note tip>
Reading order: ''model'' → ''schema'' → ''type'' → ''relations'' → ''define''.
Outer keywords set the container; inner ones fill in the detail.
</note>

===== More examples to read =====

The trick to reading a relation is to say it out loud in plain words. Below, the
left side is the DSL, the right side is how you say it.

==== Direct grant ====

<code>
define owner: [user]
</code>

Read it as: **"a user can be assigned as the owner."** \\
Keyword: ''define''. Names: ''owner'', ''user''. This one needs a tuple to be true.

==== Union with ''or'' ====

<code>
define editor: [user] or owner
</code>

Read it as: **"an editor is a user assigned directly, //or// anyone who is already
an owner."** \\
So every owner is also an editor, for free.

==== More than one allowed type ====

<code>
define member: [user, group#member]
</code>

Read it as: **"a member can be a single user, //or// every member of a group."** \\
The comma lists two allowed types. ''group#member'' means "the members of a group."

==== Public access with a wildcard ====

<code>
define viewer: [user:*]
</code>

Read it as: **"every user can view this."** \\
The ''*'' is a wildcard. Use it for public things.

==== Both must be true with ''and'' ====

<code>
define can_delete: owner and admin
</code>

Read it as: **"you can delete only if you are //both// an owner //and// an admin."** \\
''and'' means both conditions must hold at the same time.

==== Take away with ''but not'' ====

<code>
define viewer: [user] but not blocked
</code>

Read it as: **"a viewer is any assigned user, //except// anyone who is blocked."** \\
''but not'' removes people, even if they would otherwise qualify.

==== Inherit through a link with ''from'' ====

<code>
define viewer: viewer from parent
</code>

Read it as: **"you can view this if you are a viewer of its parent."** \\
Follow the ''parent'' link, then check ''viewer'' on whatever you land on.

==== Everything combined ====

<code>
define viewer: [user] or editor or viewer from parent
</code>

Read it as: **"a viewer is a user assigned directly, //or// an editor, //or// a
viewer of the parent folder."** \\
This is the common real-world pattern: direct people, higher roles, and inherited
folder access all at once.

===== Quick reading table =====

^ DSL ^ Read it as ^
| ''[user]'' | assigned directly, needs a tuple |
| ''[user, team#member]'' | a user, or every member of a team |
| ''[user:*]'' | everyone (public) |
| ''or owner'' | also counts if you are an owner |
| ''and admin'' | only if you are also an admin |
| ''but not blocked'' | unless you are blocked |
| ''viewer from parent'' | if you are a viewer of the parent |

<note tip>
Rule of thumb: ''[ ]'' means a //direct// grant (a tuple sets it). A bare relation
name means a //computed// grant (worked out from other relations, no tuple needed).
</note>

===== See also =====

  * [[security:authorization:openfga:authorization-model|Authorization model]]
  * [[security:authorization:openfga:relationship-tuples|Relationship tuples]]