feat: update example schemas shown in playground

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,29 +1,3 @@
 # Super-admin / site-wide permissions
 
-Models providing site-wide (or superuser) permissions for all resources of a specific type
-
----
-
-## Schema
-
-```
-definition platform {
-    relation administrator: user
-    permission super_admin = administrator
-}
-
-definition organization {
-    // The platform is generally a singleton pointing to the same
-    // platform object, on which the superuser is in turn granted
-    // access.
-    relation platform: platform
-    permission admin = platform->super_admin
-}
-
-definition resource {
-    relation owner: user | organization
-    permission admin = owner + owner->admin
-}
-
-definition user {}
-```
+Provide site-wide (or superuser) permissions for all resources of a specific type

schemas/superuser/README.md

@@ -1,30 +1,44 @@
 ---
 schema: |-
-  definition platform {
-  	relation administrator: user
-  	permission super_admin = administrator
+  /**
+  * an entity that can be granted permissions
+  */
+  definition user {}
+  
+  /**
+   * a resource that we are trying to protect
+   */
+  definition document {
+    relation owner: user | organization
+  
+    /**
+    * if a user has the (direct) owner relation OR if they are admin of the owner organization, they get the admin permission on the document.
+    */
+    permission admin = owner + owner->admin
   }
-
+  
   definition organization {
     // The platform is generally a singleton pointing to the same
     // platform object, on which the superuser is in turn granted
     // access.
-  	relation platform: platform
-  	permission admin = platform->super_admin
-  }
-
-  definition resource {
-  	relation owner: user | organization
-  	permission admin = owner + owner->admin
+    relation platform: platform
+    permission admin = platform->super_admin
   }
+  
+  /**
+   * a root object
+   */
+  definition platform {
+    relation administrator: user
+    permission super_admin = administrator
+  }  
 
-  definition user {}
 relationships: |-
   platform:evilempire#administrator@user:drevil
   organization:virtucon#platform@platform:evilempire
-  resource:lasers#owner@organization:virtucon
+  document:lasers#owner@organization:virtucon
 assertions:
   assertTrue:
-    - "resource:lasers#admin@user:drevil"
+    - "document:lasers#admin@user:drevil"
   assertFalse: null
 validation: null