From b2cc8366498fed2d230ec48279d3e2ea9f840d50 Mon Sep 17 00:00:00 2001
From: Travis Ralston <travisr@matrix.org>
Date: Tue, 18 Oct 2022 11:50:41 -0600
Subject: [PATCH] Spec reference relationships (#1206)

* Spec reference relationships

MSC: https://github.com/matrix-org/matrix-spec-proposals/pull/3267

* Apply suggestions from code review

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

* Edits per code review

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
---
 .../client_server/newsfragments/1206.feature  |  1 +
 content/client-server-api/_index.md           |  2 +
 .../modules/reference_relations.md            | 55 +++++++++++++++++++
 .../m.key.verification.m.relates_to.yaml      |  3 +-
 4 files changed, 60 insertions(+), 1 deletion(-)
 create mode 100644 changelogs/client_server/newsfragments/1206.feature
 create mode 100644 content/client-server-api/modules/reference_relations.md

diff --git a/changelogs/client_server/newsfragments/1206.feature b/changelogs/client_server/newsfragments/1206.feature
new file mode 100644
index 00000000..16bcd216
--- /dev/null
+++ b/changelogs/client_server/newsfragments/1206.feature
@@ -0,0 +1 @@
+Add `m.reference` relations, as per [MSC3267](https://github.com/matrix-org/matrix-spec-proposals/pull/3267).
diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md
index dd50f225..1407441b 100644
--- a/content/client-server-api/_index.md
+++ b/content/client-server-api/_index.md
@@ -1973,6 +1973,7 @@ This specification describes the following relationship types:
 * [Rich replies](#rich-replies) (**Note**: does not use `rel_type`).
 * [Event replacements](#event-replacements).
 * [Threads](#threading).
+* [References](#reference-relations)
 
 #### Aggregations
 
@@ -2640,3 +2641,4 @@ systems.
 {{< cs-module name="spaces" >}}
 {{< cs-module name="event_replacements" >}}
 {{< cs-module name="threading" >}}
+{{< cs-module name="reference_relations" >}}
\ No newline at end of file
diff --git a/content/client-server-api/modules/reference_relations.md b/content/client-server-api/modules/reference_relations.md
new file mode 100644
index 00000000..b88b56ae
--- /dev/null
+++ b/content/client-server-api/modules/reference_relations.md
@@ -0,0 +1,55 @@
+---
+type: module
+---
+
+### Reference relations
+
+{{% added-in v="1.4" %}}
+
+Generically referencing another event can be done with a `rel_type` of `m.reference`
+as a form of [relationship](#forming-relationships-between-events). There is no
+implied meaning behind the reference, and is usually context-dependent. One
+example is the [key verification framework](#key-verification-framework) which uses
+reference relations to associate distinct events with a specific verification attempt.
+
+{{% boxes/note %}}
+Clients which wish to use threads or replies are expected to use other relationship
+types than references. References are typically used to associate data rather than
+messages.
+{{% /boxes/note %}}
+
+#### Server behaviour
+
+##### Server-side aggregation of `m.reference`
+
+The aggregation format of `m.reference` relations consists of a single `chunk` property,
+which lists all the events which `m.reference` the event (the parent). Currently,
+only a single `event_id` field is present on the events in the `chunk`.
+
+An example `m.reference` would be:
+
+```json
+{
+  "content": {
+    "m.relates_to": {
+      "rel_type": "m.reference",
+      "event_id": "$another_event"
+    }
+    // other content fields as required
+  }
+  // other fields as required by events
+}
+```
+
+The [bundle](#aggregations) under `m.relations` would appear similar to the following:
+
+```json
+{
+  "m.reference": {
+    "chunk": [
+      { "event_id": "$one" },
+      { "event_id": "$two" }
+    ]
+  }
+}
+```
diff --git a/data/event-schemas/schema/m.key.verification.m.relates_to.yaml b/data/event-schemas/schema/m.key.verification.m.relates_to.yaml
index 670fd606..038344b9 100644
--- a/data/event-schemas/schema/m.key.verification.m.relates_to.yaml
+++ b/data/event-schemas/schema/m.key.verification.m.relates_to.yaml
@@ -10,7 +10,8 @@ properties:
     enum:
       - m.reference
     description: |-
-      The relationship type.
+      The relationship type. Currently, this can only be an
+      [`m.reference`](/client-server-api/#reference-relations) relationship type.
   event_id:
     type: string
     description: |-