docs: add notes on permissions

1 files changed, 37 insertions, 0 deletions

diff --git a/share/man/spicedb/SCHEMA.md b/share/man/spicedb/SCHEMA.md
index 799c28f3..7f66559c 100644
--- a/share/man/spicedb/SCHEMA.md
+++ b/share/man/spicedb/SCHEMA.md
@@ -77,6 +77,43 @@ Relations should be named as nouns.
 
 ## Permissions
 
+A permission defines a computed set of subjects that have a permission of some
+kind on the parent object.
+
+A user can be a reader or writer of a document.
+When a user is a writer of a document they have the view and edit permission on
+the document. When a user is a reader of a document they have the view
+permission on the document.
+
+```spicedb
+definition user {}
+
+definition document {
+  relation writer: user
+  relation reader: user
+
+  permission edit = writer
+  permission view = reader + writer
+}
+```
+
+### Operators
+
+- `+`: Union operator to join different relations or permissions
+- `&`: Intersection operator to find relations or permissions with both sets.
+- `-`: Exclusion operator to exclude relations/permissions on the right.
+- `->`: Array operator for walking a hierarchy of relations defined for an object of a subject.
+
+### Naming
+
+Permissions should be named as verbs or nouns.
+
+* `is/can {permission name} (the object)`
+* can `read` the object
+* can `write` the object
+* can `delete` the object
+* is `member` of the object
+
 ## Resources
 
 * https://authzed.com/docs/spicedb/concepts/schema