Add remainder of MSC2674

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,43 @@ 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)
+
 ## Rooms
 
 ### Types

data/api/client-server/definitions/m.relates_to.yaml

@@ -0,0 +1,43 @@
+# Copyright 2022 The Matrix.org Foundation C.I.C.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+type: object
+title: m.relates_to
+description: |-
+  A description of a valid `m.relates_to` definition on an event. This is contained
+  within the event's `content` alongside other fields for that event type.
+example: {
+  # We deliberately "break" the example by including the top-level field so it renders
+  # sensibly for readers of the spec.
+  "m.relates_to": {
+    "rel_type": "org.example.relationship",
+    "event_id": "$an_event"
+  }
+}
+properties:
+  rel_type:
+    type: string
+    description: |-
+      The namespaced relationship type. Values must use the
+      [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
+
+      The relationship type determines how clients should perceive the event, and in what
+      context. Some relationship types are processed server-side for "bundling", though not
+      all relationships require such behaviour. For example, an `m.thread` relationship type
+      denotes that the event is part of a "thread" of messages and should be rendered as
+      such.
+  event_id:
+    type: string
+    description: The event ID in the same room this event relates to.
+required: ['rel_type', 'event_id']