Add documentation for using contextual tuples in Expand API

openfga/v1/openfga_service.proto

@@ -408,6 +408,7 @@ service OpenFGAService {
         "This is different from the `/stores/{store_id}/read` API in that both users and "
         "computed usersets are returned.\n"
         "Body parameters `tuple_key.object` and `tuple_key.relation` are all required.\n"
+        "A `contextual_tuples` object may also be included in the body of the request. This object contains one field `tuple_keys`, which is an array of tuple keys. Each of these tuples may have an associated `condition`.\n"
         "The response will return a tree whose leaves are the specific users and usersets. "
         "Union, intersection and difference operator are located in the intermediate nodes.\n\n"
         "## Example\n"
@@ -455,7 +456,115 @@ service OpenFGAService {
         "  }\n"
         "}\n"
         "```\n"
-        "The caller can then call expand API for the `writer` relationship for the `document:2021-budget`."
+        "The caller can then call expand API for the `writer` relationship for the `document:2021-budget`.\n"
+        "### Expand Request with Contextual Tuples\n"
+        "\n"
+        "Given the model\n"
+        "```python\n"
+        "model\n"
+        "    schema 1.1\n"
+        "\n"
+        "type user\n"
+        "\n"
+        "type folder\n"
+        "    relations\n"
+        "        define owner: [user]\n"
+        "\n"
+        "type document\n"
+        "    relations\n"
+        "        define parent: [folder]\n"
+        "        define viewer: [user] or writer\n"
+        "        define writer: [user] or owner from parent\n"
+        "```\n"
+        "and the initial tuples\n"
+        "```json\n"
+        "[{\n"
+        "    \"user\": \"user:bob\",\n"
+        "    \"relation\": \"owner\",\n"
+        "    \"object\": \"folder:1\"\n"
+        "}]\n"
+        "```\n"
+        "\n"
+        "To expand all `writers` of `document:1` when `document:1` is put in `folder:1`, the first call could be\n"
+        "\n"
+        "```json\n"
+        "{\n"
+        "  \"tuple_key\": {\n"
+        "    \"object\": \"document:1\",\n"
+        "    \"relation\": \"writer\"\n"
+        "  },\n"
+        "  \"contextual_tuples\": {\n"
+        "    \"tuple_keys\": [\n"
+        "      {\n"
+        "        \"user\": \"folder:1\",\n"
+        "        \"relation\": \"parent\",\n"
+        "        \"object\": \"document:1\"\n"
+        "      }\n"
+        "    ]\n"
+        "  }\n"
+        "}\n"
+        "```\n"
+        "this returns:\n"
+        "```json\n"
+        "{\n"
+        "  \"tree\": {\n"
+        "    \"root\": {\n"
+        "      \"name\": \"document:1#writer\",\n"
+        "      \"union\": {\n"
+        "        \"nodes\": [\n"
+        "          {\n"
+        "            \"name\": \"document:1#writer\",\n"
+        "            \"leaf\": {\n"
+        "              \"users\": {\n"
+        "                \"users\": []\n"
+        "              }\n"
+        "            }\n"
+        "          },\n"
+        "          {\n"
+        "            \"name\": \"document:1#writer\",\n"
+        "            \"leaf\": {\n"
+        "              \"tupleToUserset\": {\n"
+        "                \"tupleset\": \"document:1#parent\",\n"
+        "                \"computed\": [\n"
+        "                  {\n"
+        "                    \"userset\": \"folder:1#owner\"\n"
+        "                  }\n"
+        "                ]\n"
+        "              }\n"
+        "            }\n"
+        "          }\n"
+        "        ]\n"
+        "      }\n"
+        "    }\n"
+        "  }\n"
+        "}\n"
+        "```\n"
+        "This tells us that the `owner` of `folder:1` may also be a writer. So our next call could be to find the `owners` of `folder:1`\n"
+        "```json\n"
+        "{\n"
+        "  \"tuple_key\": {\n"
+        "    \"object\": \"folder:1\",\n"
+        "    \"relation\": \"owner\"\n"
+        "  }\n"
+        "}\n"
+        "```\n"
+        "which gives\n"
+        "```json\n"
+        "{\n"
+        "  \"tree\": {\n"
+        "    \"root\": {\n"
+        "      \"name\": \"folder:1#owner\",\n"
+        "      \"leaf\": {\n"
+        "        \"users\": {\n"
+        "          \"users\": [\n"
+        "            \"user:bob\"\n"
+        "          ]\n"
+        "        }\n"
+        "      }\n"
+        "    }\n"
+        "  }\n"
+        "}\n"
+        "```\n"
     };
   }