Update README.md

README.md

@@ -63,7 +63,80 @@ Next, add the following contents to the config file mounted in `./config/authori
 
 It basically configures read/write access for everyone for all data on the `http://mu.semte.ch/graphs/public` graph.
 
+## Tutorials
+### Specifying groups of users
+sparql-parser does authentication based on user groups. We will later define which groups are allowed to perform which operations on which data. So first we need to define some user groups.
+User groups are defined based on the result of a query involving the user's session id. This can look as follows:
+```lisp
+(supply-allowed-group "super-mega-admins"
+  :parameters ("session_group_id" "session_role")
+  :query "PREFIX ext: <http://mu.semte.ch/vocabularies/ext/>
+    PREFIX mu: <http://mu.semte.ch/vocabularies/core/>
+
+    SELECT ?session_group ?session_role WHERE {
+      <SESSION_ID> ext:sessionGroup/mu:uuid ?session_group_id;
+                   ext:sessionRole ?session_role.
+      FILTER( ?session_role = \"SuperMegaAdmin\" )
+    }")
+```
+If this query returns a result, the user will belong to the `super-mega-admins` group. The value for `<SESSION_ID>` will be filled in automatically at runtime. The value of the variables listed in the `:parameters` argument will be joined using `/` and appended to the graph URI when it is accessed. This allows us to have a separate graph per user group.
+
+### Specifying which triples are accessible from which graphs
+For this we need a `define-graph` block. This will create a *graph spec* and looks as follows:
+```lisp
+(define-graph organization ("http://mu.semte.ch/graphs/organizations/")
+  ("foaf:Person" -> _)
+  ("foaf:OnlineAccount" x> "ext:password"))
+```
+**NOTE**: Any prefixes such as `foaf` and `ext` need to be defined, see [Defining prefixes](#defining-prefixes)
+
+The `define-graph` macro takes:
+- A unique identifier (*here `organization`*)
+- The URI of the graph where the triples are stored (*here `http://mu.semte.ch/graphs/organizations/`*)
+- One or more triple shapes (*here `("foaf:Person" -> _)` and `("foaf:OnlineAccount" x> "ext:password")`*).
+
+The triple shapes have this form: `(<someResourceType> <operator> <somePredicate>)`. `<someResourceType>` and `<somePredicate>` must be a URI string (e.g. `"foaf:Person"`) or a `_` (indicating a wildcard). Triples that match these shapes will go to (or retrieved from) the specified graph (in the above example this is `http://mu.semte.ch/graphs/organizations/`). 
+**Note**: different *graph specs* can specify the same graph URI.
+
+These are all the possible operators:
+- `T -> p`: Triples where the subject is of type `T` and the predicate is `p`.
+- `T <- p`: Triples where the object is of type `T` and the predicate is `p`.
+- `T x> p`: For triples where the subject is of type `T`, allow every predicate except for `p`.
+- `T <x p`: For triples where the object is of type `T`, allow every predicate except for `p`.
+
+In the above example this means the following:
+- Matches all triples where the subject is of type `foaf:Person`.
+- Matches all triples where the subject is of type `foaf:OnlineAccount` and where the predicate is not `ext:password`.
+
+### Specifying which user groups have access to which graphs
+Finally we need to specify which *user groups* are allowed to access which *graph spec*. This is done using the `grant` macro.
+```lisp
+(grant (read write)
+  :to-graph (organization)
+  :for-allowed-group "super-mega-admins")
+```
+This indicates that we allow the users in the `super-mega-admins` group to read and write tripes from and to the `http://mu.semte.ch/graphs/organizations/` graph, according to the triple restrictions in the `organization` *graph spec*.
+
+The only allowed operation values are `read` and `write`.
+
+`:to-graph` allows specifying multiple *graph specs*.
+
+`:for-allowed-group` specifies which user group is allowed to execute the specified operations.
+
+
 ## Reference
+### Defining prefixes
+In order to use the CURIE (Compact URI) form (e.g. `foaf:name`) we need to define the prefixes first. This is done as follows:
+```lisp
+(define-prefixes
+  :adms "http://www.w3.org/ns/adms#"
+  :cal "http://www.w3.org/2002/12/cal/ical#"
+  :cogs "http://vocab.deri.ie/cogs#"
+  :dcat "http://www.w3.org/ns/dcat#"
+  :ext "http://mu.semte.ch/vocabularies/ext/"
+  :eli "http://data.europa.eu/eli/ontology#")
+```
+**NOTE**: This does not affect prefixes that can be used in sparql query strings used in this config. They still need to be specified using the `PREFIX` keyword.
 ### Existing configurations
 
 The following projects are currently using this service as a replacement of