MSC3267: Reference relations

proposals/3267-reference-relations.md

@@ -0,0 +1,56 @@
+# MSC 3267: reference relationships
+
+## Proposal
+
+This proposal defines a relation type (using [MSC 2674 relations](https://github.com/matrix-org/matrix-doc/pull/2674)) for events to make a reference to another event.
+
+A `rel_type` of `m.reference` is defined for future handling replies and
+threading. This let you define an event which references an existing
+event. When aggregated, this currently doesn't do anything special, but in
+future could bundle chains of references (i.e. threads). These do not yet
+replace the [reply mechanism currently defined in the spec](https://matrix.org/docs/spec/client_server/latest#rich-replies).
+
+Reference relations are used by [MSC 2241](https://github.com/matrix-org/matrix-doc/pull/2241) to tie all events together for the same verification request.
+
+For instance, an `m.room.message` which references an existing event
+would look like:
+
+```json
+{
+    "type": "m.room.message",
+    "content": {
+        "body": "i <3 shelties",
+        "m.relates_to": {
+            "rel_type": "m.reference",
+            "event_id": "$another_event_id"
+        }
+    }
+}
+```
+
+## Server aggregation
+
+Even though [MSC 2674](https://github.com/matrix-org/matrix-doc/pull/2674) states that values for `rel_type`
+should define how the server should aggregate the `rel_type`, this MSC does not define how references should be aggregated by the server on the target event. One possibly way would be to aggregate them as an array of event ids, but the final layout is deferred to [MSC 2675](https://github.com/matrix-org/matrix-doc/pull/2675). The aim of this MSC is to just document the status quo of how `m.reference` is used by [MSC 2241](https://github.com/matrix-org/matrix-doc/pull/2241), where server aggregations are not assumed by the client.
+
+## Limitations
+
+Different subtypes of references could be defined through additional fields on
+the `m.relates_to` object, to distinguish between replies, threads, etc.
+This MSC doesn't attempt to define these subtypes. 
+
+## Edge Cases
+
+Can you reply (via m.references) to a [reaction](https://github.com/matrix-org/matrix-doc/pull/2677)/[edit](https://github.com/matrix-org/matrix-doc/pull/2677)?
+ * Yes, at the protocol level.  But you shouldn't expect clients to do anything
+   useful with it.
+ * Replying to a reaction should be treated like a normal message and have the
+   reply behaviour ignored.
+ * Replying to an edit should be treated in the UI as if you had replied to
+   the original message.
+
+Do we need to support retrospective references?
+ * For something like "m.duplicate" to retrospectively declare that one event
+   dupes another, we might need to bundle two-levels deep (subject+ref and then
+   ref+target).  We can cross this bridge when we get there though, as a 4th
+   aggregation type