Arbitrary vars in rule refs

docs/content/policy-language.md

@@ -992,6 +992,120 @@ data.example
 ```live:eg/ref_heads:output
 ```
 
+#### General References
+
+Any term, except the very first, in a rule head's reference can be a variable. These variables can be assigned within the rule, just as for any other partial rule, to dynamically construct a nested collection of objects. 
+
+{{< danger >}}
+General refs in rule heads is an experimental feature, and can be enabled by setting the `OPA_ENABLE_GENERAL_RULE_REFS` environment variable.
+
+This feature is currently not supported for Wasm and IR.
+{{< /danger >}}
+
+Data:
+
+```json
+{
+    "users": [
+        {
+            "id": "alice",
+            "role": "employee",
+            "country": "USA"
+        },
+        {
+            "id": "bob",
+            "role": "customer",
+            "country": "USA"
+        },
+        {
+            "id": "dora",
+            "role": "admin",
+            "country": "Sweden"
+        }
+    ],
+    "admins": [
+        {
+            "id": "charlie"
+        }
+    ]
+}
+```
+
+Module: 
+
+```rego
+package example
+
+import future.keywords
+
+# A partial object rule that converts a list of users to a mapping by "role" and then "id".
+users_by_role[role][id] := user {
+    some user in data.users
+    id := user.id
+    role := user.role
+}
+
+# Partial rule with an explicit "admin" key override
+users_by_role.admin[id] := user {
+    some user in data.admins
+    id := user.id
+}
+
+# Leaf entries can be partial sets
+users_by_country[country] contains user.id {
+    some user in data.users
+    country := user.country
+}
+```
+
+Query:
+
+```
+data.example
+```
+
+Output: 
+
+```json
+{
+  "users_by_country": {
+    "Sweden": [
+      "dora"
+    ],
+    "USA": [
+      "alice",
+      "bob"
+    ]
+  },
+  "users_by_role": {
+    "admin": {
+      "charlie": {
+        "id": "charlie"
+      },
+      "dora": {
+        "country": "Sweden",
+        "id": "dora",
+        "role": "admin"
+      }
+    },
+    "customer": {
+      "bob": {
+        "country": "USA",
+        "id": "bob",
+        "role": "customer"
+      }
+    },
+    "employee": {
+      "alice": {
+        "country": "USA",
+        "id": "alice",
+        "role": "employee"
+      }
+    }
+  }
+}
+```
+
 ### Functions
 
 Rego supports user-defined functions that can be called with the same semantics as [Built-in Functions](#built-in-functions). They have access to both the [the data Document](../philosophy/#the-opa-document-model) and [the input Document](../philosophy/#the-opa-document-model).