From b210e21081492e0c6937d65faf728067f1162059 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Cl=C3=A9ment=20Delafargue?= <clement@delafargue.name>
Date: Thu, 23 Jun 2022 11:27:35 +0200
Subject: [PATCH 1/2] Add a mention of facts namespaces in datalog reference

---
 content/docs/reference/datalog.md | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/content/docs/reference/datalog.md b/content/docs/reference/datalog.md
index 7353f84..ef81839 100644
--- a/content/docs/reference/datalog.md
+++ b/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:

From 3f7d916f7af7a287e434b6d6d88f4582bdea87d1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Cl=C3=A9ment=20Delafargue?= <clement@delafargue.name>
Date: Thu, 23 Jun 2022 11:43:47 +0200
Subject: [PATCH 2/2] Add a small guide on interop & reusability

---
 content/docs/guides/interop.md | 50 ++++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)
 create mode 100644 content/docs/guides/interop.md

diff --git a/content/docs/guides/interop.md b/content/docs/guides/interop.md
new file mode 100644
index 0000000..15321a1
--- /dev/null
+++ b/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.