Spec /relations and aggregations

changelogs/client_server/newsfragments/1062.feature.1

@@ -0,0 +1 @@
+Relax the restrictions on Rich Replies, as per [MSC3676](https://github.com/matrix-org/matrix-spec-proposals/pull/3676).

changelogs/client_server/newsfragments/1062.feature.2

@@ -0,0 +1 @@
+Describe a structured system for event relationships, as per [MSC2674](https://github.com/matrix-org/matrix-spec-proposals/pull/2674).

content/client-server-api/_index.md

@@ -1741,6 +1741,16 @@ There are several APIs provided to `GET` events for a room:
 
 ### Sending events to a room
 
+{{% boxes/note %}}
+{{% added-in v="1.3" %}}
+
+Servers might need to post-process some events if they
+[relate to](#forming-relationships-between-events) another event. The event's
+relationship type (`rel_type`) determines any restrictions which might apply,
+such as the user only being able to send one event of a given type in relation
+to another.
+{{% /boxes/note %}}
+
 {{% http-api spec="client-server" api="room_state" %}}
 
 **Examples**
@@ -1831,6 +1841,47 @@ the topic to be removed from the room.
 
 {{% http-api spec="client-server" api="redaction" %}}
 
+### Forming relationships between events
+
+{{% changed-in v="1.3" %}}
+
+In some cases it is desirable to logically associate one event's contents with
+another event's contents. For example, when replying to a message, editing an
+event, or simply looking to add context for an event's purpose.
+
+Relationships are defined as part of an event's `content`. Any event can relate
+to any other event, however the relationship itself might have restrictions
+depending on its `rel_type`. Those restrictions are described by the relationship
+type in this specification, if any exist.
+
+The relationship is stored under the `m.relates_to` key of `content`, referencing
+the "parent" event. Both the event with `m.relates_to` and the event targeted by
+`m.relates_to` MUST exist in the same room.
+
+{{% boxes/note %}}
+For simplicity, a single type of relationship is permitted on an event at a time.
+A future MSC might change this if a use case arises.
+{{% /boxes/note %}}
+
+{{% boxes/note %}}
+An event with `m.relates_to` can relate to another event with `m.relates_to`,
+forming a sort of chain of events.
+{{% /boxes/note %}}
+
+`m.relates_to` is described as follows:
+
+{{% definition path="api/client-server/definitions/m.relates_to" %}}
+
+### Relationship types
+
+This specification describes the following relationship types:
+
+* [Rich replies](#rich-replies)
+<!--
+TODO: TR,MSC3440: Uncomment for threading support.
+* [Event threading](#threading)
+-->
+
 ## Rooms
 
 ### Types
@@ -2212,6 +2263,7 @@ that profile.
 | Module / Profile                                           | Web       | Mobile   | Desktop  | CLI      | Embedded |
 |------------------------------------------------------------|-----------|----------|----------|----------|----------|
 | [Instant Messaging](#instant-messaging)                    | Required  | Required | Required | Required | Optional |
+| [Rich replies](#rich-replies)                              | Optional  | Optional | Optional | Optional | Optional |
 | [Direct Messaging](#direct-messaging)                      | Required  | Required | Required | Required | Optional |
 | [Mentions](#user-room-and-group-mentions)                  | Required  | Required | Required | Optional | Optional |
 | [Presence](#presence)                                      | Required  | Required | Required | Required | Optional |
@@ -2291,6 +2343,7 @@ applications, they are not intended to be fully-fledged communication
 systems.
 
 {{% cs-module name="instant_messaging" %}}
+{{% cs-module name="rich_replies" %}}
 {{% cs-module name="voip_events" %}}
 {{% cs-module name="typing_notifications" %}}
 {{% cs-module name="receipts" %}}

content/client-server-api/modules/instant_messaging.md

@@ -287,169 +287,6 @@ when using the `m.heroes` to calculate the name. Clients SHOULD use
 minimum 5 heroes to calculate room names where possible, but may use
 more or less to fit better with their user experience.
 
-##### Rich replies
-
-In some cases, events may wish to reference other events. This could be
-to form a thread of messages for the user to follow along with, or to
-provide more context as to what a particular event is describing.
-Currently, the only kind of relation defined is a "rich reply" where a
-user may reference another message to create a thread-like conversation.
-
-Relationships are defined under an `m.relates_to` key in the event's
-`content`. If the event is of the type `m.room.encrypted`, the
-`m.relates_to` key MUST NOT be covered by the encryption and instead be
-put alongside the encryption information held in the `content`.
-
-A rich reply is formed through use of an `m.relates_to` relation for
-`m.in_reply_to` where a single key, `event_id`, is used to reference the
-event being replied to. The referenced event ID SHOULD belong to the
-same room where the reply is being sent. Clients should be cautious of
-the event ID belonging to another room, or being invalid entirely. Rich
-replies can only be constructed in the form of `m.room.message` events
-with a `msgtype` of `m.text` or `m.notice`. Due to the fallback
-requirements, rich replies cannot be constructed for types of `m.emote`,
-`m.file`, etc. Rich replies may reference any other `m.room.message`
-event, however. Rich replies may reference another event which also has
-a rich reply, infinitely.
-
-An `m.in_reply_to` relationship looks like the following:
-
-```
-{
-  ...
-  "type": "m.room.message",
-  "content": {
-    "msgtype": "m.text",
-    "body": "<body including fallback>",
-    "format": "org.matrix.custom.html",
-    "formatted_body": "<HTML including fallback>",
-    "m.relates_to": {
-      "m.in_reply_to": {
-        "event_id": "$another:event.com"
-      }
-    }
-  }
-}
-```
-
-##### Fallbacks for rich replies
-
-Some clients may not have support for rich replies and therefore need a
-fallback to use instead. Clients that do not support rich replies should
-render the event as if rich replies were not special.
-
-Clients that do support rich replies MUST provide the fallback format on
-replies, and MUST strip the fallback before rendering the reply. Rich
-replies MUST have a `format` of `org.matrix.custom.html` and therefore a
-`formatted_body` alongside the `body` and appropriate `msgtype`. The
-specific fallback text is different for each `msgtype`, however the
-general format for the `body` is:
-
-    > <@alice:example.org> This is the original body
-
-    This is where the reply goes
-
-The `formatted_body` should use the following template:
-
-    <mx-reply>
-      <blockquote>
-        <a href="https://matrix.to/#/!somewhere:example.org/$event:example.org">In reply to</a>
-        <a href="https://matrix.to/#/@alice:example.org">@alice:example.org</a>
-        <br />
-        <!-- This is where the related event's HTML would be. -->
-      </blockquote>
-    </mx-reply>
-    This is where the reply goes.
-
-If the related event does not have a `formatted_body`, the event's
-`body` should be considered after encoding any HTML special characters.
-Note that the `href` in both of the anchors use a [matrix.to
-URI](/appendices#matrixto-navigation).
-
-###### Stripping the fallback
-
-Clients which support rich replies MUST strip the fallback from the
-event before rendering the event. This is because the text provided in
-the fallback cannot be trusted to be an accurate representation of the
-event. After removing the fallback, clients are recommended to represent
-the event referenced by `m.in_reply_to` similar to the fallback's
-representation, although clients do have creative freedom for their user
-interface. Clients should prefer the `formatted_body` over the `body`,
-just like with other `m.room.message` events.
-
-To strip the fallback on the `body`, the client should iterate over each
-line of the string, removing any lines that start with the fallback
-prefix ("&gt; ", including the space, without quotes) and stopping when
-a line is encountered without the prefix. This prefix is known as the
-"fallback prefix sequence".
-
-To strip the fallback on the `formatted_body`, the client should remove
-the entirety of the `mx-reply` tag.
-
-###### Fallback for `m.text`, `m.notice`, and unrecognised message types
-
-Using the prefix sequence, the first line of the related event's `body`
-should be prefixed with the user's ID, followed by each line being
-prefixed with the fallback prefix sequence. For example:
-
-    > <@alice:example.org> This is the first line
-    > This is the second line
-
-    This is the reply
-
-The `formatted_body` uses the template defined earlier in this section.
-
-###### Fallback for `m.emote`
-
-Similar to the fallback for `m.text`, each line gets prefixed with the
-fallback prefix sequence. However an asterisk should be inserted before
-the user's ID, like so:
-
-    > * <@alice:example.org> feels like today is going to be a great day
-
-    This is the reply
-
-The `formatted_body` has a subtle difference for the template where the
-asterisk is also inserted ahead of the user's ID:
-
-    <mx-reply>
-      <blockquote>
-        <a href="https://matrix.to/#/!somewhere:example.org/$event:example.org">In reply to</a>
-        * <a href="https://matrix.to/#/@alice:example.org">@alice:example.org</a>
-        <br />
-        <!-- This is where the related event's HTML would be. -->
-      </blockquote>
-    </mx-reply>
-    This is where the reply goes.
-
-###### Fallback for `m.image`, `m.video`, `m.audio`, and `m.file`
-
-The related event's `body` would be a file name, which may not be very
-descriptive. The related event should additionally not have a `format`
-or `formatted_body` in the `content` - if the event does have a `format`
-and/or `formatted_body`, those fields should be ignored. Because the
-filename alone may not be descriptive, the related event's `body` should
-be considered to be `"sent a file."` such that the output looks similar
-to the following:
-
-    > <@alice:example.org> sent a file.
-
-    This is the reply
-
-    <mx-reply>
-      <blockquote>
-        <a href="https://matrix.to/#/!somewhere:example.org/$event:example.org">In reply to</a>
-        <a href="https://matrix.to/#/@alice:example.org">@alice:example.org</a>
-        <br />
-        sent a file.
-      </blockquote>
-    </mx-reply>
-    This is where the reply goes.
-
-For `m.image`, the text should be `"sent an image."`. For `m.video`, the
-text should be `"sent a video."`. For `m.audio`, the text should be
-`"sent an audio file"`.
-
 ##### Spoiler messages
 
 {{% added-in v="1.1" %}}