diff --git a/pages/spicedb/concepts/schema.mdx b/pages/spicedb/concepts/schema.mdx
index 632d0508..f707356b 100644
--- a/pages/spicedb/concepts/schema.mdx
+++ b/pages/spicedb/concepts/schema.mdx
@@ -1,6 +1,6 @@
-import { Callout } from 'nextra/components'
+import { Callout } from 'nextra/components';
import YouTube from 'react-youtube';
-import { InlinePlayground } from '@/components/playground'
+import { InlinePlayground } from '@/components/playground';
# Schema Language
@@ -12,7 +12,8 @@ You can experiment with schemas in real-time with the [Playground](https://play.
The following video provides an overview of schema development using the Playground:
-
+
+
After studying this page's content, you may want to also read the [Developing a Schema] doc.
@@ -22,7 +23,6 @@ After studying this page's content, you may want to also read the [Developing a
The top level of a Schema consists of zero or more [Object Type definitions](#object-type-definitions) and [Caveats](./caveats).
-
```zed
/**
* somecaveat is a caveat defined
@@ -38,8 +38,9 @@ definition someobjecttype {}
```
- Note that the examples are unprefixed.
- You'll need to add the prefix from your permissions system if calling `WriteSchema` for a permissions system hosted in Serverless.
+ Note that the examples are unprefixed. You'll need to add the prefix from your
+ permissions system if calling `WriteSchema` for a permissions system hosted in
+ Serverless.
### Object Type Definitions
@@ -84,7 +85,8 @@ definition document {
In the above example, the `user` on `reader` does not contain a sub-relation
- Occasionally you will see a subject which has a sub-relation such as `usergroup:admins#members` which refers not just to the `usergroup` as a whole, but the set of members which have that relation to the `usergroup`.
+Occasionally you will see a subject which has a sub-relation such as `usergroup:admins#members` which refers not just to the `usergroup` as a whole, but the set of members which have that relation to the `usergroup`.
+
### Subject Relations
@@ -105,7 +107,8 @@ definition group {
```
- Subject Relations are useful in RBAC-style permissions systems to grant "roles" to _sets_ of subjects, such as the members of a team.
+ Subject Relations are useful in RBAC-style permissions systems to grant
+ "roles" to _sets_ of subjects, such as the members of a team.
### Wildcards
@@ -134,8 +137,8 @@ resource:someresource viewer user:*
Now _any_ user is a `viewer` of the resource.
- Be **very careful** with wildcard support in your schema!
- **Only** grant it to read permissions, unless you intend to allow for universal writing.
+ Be **very careful** with wildcard support in your schema! **Only** grant it to
+ read permissions, unless you intend to allow for universal writing.
### Naming Relations
@@ -218,7 +221,7 @@ permission can_only_read = reader - writer
#### `->` (Arrow)
-Arrows allow for "walking" the heirarchy of relations (and permissions) defined for an object, referencing a permission or relation on the _resulting_ object.
+Arrows allow for "walking" the heirarchy of relations (and permissions) defined for an **object** of a subject, referencing a permission or relation on the _resulting_ subject's object.
For example, imagine a schema where a document is found under a folder:
@@ -283,8 +286,38 @@ definition document {
```
-It is _recommended_ that the right side of all arrows refer to **permissions**, instead
-of relations. This allows for easy nested computation, and is more readable.
+ It is _recommended_ that the right side of all arrows refer to
+ **permissions**, instead of relations, as this allows for easy nested
+ computation, and is more readable.
+
+
+##### Subject relations and Arrows
+
+
+ Arrows operate on the **object** of the subject(s) found on a `relation`. They
+ *do not* operate on the relation/permission of a subject, *even if the subject
+ refers to a relation or permission*.
+
+
+For example, in:
+
+```
+defintion resource {
+ relation parent: group#member
+ permission someperm = parent->something
+}
+```
+
+`parent->something` refers to the `something` permission on the **group**, and `#member` will be ignored for the arrow.
+
+It is recommended to not use arrows over relations that allow for subject relations without noting that
+fact via a comment.
+
+
+ Why is this the case? In one word: **performance**. If arrows operated over
+ the subject's relation or permission, a full LookupSubjects call would be
+ necessary for the arrow to correctly "walk", which would make these
+ CheckPermission requests potentially *incredibly* expensive.
### Naming Permissions
@@ -301,7 +334,10 @@ Examples:
| `member` | is member of the object |
-You'll note that we also used `member` above in the relation example. Defining `member` as a **permission** might be found when you have multiple "ways" a subject can be a member of a resource, thus changing it from a simple relation to a _computed_ set of subjects.
+ You'll note that we also used `member` above in the relation example. Defining
+ `member` as a **permission** might be found when you have multiple "ways" a
+ subject can be a member of a resource, thus changing it from a simple relation
+ to a _computed_ set of subjects.
## Comments
@@ -309,7 +345,8 @@ You'll note that we also used `member` above in the relation example. Defining `
### Documentation Comments
-It is **highly** recommended to put doc comments on all definitions, relations and permissions.
+ It is **highly** recommended to put doc comments on all definitions, relations
+ and permissions.
```zed
@@ -327,7 +364,7 @@ It is **highly** recommended to put doc comments on all definitions, relations a
## Full Example
-
+
## Common Patterns
@@ -340,7 +377,7 @@ Both admins and members are considered to have membership in the group.
A role can be applied to individual users and groups.
All individually applied users as well as members for applied groups will have the `allowed` permission.
-
+
### Global admin permissions
@@ -350,7 +387,7 @@ In lieu of adding a super_admin relation on every object that can b
Super admin users can be applied to platform and a relation to platform on top level objects.
Admin permission on resources is then defined as the direct owner of the resource as well as through a traversal of the object hierarchy to the platform super admin.
-
+
### Synthetic relations
@@ -375,10 +412,11 @@ In this example, a folder can have users with read permission.
Additionally, users that can read the parent folder can also read the current folder.
Checking read permission on a folder will recursively consider these relations as the answer is computed.
-
+
- Note that since `parent->read` calls the same `read` permission, it will form a recursive lookup across the chain of parent folder(s).
+ Note that since `parent->read` calls the same `read` permission, it will form
+ a recursive lookup across the chain of parent folder(s).
### Recursive permissions across different resource types
@@ -386,4 +424,4 @@ Checking read permission on a folder will recursively consider these relations a
If a non-recursive resource is used as the starting point for a recursive lookup, it is
**very important** that the permission name used on the right side of the arrow is the **same** in both the starting resource type and the parent resource type(s):
-
+