Merge pull request #49 from biscuit-auth/namespace-and-interop

Talk a bit about interop and namespacing

content/docs/guides/interop.md

@@ -0,0 +1,50 @@
++++
+title = "Interoperability & Reusability"
+description = "Designing rules for reusability; keping things interoperable"
+date = 2021-05-01T08:00:00+00:00
+updated = 2021-05-01T08:00:00+00:00
+draft = false
+weight = 10
+sort_by = "weight"
+template = "docs/page.html"
+
+[extra]
+lead = "Designing rules for reusability; keeping thing interoperable"
+toc = true
+top = false
++++
+
+In small biscuit deployments (a couple services, in a single
+organization), you have full control on which rules and facts are
+defined and have meaning. On bigger deployments (across multiple
+organizations, or if you want to design a reusable library that can
+be used by multiple services), you will need to be more careful
+about avoiding name collisions.
+
+While there are no well-defined patterns that have emerged yet,
+a good practice is to prefix fact names with the organization name,
+separated by a colon (`:`). So for instance:
+
+```
+// can collide with other facts
+user("1234");
+
+// makes it clear that the user is tied to a specific organization
+wayne_industries:user("1234");
+```
+
+## A few notes
+
+Using namespaced fact names will make tokens a bit bigger for two reasons:
+
+- well, they're longer;
+- names like `user` that are part of the default symbol table are only
+  represented by an index in the wire format.
+
+The size increase will be mitigated by string interning (you only pay the extra
+cost once).
+
+Another thing to note is that _namespacing is not a security feature_: it prevents
+accidental name collisions, but is not a proper way to separate facts based on
+their origin. Third party blocks provide such a mechanism. Namespacing can be
+used _in conjuction_, to make things easier to read and understand.

content/docs/reference/datalog.md

@@ -20,6 +20,16 @@ In Datalog, data is represented by facts. They come in the format `fact_name(42,
 
 All of the tasks around Datalog consists in selecting data from facts, and generating new ones.
 
+### Namespacing
+
+Fact names can contain colons (`:`). While they don’t mean anything particular to the datalog engine, they are meant as a namespace
+separator: when your rules start to grow, or if you want to provide reusable rules that don’t clash with others, you can _namespace_
+your datalog facts and rules:
+
+```
+service_a:fact_name(42);
+```
+
 ## Data types
 
 A fact contains data of the following types: