feat: update example schemas shown in playground (#39)

Author: miparnisari

README.md

@@ -17,7 +17,7 @@ Developers create a schema that models their permissions requirements and use a
 Examples in this repository include:
 
 - How to set up SpiceDB with tracing: see [tracing](./tracing)
-- How to invoke SpiceDB as a library: see [library](./library)
+- How to invoke SpiceDB as a library: see [library](./spicedb-as-library)
 - How to run SpiceDB in a Kubernetes cluster: see [kubernetes](./kubernetes)
 - CI/CD Workflows
 

schemas/basic-rbac/README.md

@@ -0,0 +1,3 @@
+# Simple Relationship Based Access Control (ReBAC)
+
+Access is granted to users based on the relation(s) that they have to a given document.

schemas/basic-rebac/README.md

@@ -1,32 +1,31 @@
 ---
 schema: |-
   /**
-   * user represents a user that can be granted role(s)
+   * an entity that can be granted permissions
    */
   definition user {}
 
   /**
-   * document represents a document protected by Authzed.
+   * a resource that we are trying to protect
    */
   definition document {
       /**
-       * writer indicates that the user is a writer on the document.
+       * users can be made writers of specific documents
        */
       relation writer: user
 
       /**
-       * reader indicates that the user is a reader on the document.
+       * users can be made readers of specific documents
        */
       relation reader: user
 
       /**
-       * edit indicates that the user has permission to edit the document.
+       * if a user has the writer relationship to a specific document, they automatically get permission to edit it
        */
       permission edit = writer
 
       /**
-       * view indicates that the user has permission to view the document, if they
-       * are a `reader` *or* have `edit` permission.
+       * if a user has the reader relation to a document OR the permission to edit a document (or both), they automatically get permission to view it
        */
       permission view = reader + edit
   }

schemas/basic-rbac/schema-and-data.yaml schemas/basic-rebac/schema-and-data.yamlschemas/basic-rbac/schema-and-data.yaml renamed to schemas/basic-rebac/schema-and-data.yaml

@@ -1,29 +1,4 @@
-# Caveats for conditional access
+# Simple Attribute Based Access Control (ABAC)
 
-Models the use of caveats, which allows for conditional access based on information provided at _runtime_ to permission checks.
+Access can be granted to users based on information provided at runtime to permission checks.
 
----
-
-## Schema
-
-```
-definition user {}
-
-/**
- * only allowed on tuesdays. `day_of_week` can be provided either at the time
- * the relationship is written, or in the CheckPermission API call.
- */
-caveat only_on_tuesday(day_of_week string) {
-  day_of_week == 'tuesday'
-}
-
-definition document {
-    /**
-     * reader indicates that the user is a reader on the document, either
-     * directly or only on tuesday.
-     */
-    relation reader: user | user with only_on_tuesday
-
-    permission view = reader
-}
-```

schemas/caveats/README.md

@@ -1,42 +1,57 @@
 ---
 schema: |-
+  /**
+   * an entity that can be granted permissions
+   */
   definition user {}
 
   /**
-   * only allowed on tuesdays. `day_of_week` can be provided either at the time
-   * the relationship is written, or in the CheckPermission API call.
+   * a resource that we are trying to protect
    */
-  caveat only_on_tuesday(day_of_week string) {
-    day_of_week == 'tuesday'
-  }
-
-  caveat ip_allowlist(user_ip ipaddress, cidr string) {
-    user_ip.in_cidr(cidr)
-  }
-
   definition document {
       /**
-       * reader indicates that the user is a reader on the document, either directly,
-       * only on tuesday, or from allowed IPs.
+       * users can be made readers of specific documents,
+       * either directly, or only if they have a valid IP, or only if they aren't rate limited.
        */
-      relation reader: user | user with only_on_tuesday | user with ip_allowlist
+      relation reader: user | user with has_valid_ip | user with not_rate_limited
 
+      /**
+       * if a user has the reder relationship to a specific document, they automatically get permission to view it
+       */
       permission view = reader
   }
+
+    /**
+     * only allowed if the IP address is allowed.
+     * we can provide cidr at the time we write the relation, and
+     * we can provide user_ip at the time the CheckPermission is made.
+     */
+    caveat has_valid_ip(user_ip ipaddress, cidr string) {
+      user_ip.in_cidr(cidr)
+    }
+
+    /**
+     * only allowed if rate limits haven't been exceeded.
+     * we can provide allowed_max at the time we write the relation, and
+     * we can provide current at the time the CheckPermission is made.
+     */
+    caveat not_rate_limited(allowed_max int, current int) {
+      current < allowed_max
+    }
 relationships: |-
   document:firstdoc#reader@user:fred
-  document:firstdoc#reader@user:tom[only_on_tuesday]
-  document:firstdoc#reader@user:alice[ip_allowlist:{"cidr":"1.2.3.0/24"}]
+  document:firstdoc#reader@user:tom[not_rate_limited:{"allowed_max":100}]
+  document:firstdoc#reader@user:alice[has_valid_ip:{"cidr":"1.2.3.0/24"}]
 assertions:
   assertTrue:
-    - 'document:firstdoc#view@user:tom with {"day_of_week": "tuesday"}'
+    - 'document:firstdoc#view@user:tom with {"current": 1}'
     - "document:firstdoc#view@user:fred"
     - 'document:firstdoc#view@user:alice with {"user_ip": "1.2.3.4"}'
   assertCaveated:
     - "document:firstdoc#view@user:tom"
     - "document:firstdoc#view@user:alice"
   assertFalse:
-    - 'document:firstdoc#view@user:tom with {"day_of_week": "wednesday"}'
+    - 'document:firstdoc#view@user:tom with {"current": 500}'
     - 'document:firstdoc#view@user:alice with {"user_ip": "8.8.8.8"}'
 validation:
   document:firstdoc#view:

schemas/caveats/schema-and-data.yaml

@@ -1,101 +1,3 @@
-# Google Docs-style Sharing
+# Group membership and parent-of/child-of relations
 
-Models a Google Docs-style sharing permission system where users can be granted direct access to a resource, or access via organizations and nested groups.
-
----
-
-## Schema
-
-```
-definition user {}
-
-definition resource {
-    relation manager: user | usergroup#member | usergroup#manager
-    relation viewer: user | usergroup#member | usergroup#manager
-
-    permission manage = manager
-    permission view = viewer + manager
-}
-
-definition usergroup {
-    relation manager: user | usergroup#member | usergroup#manager
-    relation direct_member: user | usergroup#member | usergroup#manager
-
-    permission member = direct_member + manager
-}
-
-definition organization {
-    relation group: usergroup
-    relation administrator: user | usergroup#member | usergroup#manager
-    relation direct_member: user
-
-    relation resource: resource
-
-    permission admin = administrator
-    permission member = direct_member + administrator + group->member
-}
-```
-
-### user
-
-`user` is an example of a "user" type, which is used to represent users. The definition itself is empty, as it is only used for referencing purposes.
-
-```zed
-definition user {}
-```
-
-### resource
-
-`resource` is the definition used to represent the resource being shared
-
-```zed
-definition resource {
-    relation manager: user | usergroup#member | usergroup#manager
-    relation viewer: user | usergroup#member | usergroup#manager
-
-    permission manage = manager
-    permission view = viewer + manager
-}
-```
-
-Within the definition, there are defined two relations: `viewer` and `manager`, which are used to represent roles for users _or members/managers of groups_ for the resource, as well as the `view` and `manage` permissions for viewing and managing the resource, respectively.
-
-### usergroup
-
-`usergroup` is the definition used to represent groups, which can contain either users or other groups. Groups support a distinction between member and manager.
-
-```zed
-definition usergroup {
-    relation manager: user | usergroup#member | usergroup#manager
-    relation direct_member: user | usergroup#member | usergroup#manager
-
-    permission member = direct_member + manager
-}
-```
-
-### organization
-
-`organization` is the definition used to represent the overall organization.
-
-```zed
-definition organization {
-    relation group: usergroup
-    relation administrator: user | usergroup#member | usergroup#manager
-    relation direct_member: user
-
-    relation resource: resource
-
-    permission admin = administrator
-    permission member = direct_member + administrator + group->member
-}
-```
-
-Organizations contain four relations (`group`, `resource`, `member`, `administrator`) which are used to reference the groups, resources, direct members and administrator users for the organization.
-
-#### member permission
-
-The `member` permission under organization computes the transitive closure of _all_ member users/groups of an organization by combining data from three sources:
-
-1. `direct_member`: users directly added to the organization as a member
-2. `administrator` is used to add any users found as an `administrator` of the organization
-3. `group->member` is used to walk from the organization to any of its groups, and then from the `group` to any of its members. This ensure that if a user is available under `member` under any group in the organization, they are treated as a member of the organization as well.
+Access can be granted via direct access, or by being member of a group (that can be a child of another group) that has access to the resource.