Differences

This shows you the differences between two versions of the page.

--- security:authorization:openfga:authorization-model:keyword-vs-name [2026/07/09 04:15] – created phong2018
+++ security:authorization:openfga:authorization-model:keyword-vs-name [2026/07/09 04:36] (current) – phong2018
@@ Line 67: / Line 67: @@
     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 =====
@@ Line 72: / Line 283: @@
   * [[security:authorization:openfga:authorization-model|Authorization model]]
   * [[security:authorization:openfga:relationship-tuples|Relationship tuples]]
-  * [[https://openfga.dev/docs/configuration-language|Configuration language (DSL)]]