Spec reference relationships

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).

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" >}}

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" }
+    ]
+  }
+}
+```

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: |-