docs: add notes on spiced schema

1 files changed, 82 insertions, 0 deletions

diff --git a/share/man/spicedb/SCHEMA.md b/share/man/spicedb/SCHEMA.md
new file mode 100644
index 00000000..799c28f3
--- /dev/null
+++ b/share/man/spicedb/SCHEMA.md
@@ -0,0 +1,82 @@
+# SpiceDB Schema
+
+## Object Type
+
+> An Object Type definition is used to represent a new type of object.
+
+This is like a class definition in a OOP language.
+
+```spicedb
+definition user {}
+
+definition document {}
+
+```
+
+## Caveat
+
+This a condition that can be applied to a relationship. The relationship is only
+considered present if the caveat evaluates to true at query time
+
+## Relation
+
+Defines how two objects (or an object and subject) can relate to one another.
+
+A user can read a document if they are a reader of the document.
+A document can be read by readers.
+
+```spicedb
+defintion user {}
+
+definition document {
+  relation reader: user
+}
+```
+
+### Subject Relation
+
+Relations can also "contain" references to other relations/permissions.
+
+A user can be a member of a group A.
+The members of group B can be members of a group A.
+
+```spicedb
+definition user {}
+
+definition group {
+  relation member: user | group#member
+}
+```
+
+### Wildcards
+
+A relation can specify a wildcard to indicate that a grant can be made to the
+resource type as a whole.
+
+All users can view the resource.
+The resource is viewable by all users.
+
+```spicedb
+definition user {}
+
+definition resource {
+  relation viewer: user | user:*
+}
+```
+
+### Naming
+
+Relations should be named as nouns.
+
+* `{relation name} (of the object)`
+
+* `reader` of the document
+* `writer` of the document
+* `member` of the group
+* `parent` of the group
+
+## Permissions
+
+## Resources
+
+* https://authzed.com/docs/spicedb/concepts/schema