From 0b59d857207979c2b3063bef8522ead8022c20a1 Mon Sep 17 00:00:00 2001
From: Cyber MacGeddon <cybermaggedon@gmail.com>
Date: Thu, 3 Jul 2025 10:02:52 +0100
Subject: [PATCH] Improve triple docs

---
 docs/apis/api-triples-query.md | 57 +++++++++++++++++++++++++---------
 1 file changed, 42 insertions(+), 15 deletions(-)

diff --git a/docs/apis/api-triples-query.md b/docs/apis/api-triples-query.md
index f6038163..7c1a6bd9 100644
--- a/docs/apis/api-triples-query.md
+++ b/docs/apis/api-triples-query.md
@@ -33,15 +33,53 @@ Each triple element uses the same schema:
 - `is_uri`: A boolean value which is true if this is a graph entity i.e.
   `value` is a URI, not a literal value.
 
+## Data Format Details
+
+### Triple Element Format
+
+To reduce the size of JSON messages, triple elements (subject, predicate, object) are encoded using a compact format:
+
+- `v`: The value as a string (maps to `value` in the full schema)
+- `e`: Boolean indicating if this is an entity/URI (maps to `is_uri` in the full schema)
+
+Each triple element (`s`, `p`, `o`) contains:
+- `v`: The actual value as a string
+- `e`: Boolean indicating the value type
+  - `true`: The value is a URI/entity (e.g., `"http://example.com/Person1"`)
+  - `false`: The value is a literal (e.g., `"John Doe"`, `"42"`, `"2023-01-01"`)
+
+### Examples
+
+**URI/Entity Element:**
+```json
+{
+    "v": "http://trustgraph.ai/e/space-station-modules",
+    "e": true
+}
+```
+
+**Literal Element:**
+```json
+{
+    "v": "space station modules", 
+    "e": false
+}
+```
+
+**Numeric Literal:**
+```json
+{
+    "v": "42",
+    "e": false
+}
+```
+
 ## REST service
 
 The REST service accepts a request object containing the `s`, `p`, `o`
 and `limit` fields.
 The response is a JSON object containing the `response` field.
 
-To reduce the size of the JSON, the graph entities are encoded as an
-object with `value` and `is_uri` mapped to `v` and `e` respectively.
-
 e.g.
 
 This example query matches triples with a subject of
@@ -98,13 +136,9 @@ Response:
 
 ## Websocket
 
-Requests have a `request` object containing the `system` and
-`prompt` fields.
+Requests have a `request` object containing the query fields (`s`, `p`, `o`, `limit`).
 Responses have a `response` object containing `response` field.
 
-To reduce the size of the JSON, the graph entities are encoded as an
-object with `value` and `is_uri` mapped to `v` and `e` respectively.
-
 e.g.
 
 Request:
@@ -179,10 +213,3 @@ The client class is
 
 https://github.com/trustgraph-ai/trustgraph/blob/master/trustgraph-base/trustgraph/clients/triples_query_client.py
 
-
-
-
-
-
-
-