diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 0c9cfec1..189bb00b 100644 --- a/content/client-server-api/_index.md +++ b/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 diff --git a/data/api/client-server/definitions/m.relates_to.yaml b/data/api/client-server/definitions/m.relates_to.yaml new file mode 100644 index 00000000..2e35e448 --- /dev/null +++ b/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']