From 9e8460f58c781934c259b58c2dd740a00485057a Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 7 Jul 2020 15:25:30 -0400 Subject: [PATCH 01/46] initial version of event relationship MSC --- proposals/xxxx-event-relationships.md | 255 ++++++++++++++++++++++++++ 1 file changed, 255 insertions(+) create mode 100644 proposals/xxxx-event-relationships.md diff --git a/proposals/xxxx-event-relationships.md b/proposals/xxxx-event-relationships.md new file mode 100644 index 0000000000..db8c028f02 --- /dev/null +++ b/proposals/xxxx-event-relationships.md @@ -0,0 +1,255 @@ +# MSCxxxx: Event relationships + +It's common to want to send events in Matrix which relate to existing events - +for instance, reactions, edits and even replies/threads. + +This proposal is one in a series of proposals that defines a mechanism for +events to relate to each other. Together, these proposals replace +[MSC1849](https://github.com/matrix-org/matrix-doc/pull/1849). + +* This proposal defines a standard shape for indicating events which relate to + other events. +* [MSCxxxx](https://github.com/matrix-org/matrix-doc/pull/xxxx) defines APIs to + let the server calculate the aggregations on behalf of the client, and so + bundle the related events with the original event where appropriate. +* [MSCxxxx](https://github.com/matrix-org/matrix-doc/pull/xxxx) defines how + users can edit messages using this mechanism. +* [MSCxxxx](https://github.com/matrix-org/matrix-doc/pull/xxxx) defines how + users can annotate events, such as reacting to events with emoji, using this + mechanism. + +## Proposal + +This proposal introduces the concept of relations, which can be used to +associate new information with an existing event. + +Relations are any event which have an `m.relates_to` field in their +contents. The `m.relates_to` field must include a `rel_type` field that +gives the type of relationship being defined, and the `event_id` field that +gives the event which is the target of the relation. All the information about +the relationship lives under the `m.relates_to` key. + +If it helps, you can think of relations as a "subject verb object" triple, +where the subject is the relation event itself; the verb is the `rel_type` +field of the `m.relates_to` and the object is the `event_id` field. + +We consciously do not support multiple different relations within a single event, +in order to keep the API simple, and in the absence of identifiable use cases. +Instead, one would send multiple events, each with its own `m.relates_to` +defined. + +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). + +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" + } + } +} +``` + +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. + + XXX: do we want to support multiple parents for a m.reference event, if a + given event references different parents in different ways? + +### Sending relations + +Related events are normal Matrix events, and can be sent by the normal /send +API. + +The server should postprocess relations if needed before sending them into a +room, as defined by the relationship type. For example, a relationship type +might only allow a user to send one related message to a given event. + +Similar to membership events, a convenience API is also provided to highlight +that the server may post-process the event, and whose URL structures the +semantics of the relation being sent more clearly: + +``` +PUT /_matrix/client/r0/rooms/{roomId}/send_relation/{parent_id}/{relation_type}/{event_type}/{txn_id}[?key={relation_key}] +{ + // event contents +} +``` + +The `parent_id` is the ID of the event being referenced. In other words, it is +the `event_id` field that will be in the `m.relates_to` object. + +The `relation_key` is for relationships that have a `key` property. + +The endpoint does not have any trailing slashes. + +### Receiving relations + +Relations are received during non-gappy incremental syncs (that is, syncs +called with a `since` token, and that have `limited: false` in the portion of +response for the given room) as normal discrete Matrix events. + +[MSCxxxx](https://github.com/matrix-org/matrix-doc/pull/xxxx) defines ways in +which the server may aid clients in processing relations by aggregating the +events. + +### End to end encryption + +Since the server has to be able to bundle related events, structural +information about relations cannot be encrypted end-to-end, and so the +`m.relates_to` field should not be included in the ciphertext. + +A future MSC may define a method for encrypting certain parts of the +`m.relates_to` field that may contain sensitive information. + +### Redactions + +Relations may be redacted like any other event. In the case of `m.reference` it +removes the referencing event. + +The `m.relates_to`.`rel_type` and `m.relates_to`.`event_id` fields should +be preserved over redactions, so that clients can distinguish redacted edits +from normal redacted messages, and maintain reply ordering. + + FIXME: synapse doesn't do this yet + + XXX: Does this require a new room version? + +## Edge Cases + +Can you reply (via m.references) to a [reaction](https://github.com/matrix-org/matrix-doc/pull/xxxx)/[edit](https://github.com/matrix-org/matrix-doc/pull/xxxx)? + * 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. + +What does it mean to call /context on a relation? + * We should probably just return the root event for now, and then refine it in + future for threading? + * XXX: what does synapse do here? + +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 + +## Potential issues + +### Federation considerations + +We have a problem with resynchronising relations after a gap in federation: +We have no way of knowing that an edit happened in the gap to one of the events +we already have. So, we'll show inconsistent data until we backfill the gap. + * We could write this off as a limitation. + * Or we could make *ALL* relations a DAG, so we can spot holes at the next + relation, and go walk the DAG to pull in the missing relations? Then, the + next relation for an event could pull in any of the missing relations. + Socially this probably doesn't work as reactions will likely drop off over + time, so by the time your server comes back there won't be any more reactions + pulling the missing ones in. + * Could we also ask the server, after a gap, to provide all the relations which + happened during the gap to events whose root preceeded the gap. + * "Give me all relations which happened between this set of + forward-extremities when I lost sync, and the point i've rejoined the DAG, + for events which preceeded the gap"? + * Would be hard to auth all the relations which this api coughed up. + * We could auth them based only the auth events of the relation, except we + lose the context of the nearby DAG which we'd have if it was a normal + backfilled event. + * As a result it would be easier for a server to retrospectively lie about + events on behalf of its users. + * This probably isn't the end of the world, plus it's more likely to be + consistent than if we leave a gap. + * i.e. it's better to consistent with a small chance of being maliciously + wrong, than inconsistent with a guaranteed chance of being innocently + wrong. + * We'd need to worry about pagination. + * This is probably the best solution, but can also be added as a v2. + +## Tradeoffs + +### Event shape + +Shape of + +```json +"content": { + "m.relates_to": { + "m.reference": { + "event_id": "$another:event.com" + } + } +} +``` +versus + +```json +"content": { + "m.relates_to": { + "rel_type": "m.reference", + "event_id": "$another:event.com" + } +} +``` + +The reasons to go with `rel_type` is: + * we don't need the extra indirection to let multiple relations apply to a given pair of + events, as that should be expressed as separate relation events. + * if we want 'adverbs' to apply to 'verbs' in the subject-verb-object triples which + relations form, then we apply it as mixins to the relation data itself rather than trying + to construct subject-verb-verb-object sentences. + * so, we should pick a simpler shape rather than inheriting the mistakes of m.in_reply_to + and we have to keep ugly backwards compatibility around for m.in_reply_to + but we can entirely separately worry about migrating replies to new-style-aggregations in future + perhaps at the same time as doing threads. + +## Historical context + +pik's MSC441 has: + +Define the JSON schema for the aggregation event, so the server can work out +which fields should be aggregated. + +```json +"type": "m.room._aggregation.emoticon", +"content": { + "emoticon": "::smile::", + "msgtype": "?", + "target_id": "$another:event.com" +} +``` + +These would then aggregated, based on target_id, and returned as annotations on +the source event in an `aggregation_data` field: + +```json +"content": { + ... + "aggregation_data": { + "m.room._aggregation.emoticon": { + "aggregation_data": [ + { + "emoticon": "::smile::", + "event_id": "$14796538949JTYis:pik-test", + "sender": "@pik:pik-test" + } + ], + "latest_event_id": "$14796538949JTYis:pik-test" + } + } +} +``` From 34152627a2cc0ebad4bac0fe140069fc71e18fb7 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 7 Jul 2020 16:23:55 -0400 Subject: [PATCH 02/46] fix MSC numbers --- ...-relationships.md => 2674-event-relationships.md} | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) rename proposals/{xxxx-event-relationships.md => 2674-event-relationships.md} (96%) diff --git a/proposals/xxxx-event-relationships.md b/proposals/2674-event-relationships.md similarity index 96% rename from proposals/xxxx-event-relationships.md rename to proposals/2674-event-relationships.md index db8c028f02..77ce81aaaf 100644 --- a/proposals/xxxx-event-relationships.md +++ b/proposals/2674-event-relationships.md @@ -1,4 +1,4 @@ -# MSCxxxx: Event relationships +# MSC2674: Event relationships It's common to want to send events in Matrix which relate to existing events - for instance, reactions, edits and even replies/threads. @@ -9,12 +9,12 @@ events to relate to each other. Together, these proposals replace * This proposal defines a standard shape for indicating events which relate to other events. -* [MSCxxxx](https://github.com/matrix-org/matrix-doc/pull/xxxx) defines APIs to +* [MSC2675](https://github.com/matrix-org/matrix-doc/pull/2675) defines APIs to let the server calculate the aggregations on behalf of the client, and so bundle the related events with the original event where appropriate. -* [MSCxxxx](https://github.com/matrix-org/matrix-doc/pull/xxxx) defines how +* [MSC2676](https://github.com/matrix-org/matrix-doc/pull/2676) defines how users can edit messages using this mechanism. -* [MSCxxxx](https://github.com/matrix-org/matrix-doc/pull/xxxx) defines how +* [MSC2677](https://github.com/matrix-org/matrix-doc/pull/2677) defines how users can annotate events, such as reacting to events with emoji, using this mechanism. @@ -100,7 +100,7 @@ Relations are received during non-gappy incremental syncs (that is, syncs called with a `since` token, and that have `limited: false` in the portion of response for the given room) as normal discrete Matrix events. -[MSCxxxx](https://github.com/matrix-org/matrix-doc/pull/xxxx) defines ways in +[MSC2675](https://github.com/matrix-org/matrix-doc/pull/2675) defines ways in which the server may aid clients in processing relations by aggregating the events. @@ -128,7 +128,7 @@ from normal redacted messages, and maintain reply ordering. ## Edge Cases -Can you reply (via m.references) to a [reaction](https://github.com/matrix-org/matrix-doc/pull/xxxx)/[edit](https://github.com/matrix-org/matrix-doc/pull/xxxx)? +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 From c00e4f4aeb03e5de684df91e5d936b9b0f204daa Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Wed, 2 Jun 2021 16:57:23 -0400 Subject: [PATCH 03/46] clarifications --- proposals/2674-event-relationships.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/proposals/2674-event-relationships.md b/proposals/2674-event-relationships.md index 77ce81aaaf..d0f4a6a7a5 100644 --- a/proposals/2674-event-relationships.md +++ b/proposals/2674-event-relationships.md @@ -25,7 +25,7 @@ associate new information with an existing event. Relations are any event which have an `m.relates_to` field in their contents. The `m.relates_to` field must include a `rel_type` field that -gives the type of relationship being defined, and the `event_id` field that +gives the type of relationship being defined, and an `event_id` field that gives the event which is the target of the relation. All the information about the relationship lives under the `m.relates_to` key. @@ -64,9 +64,6 @@ 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. - XXX: do we want to support multiple parents for a m.reference event, if a - given event references different parents in different ways? - ### Sending relations Related events are normal Matrix events, and can be sent by the normal /send @@ -107,8 +104,8 @@ events. ### End to end encryption Since the server has to be able to bundle related events, structural -information about relations cannot be encrypted end-to-end, and so the -`m.relates_to` field should not be included in the ciphertext. +information about relations must be visible to the server, and so the +`m.relates_to` field must be included in the plaintext. A future MSC may define a method for encrypting certain parts of the `m.relates_to` field that may contain sensitive information. @@ -124,7 +121,9 @@ from normal redacted messages, and maintain reply ordering. FIXME: synapse doesn't do this yet - XXX: Does this require a new room version? +This modification to the redaction algorithm requires a new room version. +However, event relationships can still be used in existing room versions, but +the user experince may worse if redactions are performed. ## Edge Cases From e4c16fa7299252d4dca250cf143fa591c5acfde9 Mon Sep 17 00:00:00 2001 From: Bruno Windels Date: Wed, 30 Jun 2021 15:13:09 +0200 Subject: [PATCH 04/46] mention multiple relations per event might be useful, but postpone for a future MSC --- proposals/2674-event-relationships.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/proposals/2674-event-relationships.md b/proposals/2674-event-relationships.md index d0f4a6a7a5..768e5a1d30 100644 --- a/proposals/2674-event-relationships.md +++ b/proposals/2674-event-relationships.md @@ -34,9 +34,8 @@ where the subject is the relation event itself; the verb is the `rel_type` field of the `m.relates_to` and the object is the `event_id` field. We consciously do not support multiple different relations within a single event, -in order to keep the API simple, and in the absence of identifiable use cases. -Instead, one would send multiple events, each with its own `m.relates_to` -defined. +in order to keep the API simple. A future MSC can propose a change to add support +for multiple relations if it turns out that this would facilitate certain use cases. A `rel_type` of `m.reference` is defined for future handling replies and threading. This let you define an event which references an existing From 35fb00c30a7cb85629e2da5bb7dc9612ea6f6fe9 Mon Sep 17 00:00:00 2001 From: Bruno Windels Date: Wed, 30 Jun 2021 15:29:53 +0200 Subject: [PATCH 05/46] mention MSC 3051 for proposed multiple relations --- proposals/2674-event-relationships.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/proposals/2674-event-relationships.md b/proposals/2674-event-relationships.md index 768e5a1d30..95e005c653 100644 --- a/proposals/2674-event-relationships.md +++ b/proposals/2674-event-relationships.md @@ -34,8 +34,10 @@ where the subject is the relation event itself; the verb is the `rel_type` field of the `m.relates_to` and the object is the `event_id` field. We consciously do not support multiple different relations within a single event, -in order to keep the API simple. A future MSC can propose a change to add support -for multiple relations if it turns out that this would facilitate certain use cases. +in order to keep the API simple. Another MSC, +like [MSC 3051](https://github.com/matrix-org/matrix-doc/pull/3051), +can propose a change to add support for multiple relations if it turns out that +this would facilitate certain use cases. A `rel_type` of `m.reference` is defined for future handling replies and threading. This let you define an event which references an existing From db6213b27eb29e055f38c3b5e253910fdbe1574a Mon Sep 17 00:00:00 2001 From: Bruno Windels Date: Wed, 30 Jun 2021 15:40:32 +0200 Subject: [PATCH 06/46] remove send_relation endpoint --- proposals/2674-event-relationships.md | 18 ------------------ 1 file changed, 18 deletions(-) diff --git a/proposals/2674-event-relationships.md b/proposals/2674-event-relationships.md index 95e005c653..ec0787e48f 100644 --- a/proposals/2674-event-relationships.md +++ b/proposals/2674-event-relationships.md @@ -74,24 +74,6 @@ The server should postprocess relations if needed before sending them into a room, as defined by the relationship type. For example, a relationship type might only allow a user to send one related message to a given event. -Similar to membership events, a convenience API is also provided to highlight -that the server may post-process the event, and whose URL structures the -semantics of the relation being sent more clearly: - -``` -PUT /_matrix/client/r0/rooms/{roomId}/send_relation/{parent_id}/{relation_type}/{event_type}/{txn_id}[?key={relation_key}] -{ - // event contents -} -``` - -The `parent_id` is the ID of the event being referenced. In other words, it is -the `event_id` field that will be in the `m.relates_to` object. - -The `relation_key` is for relationships that have a `key` property. - -The endpoint does not have any trailing slashes. - ### Receiving relations Relations are received during non-gappy incremental syncs (that is, syncs From 2229975a6faf1159c10c93e00f2d5c5e6e1371a0 Mon Sep 17 00:00:00 2001 From: Bruno Windels Date: Wed, 30 Jun 2021 16:07:41 +0200 Subject: [PATCH 07/46] move e2ee section under sending relations --- proposals/2674-event-relationships.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/proposals/2674-event-relationships.md b/proposals/2674-event-relationships.md index ec0787e48f..0296cbb1bf 100644 --- a/proposals/2674-event-relationships.md +++ b/proposals/2674-event-relationships.md @@ -74,6 +74,15 @@ The server should postprocess relations if needed before sending them into a room, as defined by the relationship type. For example, a relationship type might only allow a user to send one related message to a given event. +#### End to end encryption + +Since the server has to be able to bundle related events, structural +information about relations must be visible to the server, and so the +`m.relates_to` field must be included in the plaintext. + +A future MSC may define a method for encrypting certain parts of the +`m.relates_to` field that may contain sensitive information. + ### Receiving relations Relations are received during non-gappy incremental syncs (that is, syncs @@ -84,15 +93,6 @@ response for the given room) as normal discrete Matrix events. which the server may aid clients in processing relations by aggregating the events. -### End to end encryption - -Since the server has to be able to bundle related events, structural -information about relations must be visible to the server, and so the -`m.relates_to` field must be included in the plaintext. - -A future MSC may define a method for encrypting certain parts of the -`m.relates_to` field that may contain sensitive information. - ### Redactions Relations may be redacted like any other event. In the case of `m.reference` it From d9ffb2cc6c5dc4a8dd33be2835ef10ee9b762029 Mon Sep 17 00:00:00 2001 From: Bruno Windels Date: Thu, 1 Jul 2021 14:27:59 +0200 Subject: [PATCH 08/46] mention limitation of leaving server-side aggregations out for now --- proposals/2674-event-relationships.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/proposals/2674-event-relationships.md b/proposals/2674-event-relationships.md index 0296cbb1bf..d4b6f6e73c 100644 --- a/proposals/2674-event-relationships.md +++ b/proposals/2674-event-relationships.md @@ -162,6 +162,19 @@ we already have. So, we'll show inconsistent data until we backfill the gap. * We'd need to worry about pagination. * This is probably the best solution, but can also be added as a v2. +## Limitations + +Based solely on this MSC, relations are only received as discrete events in +the timeline, so clients may only have an incomplete image of all the relations +with an event if they do not fill gaps in the timeline. + +In practice, this has proven not to be too big of a problem, as reactions +(as proposed in [MSC 2677](https://github.com/matrix-org/matrix-doc/pull/2677)) +tend to be posted close after the target event in the timeline. + +A more complete solution to this has been deferred to +[MSC2675](https://github.com/matrix-org/matrix-doc/pull/2675). + ## Tradeoffs ### Event shape From bc1df59de6d1392284ec7e819f6973f8cbd24397 Mon Sep 17 00:00:00 2001 From: Bruno Windels Date: Thu, 1 Jul 2021 15:34:52 +0200 Subject: [PATCH 09/46] remove mentions of m.reference, we'll sort that out in another MSC --- proposals/2674-event-relationships.md | 34 +-------------------------- 1 file changed, 1 insertion(+), 33 deletions(-) diff --git a/proposals/2674-event-relationships.md b/proposals/2674-event-relationships.md index d4b6f6e73c..125fc30561 100644 --- a/proposals/2674-event-relationships.md +++ b/proposals/2674-event-relationships.md @@ -39,28 +39,6 @@ like [MSC 3051](https://github.com/matrix-org/matrix-doc/pull/3051), can propose a change to add support for multiple relations if it turns out that this would facilitate certain use cases. -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). - -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" - } - } -} -``` - 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. @@ -74,15 +52,6 @@ The server should postprocess relations if needed before sending them into a room, as defined by the relationship type. For example, a relationship type might only allow a user to send one related message to a given event. -#### End to end encryption - -Since the server has to be able to bundle related events, structural -information about relations must be visible to the server, and so the -`m.relates_to` field must be included in the plaintext. - -A future MSC may define a method for encrypting certain parts of the -`m.relates_to` field that may contain sensitive information. - ### Receiving relations Relations are received during non-gappy incremental syncs (that is, syncs @@ -95,8 +64,7 @@ events. ### Redactions -Relations may be redacted like any other event. In the case of `m.reference` it -removes the referencing event. +Relations may be redacted like any other event. The `m.relates_to`.`rel_type` and `m.relates_to`.`event_id` fields should be preserved over redactions, so that clients can distinguish redacted edits From 18cac1ae0426a4c5672f8292d5e82fe7fc7a3584 Mon Sep 17 00:00:00 2001 From: Bruno Windels Date: Thu, 1 Jul 2021 15:35:17 +0200 Subject: [PATCH 10/46] whitespace --- proposals/2674-event-relationships.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2674-event-relationships.md b/proposals/2674-event-relationships.md index 125fc30561..05baae5475 100644 --- a/proposals/2674-event-relationships.md +++ b/proposals/2674-event-relationships.md @@ -26,7 +26,7 @@ associate new information with an existing event. Relations are any event which have an `m.relates_to` field in their contents. The `m.relates_to` field must include a `rel_type` field that gives the type of relationship being defined, and an `event_id` field that -gives the event which is the target of the relation. All the information about +gives the event which is the target of the relation. All the information about the relationship lives under the `m.relates_to` key. If it helps, you can think of relations as a "subject verb object" triple, From 3e6e566a6214612da79122ea6f68f03d8565df69 Mon Sep 17 00:00:00 2001 From: Bruno Windels Date: Thu, 1 Jul 2021 15:35:30 +0200 Subject: [PATCH 11/46] argument why m.relates_to should be preserved by redactions more general but still give example of redacted edits --- proposals/2674-event-relationships.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/proposals/2674-event-relationships.md b/proposals/2674-event-relationships.md index 05baae5475..e6ffffbeeb 100644 --- a/proposals/2674-event-relationships.md +++ b/proposals/2674-event-relationships.md @@ -67,7 +67,11 @@ events. Relations may be redacted like any other event. The `m.relates_to`.`rel_type` and `m.relates_to`.`event_id` fields should -be preserved over redactions, so that clients can distinguish redacted edits +be preserved over redactions, so that clients can still distinguish +redacted relations from other redacted events of the event type. + +One example is telling redacted edits (as proposed in +[MSC 2676](https://github.com/matrix-org/matrix-doc/pull/2676)) apart from from normal redacted messages, and maintain reply ordering. FIXME: synapse doesn't do this yet From 62036f10923c40f29eff5a7dc3f78d48d74d8678 Mon Sep 17 00:00:00 2001 From: Bruno Windels Date: Thu, 1 Jul 2021 15:40:45 +0200 Subject: [PATCH 12/46] deal with this in the comments --- proposals/2674-event-relationships.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/proposals/2674-event-relationships.md b/proposals/2674-event-relationships.md index e6ffffbeeb..a1cf136a06 100644 --- a/proposals/2674-event-relationships.md +++ b/proposals/2674-event-relationships.md @@ -74,8 +74,6 @@ One example is telling redacted edits (as proposed in [MSC 2676](https://github.com/matrix-org/matrix-doc/pull/2676)) apart from from normal redacted messages, and maintain reply ordering. - FIXME: synapse doesn't do this yet - This modification to the redaction algorithm requires a new room version. However, event relationships can still be used in existing room versions, but the user experince may worse if redactions are performed. From c667a08b6aa846f081f59e8288a4fc87623a464d Mon Sep 17 00:00:00 2001 From: Bruno Windels Date: Thu, 1 Jul 2021 15:52:15 +0200 Subject: [PATCH 13/46] clarify the conditions to meet for a relation --- proposals/2674-event-relationships.md | 20 +++++++------------- 1 file changed, 7 insertions(+), 13 deletions(-) diff --git a/proposals/2674-event-relationships.md b/proposals/2674-event-relationships.md index a1cf136a06..ee6e667bab 100644 --- a/proposals/2674-event-relationships.md +++ b/proposals/2674-event-relationships.md @@ -23,11 +23,13 @@ events to relate to each other. Together, these proposals replace This proposal introduces the concept of relations, which can be used to associate new information with an existing event. -Relations are any event which have an `m.relates_to` field in their -contents. The `m.relates_to` field must include a `rel_type` field that -gives the type of relationship being defined, and an `event_id` field that -gives the event which is the target of the relation. All the information about -the relationship lives under the `m.relates_to` key. +Events are said to contain a relationship when their `content` object contains +a `m.relates_to` object which has both a `rel_type` string field that gives the type +of relationship being defined, and an `event_id` string field that gives the event +which is the target of the relation. If any of these conditions is not met, +clients and servers should treat the event as if it does not contain a relationship. + +All the information about the relationship lives under the `m.relates_to` key. If it helps, you can think of relations as a "subject verb object" triple, where the subject is the relation event itself; the verb is the `rel_type` @@ -80,14 +82,6 @@ the user experince may worse if redactions are performed. ## 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. - What does it mean to call /context on a relation? * We should probably just return the root event for now, and then refine it in future for threading? From e90f31e512855410bfd56e45204f74b6224566f1 Mon Sep 17 00:00:00 2001 From: Bruno Windels Date: Thu, 1 Jul 2021 16:04:44 +0200 Subject: [PATCH 14/46] mention specifically that this does not replace replies (yet) --- proposals/2674-event-relationships.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/proposals/2674-event-relationships.md b/proposals/2674-event-relationships.md index ee6e667bab..54dd049a4b 100644 --- a/proposals/2674-event-relationships.md +++ b/proposals/2674-event-relationships.md @@ -35,6 +35,9 @@ If it helps, you can think of relations as a "subject verb object" triple, where the subject is the relation event itself; the verb is the `rel_type` field of the `m.relates_to` and the object is the `event_id` field. +These do not yet replace the +[reply mechanism currently defined in the spec](https://matrix.org/docs/spec/client_server/latest#rich-replies). + We consciously do not support multiple different relations within a single event, in order to keep the API simple. Another MSC, like [MSC 3051](https://github.com/matrix-org/matrix-doc/pull/3051), From fd137488cf7e1ccb418ec156b75458b931fdf038 Mon Sep 17 00:00:00 2001 From: Bruno Windels Date: Fri, 2 Jul 2021 13:18:19 +0200 Subject: [PATCH 15/46] clarify how general rel_types should be --- proposals/2674-event-relationships.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/proposals/2674-event-relationships.md b/proposals/2674-event-relationships.md index 54dd049a4b..21c17cb38a 100644 --- a/proposals/2674-event-relationships.md +++ b/proposals/2674-event-relationships.md @@ -48,6 +48,23 @@ 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. +### Relation types + +This MSC does not define any value for `rel_type`, but rather defines the generic +framework that different kinds of relations have in common and that other MSCs can +build on. Future definitions for values of `rel_type` should describe *how* the server +should aggregate relations on the target event +(as proposed in [MSC 2675](https://github.com/matrix-org/matrix-doc/pull/2675)). +The goals is to make each rel_type as broadly useful as possible, +and to keep the amount of types for a server implementation to support down to a minimum. + +Multiple client use cases may be served by a single `rel_type` if they require aggregation +in a similar manner. To further specify how a relation should be displayed in the client, +MSCs may define additional fields in `m.relates_to` for specific values of `rel_type`. + +Any values here should abide the +[general guidelines for identifiers](https://github.com/matrix-org/matrix-doc/pull/3171). + ### Sending relations Related events are normal Matrix events, and can be sent by the normal /send From 5eaf2de2cfa095791bee3f9488323ccd3b9518f9 Mon Sep 17 00:00:00 2001 From: Bruno Windels Date: Fri, 2 Jul 2021 13:22:06 +0200 Subject: [PATCH 16/46] clarify that gaps may cause clients to be unaware of some relations --- proposals/2674-event-relationships.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/proposals/2674-event-relationships.md b/proposals/2674-event-relationships.md index 21c17cb38a..3615d84cb3 100644 --- a/proposals/2674-event-relationships.md +++ b/proposals/2674-event-relationships.md @@ -76,9 +76,9 @@ might only allow a user to send one related message to a given event. ### Receiving relations -Relations are received during non-gappy incremental syncs (that is, syncs -called with a `since` token, and that have `limited: false` in the portion of -response for the given room) as normal discrete Matrix events. +Relations are received like other non-state events, with `/sync`, +`/messages` and `/context`, as normal discrete Matrix events. As explained +in the limitations, clients may be unaware of some relations using just these endpoints. [MSC2675](https://github.com/matrix-org/matrix-doc/pull/2675) defines ways in which the server may aid clients in processing relations by aggregating the @@ -150,7 +150,8 @@ we already have. So, we'll show inconsistent data until we backfill the gap. Based solely on this MSC, relations are only received as discrete events in the timeline, so clients may only have an incomplete image of all the relations -with an event if they do not fill gaps in the timeline. +with an event if they do not fill gaps (syncs with a since token that have +`limited: true` set in the sync response for a room) in the timeline. In practice, this has proven not to be too big of a problem, as reactions (as proposed in [MSC 2677](https://github.com/matrix-org/matrix-doc/pull/2677)) From 157a097d4e6998a8b33b779754dc691a44a0ad40 Mon Sep 17 00:00:00 2001 From: Bruno Windels Date: Fri, 2 Jul 2021 11:26:36 +0000 Subject: [PATCH 17/46] Update proposals/2674-event-relationships.md Co-authored-by: DeepBlueV7.X --- proposals/2674-event-relationships.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/proposals/2674-event-relationships.md b/proposals/2674-event-relationships.md index 3615d84cb3..fff3a63437 100644 --- a/proposals/2674-event-relationships.md +++ b/proposals/2674-event-relationships.md @@ -23,10 +23,10 @@ events to relate to each other. Together, these proposals replace This proposal introduces the concept of relations, which can be used to associate new information with an existing event. -Events are said to contain a relationship when their `content` object contains -a `m.relates_to` object which has both a `rel_type` string field that gives the type -of relationship being defined, and an `event_id` string field that gives the event -which is the target of the relation. If any of these conditions is not met, +A relationship is an object with a field `rel_type`, which is a string describing the type of relation, +and a field `event_id`, which is a string that represents the event_id of the target of this relation. +Both of those fields are required. An event is said to contain a relationship if their `content` contains +a relationship with all the required fields under the `m.relates_to` key. If any of these conditions is not met, clients and servers should treat the event as if it does not contain a relationship. All the information about the relationship lives under the `m.relates_to` key. From 71d96685b49e412122be0cbc466b9eb1e32c1b25 Mon Sep 17 00:00:00 2001 From: Bruno Windels Date: Fri, 2 Jul 2021 11:31:51 +0000 Subject: [PATCH 18/46] Update proposals/2674-event-relationships.md Co-authored-by: DeepBlueV7.X --- proposals/2674-event-relationships.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/proposals/2674-event-relationships.md b/proposals/2674-event-relationships.md index fff3a63437..ba14489df3 100644 --- a/proposals/2674-event-relationships.md +++ b/proposals/2674-event-relationships.md @@ -145,7 +145,8 @@ we already have. So, we'll show inconsistent data until we backfill the gap. wrong. * We'd need to worry about pagination. * This is probably the best solution, but can also be added as a v2. - + * In practice this seems to not be an issue, which is worth complicating the s-s API over. Clients very rarely jump over the federation gap to an edit. In most cases they scroll up, which backfills the server and we have all the edits, when we reach the event before the gap. + ## Limitations Based solely on this MSC, relations are only received as discrete events in From b590a4c4c47d13f785f7ea5ed317514d9e4ac3f6 Mon Sep 17 00:00:00 2001 From: Bruno Windels Date: Mon, 5 Jul 2021 16:34:30 +0200 Subject: [PATCH 19/46] make wording clearer and move to bottom of section --- proposals/2674-event-relationships.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/proposals/2674-event-relationships.md b/proposals/2674-event-relationships.md index ba14489df3..373101269c 100644 --- a/proposals/2674-event-relationships.md +++ b/proposals/2674-event-relationships.md @@ -35,9 +35,6 @@ If it helps, you can think of relations as a "subject verb object" triple, where the subject is the relation event itself; the verb is the `rel_type` field of the `m.relates_to` and the object is the `event_id` field. -These do not yet replace the -[reply mechanism currently defined in the spec](https://matrix.org/docs/spec/client_server/latest#rich-replies). - We consciously do not support multiple different relations within a single event, in order to keep the API simple. Another MSC, like [MSC 3051](https://github.com/matrix-org/matrix-doc/pull/3051), @@ -47,6 +44,8 @@ this would facilitate certain use cases. 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. +Relations do not yet replace the +[reply mechanism currently defined in the spec](https://matrix.org/docs/spec/client_server/latest#rich-replies). ### Relation types From 0cd38d11cce05a1519cd71381981278f721d145f Mon Sep 17 00:00:00 2001 From: Bruno Windels Date: Mon, 5 Jul 2021 16:34:49 +0200 Subject: [PATCH 20/46] remove this as references are not defined here anymore --- proposals/2674-event-relationships.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/proposals/2674-event-relationships.md b/proposals/2674-event-relationships.md index 373101269c..0b3185398d 100644 --- a/proposals/2674-event-relationships.md +++ b/proposals/2674-event-relationships.md @@ -41,9 +41,6 @@ like [MSC 3051](https://github.com/matrix-org/matrix-doc/pull/3051), can propose a change to add support for multiple relations if it turns out that this would facilitate certain use cases. -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. Relations do not yet replace the [reply mechanism currently defined in the spec](https://matrix.org/docs/spec/client_server/latest#rich-replies). From 6665bc1e3e2074110834818bcb429e51e24f7939 Mon Sep 17 00:00:00 2001 From: Bruno Windels Date: Mon, 5 Jul 2021 16:35:05 +0200 Subject: [PATCH 21/46] clearer wording --- proposals/2674-event-relationships.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2674-event-relationships.md b/proposals/2674-event-relationships.md index 0b3185398d..251d494c3b 100644 --- a/proposals/2674-event-relationships.md +++ b/proposals/2674-event-relationships.md @@ -86,7 +86,7 @@ Relations may be redacted like any other event. The `m.relates_to`.`rel_type` and `m.relates_to`.`event_id` fields should be preserved over redactions, so that clients can still distinguish -redacted relations from other redacted events of the event type. +redacted relations from other redacted events of the same event type. One example is telling redacted edits (as proposed in [MSC 2676](https://github.com/matrix-org/matrix-doc/pull/2676)) apart from From 00ce39ef95d4101b33fdfe1fd298c15fd57f3e65 Mon Sep 17 00:00:00 2001 From: Bruno Windels Date: Mon, 5 Jul 2021 16:36:03 +0200 Subject: [PATCH 22/46] move edge cases to other relevant mscs --- proposals/2674-event-relationships.md | 13 ------------- 1 file changed, 13 deletions(-) diff --git a/proposals/2674-event-relationships.md b/proposals/2674-event-relationships.md index 251d494c3b..b2760c388e 100644 --- a/proposals/2674-event-relationships.md +++ b/proposals/2674-event-relationships.md @@ -96,19 +96,6 @@ This modification to the redaction algorithm requires a new room version. However, event relationships can still be used in existing room versions, but the user experince may worse if redactions are performed. -## Edge Cases - -What does it mean to call /context on a relation? - * We should probably just return the root event for now, and then refine it in - future for threading? - * XXX: what does synapse do here? - -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 - ## Potential issues ### Federation considerations From f41b78caa3ee75309cdd8c7e83848ce69875c416 Mon Sep 17 00:00:00 2001 From: Bruno Windels Date: Mon, 5 Jul 2021 16:39:12 +0200 Subject: [PATCH 23/46] clarify that a goal of sticking to this format is backwards compat. --- proposals/2674-event-relationships.md | 1 + 1 file changed, 1 insertion(+) diff --git a/proposals/2674-event-relationships.md b/proposals/2674-event-relationships.md index b2760c388e..6e703e54f6 100644 --- a/proposals/2674-event-relationships.md +++ b/proposals/2674-event-relationships.md @@ -171,6 +171,7 @@ versus ``` The reasons to go with `rel_type` is: + * this format is now in use in the wider matrix ecosystem without a prefix, in spite of the original MSC 1849 not being merged. This situation is not ideal but we still don't want to break compatibility with several clients. * we don't need the extra indirection to let multiple relations apply to a given pair of events, as that should be expressed as separate relation events. * if we want 'adverbs' to apply to 'verbs' in the subject-verb-object triples which From 6c2e2e057cc7d4c906e7397bf98e0e9b6f74e0f3 Mon Sep 17 00:00:00 2001 From: Bruno Windels Date: Mon, 5 Jul 2021 17:26:11 +0200 Subject: [PATCH 24/46] mention MSC 3267, to which m.reference has been extracted --- proposals/2674-event-relationships.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/proposals/2674-event-relationships.md b/proposals/2674-event-relationships.md index 6e703e54f6..cd5fe450ac 100644 --- a/proposals/2674-event-relationships.md +++ b/proposals/2674-event-relationships.md @@ -17,6 +17,8 @@ events to relate to each other. Together, these proposals replace * [MSC2677](https://github.com/matrix-org/matrix-doc/pull/2677) defines how users can annotate events, such as reacting to events with emoji, using this mechanism. +* [MSC3267](https://github.com/matrix-org/matrix-doc/pull/3267) defines events + can make a reference to other events. ## Proposal From 5170cc1c70234abdbb115d58296f9490794a5ddd Mon Sep 17 00:00:00 2001 From: Bruno Windels Date: Wed, 25 Aug 2021 15:20:34 +0200 Subject: [PATCH 25/46] Update proposals/2674-event-relationships.md Co-authored-by: Hubert Chathi --- proposals/2674-event-relationships.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/2674-event-relationships.md b/proposals/2674-event-relationships.md index cd5fe450ac..e4f7067039 100644 --- a/proposals/2674-event-relationships.md +++ b/proposals/2674-event-relationships.md @@ -53,8 +53,8 @@ framework that different kinds of relations have in common and that other MSCs c build on. Future definitions for values of `rel_type` should describe *how* the server should aggregate relations on the target event (as proposed in [MSC 2675](https://github.com/matrix-org/matrix-doc/pull/2675)). -The goals is to make each rel_type as broadly useful as possible, -and to keep the amount of types for a server implementation to support down to a minimum. +The goals are to make each `rel_type` as broadly useful as possible, +and to keep the number of types for a server implementation to support down to a minimum. Multiple client use cases may be served by a single `rel_type` if they require aggregation in a similar manner. To further specify how a relation should be displayed in the client, From 075ea46b079981f41219d207b319c0b11a0451ab Mon Sep 17 00:00:00 2001 From: Bruno Windels Date: Wed, 25 Aug 2021 15:20:45 +0200 Subject: [PATCH 26/46] Update proposals/2674-event-relationships.md Co-authored-by: Hubert Chathi --- proposals/2674-event-relationships.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2674-event-relationships.md b/proposals/2674-event-relationships.md index e4f7067039..16580e6dda 100644 --- a/proposals/2674-event-relationships.md +++ b/proposals/2674-event-relationships.md @@ -65,7 +65,7 @@ Any values here should abide the ### Sending relations -Related events are normal Matrix events, and can be sent by the normal /send +Related events are normal Matrix events, and can be sent by the normal `/send` API. The server should postprocess relations if needed before sending them into a From 99a2729d932b120def90de1cbcee2039ff6c68cf Mon Sep 17 00:00:00 2001 From: Bruno Windels Date: Wed, 25 Aug 2021 15:21:02 +0200 Subject: [PATCH 27/46] Update proposals/2674-event-relationships.md Co-authored-by: Matthew Hodgson --- proposals/2674-event-relationships.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2674-event-relationships.md b/proposals/2674-event-relationships.md index 16580e6dda..817a002a98 100644 --- a/proposals/2674-event-relationships.md +++ b/proposals/2674-event-relationships.md @@ -96,7 +96,7 @@ from normal redacted messages, and maintain reply ordering. This modification to the redaction algorithm requires a new room version. However, event relationships can still be used in existing room versions, but -the user experince may worse if redactions are performed. +the user experince may be worse if redactions are performed. ## Potential issues From 76a411631b6e5c1230427b42b1962480a0d19b0a Mon Sep 17 00:00:00 2001 From: Bruno Windels Date: Wed, 25 Aug 2021 15:21:17 +0200 Subject: [PATCH 28/46] Update proposals/2674-event-relationships.md Co-authored-by: Matthew Hodgson --- proposals/2674-event-relationships.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2674-event-relationships.md b/proposals/2674-event-relationships.md index 817a002a98..a36091f23f 100644 --- a/proposals/2674-event-relationships.md +++ b/proposals/2674-event-relationships.md @@ -200,7 +200,7 @@ which fields should be aggregated. } ``` -These would then aggregated, based on target_id, and returned as annotations on +These would then be aggregated, based on target_id, and returned as annotations on the source event in an `aggregation_data` field: ```json From eb9033a56fad5f7d202520a0f14f60038929426b Mon Sep 17 00:00:00 2001 From: Bruno Windels Date: Wed, 25 Aug 2021 15:29:03 +0200 Subject: [PATCH 29/46] Update proposals/2674-event-relationships.md Co-authored-by: Travis Ralston --- proposals/2674-event-relationships.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2674-event-relationships.md b/proposals/2674-event-relationships.md index a36091f23f..a5fe8e0428 100644 --- a/proposals/2674-event-relationships.md +++ b/proposals/2674-event-relationships.md @@ -44,7 +44,7 @@ can propose a change to add support for multiple relations if it turns out that this would facilitate certain use cases. Relations do not yet replace the -[reply mechanism currently defined in the spec](https://matrix.org/docs/spec/client_server/latest#rich-replies). +[reply mechanism currently defined in the spec](https://matrix.org/docs/spec/client_server/r0.6.1#rich-replies). ### Relation types From 4388deaa4a8fa85ddbd9324f81d726b8c48c5093 Mon Sep 17 00:00:00 2001 From: Bruno Windels Date: Wed, 25 Aug 2021 15:38:34 +0200 Subject: [PATCH 30/46] wrap lines --- proposals/2674-event-relationships.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/proposals/2674-event-relationships.md b/proposals/2674-event-relationships.md index a5fe8e0428..6aea4e44f6 100644 --- a/proposals/2674-event-relationships.md +++ b/proposals/2674-event-relationships.md @@ -130,7 +130,10 @@ we already have. So, we'll show inconsistent data until we backfill the gap. wrong. * We'd need to worry about pagination. * This is probably the best solution, but can also be added as a v2. - * In practice this seems to not be an issue, which is worth complicating the s-s API over. Clients very rarely jump over the federation gap to an edit. In most cases they scroll up, which backfills the server and we have all the edits, when we reach the event before the gap. + * In practice this seems to not be an issue, which is worth complicating + the s-s API over. Clients very rarely jump over the federation gap to an edit. + In most cases they scroll up, which backfills the server and we have all the + edits, when we reach the event before the gap. ## Limitations @@ -173,7 +176,9 @@ versus ``` The reasons to go with `rel_type` is: - * this format is now in use in the wider matrix ecosystem without a prefix, in spite of the original MSC 1849 not being merged. This situation is not ideal but we still don't want to break compatibility with several clients. + * this format is now in use in the wider matrix ecosystem without a prefix, + in spite of the original MSC 1849 not being merged. This situation is not ideal + but we still don't want to break compatibility with several clients. * we don't need the extra indirection to let multiple relations apply to a given pair of events, as that should be expressed as separate relation events. * if we want 'adverbs' to apply to 'verbs' in the subject-verb-object triples which From cd180b641afadf0aa70b32edf25c1de2bc0bfa87 Mon Sep 17 00:00:00 2001 From: Bruno Windels Date: Wed, 25 Aug 2021 15:41:34 +0200 Subject: [PATCH 31/46] better wording --- proposals/2674-event-relationships.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2674-event-relationships.md b/proposals/2674-event-relationships.md index 6aea4e44f6..d5f6deb908 100644 --- a/proposals/2674-event-relationships.md +++ b/proposals/2674-event-relationships.md @@ -17,7 +17,7 @@ events to relate to each other. Together, these proposals replace * [MSC2677](https://github.com/matrix-org/matrix-doc/pull/2677) defines how users can annotate events, such as reacting to events with emoji, using this mechanism. -* [MSC3267](https://github.com/matrix-org/matrix-doc/pull/3267) defines events +* [MSC3267](https://github.com/matrix-org/matrix-doc/pull/3267) defines how events can make a reference to other events. ## Proposal From 533b8e8eb405406bbf5fa3b30aa54a7bb09b481d Mon Sep 17 00:00:00 2001 From: Bruno Windels Date: Wed, 25 Aug 2021 15:45:06 +0200 Subject: [PATCH 32/46] this is singular, really --- proposals/2674-event-relationships.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2674-event-relationships.md b/proposals/2674-event-relationships.md index d5f6deb908..8a909efc0f 100644 --- a/proposals/2674-event-relationships.md +++ b/proposals/2674-event-relationships.md @@ -53,7 +53,7 @@ framework that different kinds of relations have in common and that other MSCs c build on. Future definitions for values of `rel_type` should describe *how* the server should aggregate relations on the target event (as proposed in [MSC 2675](https://github.com/matrix-org/matrix-doc/pull/2675)). -The goals are to make each `rel_type` as broadly useful as possible, +The goal is to make each `rel_type` as broadly useful as possible, and to keep the number of types for a server implementation to support down to a minimum. Multiple client use cases may be served by a single `rel_type` if they require aggregation From 138ca8ce9b8268f86ff83bb1619e24d9abba10e6 Mon Sep 17 00:00:00 2001 From: Bruno Windels Date: Wed, 25 Aug 2021 15:49:42 +0200 Subject: [PATCH 33/46] add example of event shape --- proposals/2674-event-relationships.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/proposals/2674-event-relationships.md b/proposals/2674-event-relationships.md index 8a909efc0f..e55e6d66d2 100644 --- a/proposals/2674-event-relationships.md +++ b/proposals/2674-event-relationships.md @@ -31,6 +31,19 @@ Both of those fields are required. An event is said to contain a relationship if a relationship with all the required fields under the `m.relates_to` key. If any of these conditions is not met, clients and servers should treat the event as if it does not contain a relationship. +Here's a (partial) example of an event relating to another event: + +```json +{ + "content": { + "m.relates_to": { + "rel_type": "m.replace", + "event_id": "$abc:server.tld" + } + } +} +``` + All the information about the relationship lives under the `m.relates_to` key. If it helps, you can think of relations as a "subject verb object" triple, From 9c6d2826933a7760c0e48eddcd62ca76c0c170c3 Mon Sep 17 00:00:00 2001 From: Bruno Windels Date: Wed, 25 Aug 2021 16:08:17 +0200 Subject: [PATCH 34/46] specify how invalid relations should be treated by the redaction algorithm --- proposals/2674-event-relationships.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/proposals/2674-event-relationships.md b/proposals/2674-event-relationships.md index e55e6d66d2..fc77711160 100644 --- a/proposals/2674-event-relationships.md +++ b/proposals/2674-event-relationships.md @@ -97,11 +97,14 @@ events. ### Redactions -Relations may be redacted like any other event. +Events with a relation may be redacted like any other event. The `m.relates_to`.`rel_type` and `m.relates_to`.`event_id` fields should be preserved over redactions, so that clients can still distinguish redacted relations from other redacted events of the same event type. +If `m.relates_to` is not an object, or `m._relates_to` would be +an empty object after redacting any other keys, then `m.relates_to` +should also be removed from `content`. One example is telling redacted edits (as proposed in [MSC 2676](https://github.com/matrix-org/matrix-doc/pull/2676)) apart from From e1309e12c73c58b8a60053f3ac61e7d45cab4c24 Mon Sep 17 00:00:00 2001 From: Bruno Windels Date: Thu, 9 Sep 2021 14:23:33 +0200 Subject: [PATCH 35/46] fix typo --- proposals/2674-event-relationships.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2674-event-relationships.md b/proposals/2674-event-relationships.md index fc77711160..06afacf073 100644 --- a/proposals/2674-event-relationships.md +++ b/proposals/2674-event-relationships.md @@ -112,7 +112,7 @@ from normal redacted messages, and maintain reply ordering. This modification to the redaction algorithm requires a new room version. However, event relationships can still be used in existing room versions, but -the user experince may be worse if redactions are performed. +the user experience may be worse if redactions are performed. ## Potential issues From 5ec656da1fbc085aad2796dd3da663730eae6f5e Mon Sep 17 00:00:00 2001 From: Bruno Windels Date: Thu, 9 Sep 2021 15:21:01 +0200 Subject: [PATCH 36/46] split up redactions changes in separate MSC --- proposals/2674-event-relationships.md | 15 +++------------ 1 file changed, 3 insertions(+), 12 deletions(-) diff --git a/proposals/2674-event-relationships.md b/proposals/2674-event-relationships.md index 06afacf073..7bb9e21d10 100644 --- a/proposals/2674-event-relationships.md +++ b/proposals/2674-event-relationships.md @@ -99,18 +99,9 @@ events. Events with a relation may be redacted like any other event. -The `m.relates_to`.`rel_type` and `m.relates_to`.`event_id` fields should -be preserved over redactions, so that clients can still distinguish -redacted relations from other redacted events of the same event type. -If `m.relates_to` is not an object, or `m._relates_to` would be -an empty object after redacting any other keys, then `m.relates_to` -should also be removed from `content`. - -One example is telling redacted edits (as proposed in -[MSC 2676](https://github.com/matrix-org/matrix-doc/pull/2676)) apart from -from normal redacted messages, and maintain reply ordering. - -This modification to the redaction algorithm requires a new room version. +[MSC3389](https://github.com/matrix-org/matrix-doc/pull/3389) proposes that +the redaction algorithm should preserve the type and target id of a relation. + However, event relationships can still be used in existing room versions, but the user experience may be worse if redactions are performed. From 8cfda4d7fa4d73b58a3f63516951b3d06aaa3f63 Mon Sep 17 00:00:00 2001 From: Bruno Windels Date: Thu, 9 Sep 2021 15:22:23 +0200 Subject: [PATCH 37/46] also add new msc to introduction --- proposals/2674-event-relationships.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/proposals/2674-event-relationships.md b/proposals/2674-event-relationships.md index 7bb9e21d10..3cac065782 100644 --- a/proposals/2674-event-relationships.md +++ b/proposals/2674-event-relationships.md @@ -19,6 +19,9 @@ events to relate to each other. Together, these proposals replace mechanism. * [MSC3267](https://github.com/matrix-org/matrix-doc/pull/3267) defines how events can make a reference to other events. +* [MSC3389](https://github.com/matrix-org/matrix-doc/pull/3389) defines changes to + the redaction algorithm, to preserve the type and target id of a relation. + ## Proposal From f24945e762f5f72455dd8ff1e8ad31d96120dcc1 Mon Sep 17 00:00:00 2001 From: Bruno Windels Date: Thu, 9 Sep 2021 16:07:24 +0200 Subject: [PATCH 38/46] reword why not adopt m.in_reply_to --- proposals/2674-event-relationships.md | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/proposals/2674-event-relationships.md b/proposals/2674-event-relationships.md index 3cac065782..ffcd491d52 100644 --- a/proposals/2674-event-relationships.md +++ b/proposals/2674-event-relationships.md @@ -186,18 +186,21 @@ versus ``` The reasons to go with `rel_type` is: - * this format is now in use in the wider matrix ecosystem without a prefix, + * This format is now in use in the wider matrix ecosystem without a prefix, in spite of the original MSC 1849 not being merged. This situation is not ideal but we still don't want to break compatibility with several clients. - * we don't need the extra indirection to let multiple relations apply to a given pair of + * We don't need the extra indirection to let multiple relations apply to a given pair of events, as that should be expressed as separate relation events. - * if we want 'adverbs' to apply to 'verbs' in the subject-verb-object triples which + * If we want 'adverbs' to apply to 'verbs' in the subject-verb-object triples which relations form, then we apply it as mixins to the relation data itself rather than trying to construct subject-verb-verb-object sentences. - * so, we should pick a simpler shape rather than inheriting the mistakes of m.in_reply_to - and we have to keep ugly backwards compatibility around for m.in_reply_to - but we can entirely separately worry about migrating replies to new-style-aggregations in future - perhaps at the same time as doing threads. + * We decided to not adopt the format used by `m.in_reply_to` as it allows for multiple relations + and is hence overly flexible. Also, the relation type of `m.in_reply_to` is also overly specific + judged by the guidelines for `rel_type`s laid out in this MSC. Having replies use the same + format as relations is postponed to a later MSC, but it would likely involve replies + adopting the relation format with a more broadly useful `rel_type` (possibly the `m.reference` + type proposed in [MSC3267](https://github.com/matrix-org/matrix-doc/pull/3267)), + rather than relations adopting the replies format. ## Historical context From 46d1bff3e1106ed9fd8e75d94ba3e666aa57e335 Mon Sep 17 00:00:00 2001 From: Bruno Windels Date: Wed, 17 Nov 2021 09:58:30 +0100 Subject: [PATCH 39/46] remove guidelines how to pick rel_type --- proposals/2674-event-relationships.md | 31 ++++++++++++++++----------- 1 file changed, 18 insertions(+), 13 deletions(-) diff --git a/proposals/2674-event-relationships.md b/proposals/2674-event-relationships.md index ffcd491d52..7224ebbd5d 100644 --- a/proposals/2674-event-relationships.md +++ b/proposals/2674-event-relationships.md @@ -64,21 +64,26 @@ Relations do not yet replace the ### Relation types -This MSC does not define any value for `rel_type`, but rather defines the generic -framework that different kinds of relations have in common and that other MSCs can -build on. Future definitions for values of `rel_type` should describe *how* the server -should aggregate relations on the target event -(as proposed in [MSC 2675](https://github.com/matrix-org/matrix-doc/pull/2675)). -The goal is to make each `rel_type` as broadly useful as possible, -and to keep the number of types for a server implementation to support down to a minimum. - -Multiple client use cases may be served by a single `rel_type` if they require aggregation -in a similar manner. To further specify how a relation should be displayed in the client, -MSCs may define additional fields in `m.relates_to` for specific values of `rel_type`. - -Any values here should abide the +Any values for `rel_type` should abide the [general guidelines for identifiers](https://github.com/matrix-org/matrix-doc/pull/3171). +The `rel_type` property determines how an event relates to another and can be used +by clients to determine how and in what context a relation should be displayed. + +[MSC 2675](https://github.com/matrix-org/matrix-doc/pull/2675) proposes to also interpret the `rel_type` server-side. + +It is left up to the discretion of other MSCs building on this one whether they introduce +`rel_type`s that are specific to their use case or that can serve a broad range +of use cases. MSCs may define additional properties on the relation object for a given `rel_type`. + +Currently, a few `rel_type`s are already proposed. Here's a non-exhaustive list: + + - `m.replace` in [MSC 2676](https://github.com/matrix-org/matrix-doc/pull/2676). + - `m.annotation` in [MSC 2677](https://github.com/matrix-org/matrix-doc/pull/2677). + - `m.reference` in [MSC 3267](https://github.com/matrix-org/matrix-doc/pull/3267). + - `m.thread` in [MSC 3440](https://github.com/matrix-org/matrix-doc/pull/3440). + + ### Sending relations Related events are normal Matrix events, and can be sent by the normal `/send` From 8e1215260d2090956652d3efa506e2cb1653bfab Mon Sep 17 00:00:00 2001 From: Bruno Windels Date: Wed, 17 Nov 2021 10:04:36 +0100 Subject: [PATCH 40/46] mention that the target event must exist in the same room --- proposals/2674-event-relationships.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/proposals/2674-event-relationships.md b/proposals/2674-event-relationships.md index 7224ebbd5d..1cd2b8b817 100644 --- a/proposals/2674-event-relationships.md +++ b/proposals/2674-event-relationships.md @@ -29,7 +29,8 @@ This proposal introduces the concept of relations, which can be used to associate new information with an existing event. A relationship is an object with a field `rel_type`, which is a string describing the type of relation, -and a field `event_id`, which is a string that represents the event_id of the target of this relation. +and a field `event_id`, which is a string that represents the event_id of the target event of this relation. +The target event must exist in the same room as the relating event is sent. Both of those fields are required. An event is said to contain a relationship if their `content` contains a relationship with all the required fields under the `m.relates_to` key. If any of these conditions is not met, clients and servers should treat the event as if it does not contain a relationship. From 12fdf5590dd5850e723ee08f00ea6f53a9b2fa18 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Thu, 18 Nov 2021 10:59:04 +0000 Subject: [PATCH 41/46] spell out the conscious (subject, object, verb) triple idea. --- proposals/2674-event-relationships.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/proposals/2674-event-relationships.md b/proposals/2674-event-relationships.md index 1cd2b8b817..6fee0853da 100644 --- a/proposals/2674-event-relationships.md +++ b/proposals/2674-event-relationships.md @@ -55,7 +55,9 @@ where the subject is the relation event itself; the verb is the `rel_type` field of the `m.relates_to` and the object is the `event_id` field. We consciously do not support multiple different relations within a single event, -in order to keep the API simple. Another MSC, +in order to keep the API simple. This means that if event A relates to event B +in two different ways you would send two events to describe the two relations, +rather than bundling them into a single event. Another MSC, like [MSC 3051](https://github.com/matrix-org/matrix-doc/pull/3051), can propose a change to add support for multiple relations if it turns out that this would facilitate certain use cases. From 57cfb55fa3152d38db213348cc220b6dcb61e8e6 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sun, 21 Nov 2021 22:10:42 -0700 Subject: [PATCH 42/46] Spelling Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- proposals/2674-event-relationships.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2674-event-relationships.md b/proposals/2674-event-relationships.md index 6fee0853da..007a413914 100644 --- a/proposals/2674-event-relationships.md +++ b/proposals/2674-event-relationships.md @@ -31,7 +31,7 @@ associate new information with an existing event. A relationship is an object with a field `rel_type`, which is a string describing the type of relation, and a field `event_id`, which is a string that represents the event_id of the target event of this relation. The target event must exist in the same room as the relating event is sent. -Both of those fields are required. An event is said to contain a relationship if their `content` contains +Both of those fields are required. An event is said to contain a relationship if its `content` contains a relationship with all the required fields under the `m.relates_to` key. If any of these conditions is not met, clients and servers should treat the event as if it does not contain a relationship. From e0271331b2e7dee236349aa63eec3cec7369e361 Mon Sep 17 00:00:00 2001 From: Bruno Windels Date: Tue, 23 Nov 2021 14:40:07 +0100 Subject: [PATCH 43/46] remove paragraph saying what server should accept --- proposals/2674-event-relationships.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/proposals/2674-event-relationships.md b/proposals/2674-event-relationships.md index 007a413914..87f8228991 100644 --- a/proposals/2674-event-relationships.md +++ b/proposals/2674-event-relationships.md @@ -32,8 +32,7 @@ A relationship is an object with a field `rel_type`, which is a string describin and a field `event_id`, which is a string that represents the event_id of the target event of this relation. The target event must exist in the same room as the relating event is sent. Both of those fields are required. An event is said to contain a relationship if its `content` contains -a relationship with all the required fields under the `m.relates_to` key. If any of these conditions is not met, -clients and servers should treat the event as if it does not contain a relationship. +a relationship with all the required fields under the `m.relates_to` key. Here's a (partial) example of an event relating to another event: From 7cca8ac5aec16e55b62a9185a45460f6a7ff13b6 Mon Sep 17 00:00:00 2001 From: Bruno Windels Date: Tue, 23 Nov 2021 17:58:36 +0100 Subject: [PATCH 44/46] Revert "remove paragraph saying what server should accept" This reverts commit e0271331b2e7dee236349aa63eec3cec7369e361. --- proposals/2674-event-relationships.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/proposals/2674-event-relationships.md b/proposals/2674-event-relationships.md index 87f8228991..007a413914 100644 --- a/proposals/2674-event-relationships.md +++ b/proposals/2674-event-relationships.md @@ -32,7 +32,8 @@ A relationship is an object with a field `rel_type`, which is a string describin and a field `event_id`, which is a string that represents the event_id of the target event of this relation. The target event must exist in the same room as the relating event is sent. Both of those fields are required. An event is said to contain a relationship if its `content` contains -a relationship with all the required fields under the `m.relates_to` key. +a relationship with all the required fields under the `m.relates_to` key. If any of these conditions is not met, +clients and servers should treat the event as if it does not contain a relationship. Here's a (partial) example of an event relating to another event: From 12bdf0557ccfff919f65e262c3b1f0a5cc6a53d3 Mon Sep 17 00:00:00 2001 From: Bruno Windels Date: Tue, 23 Nov 2021 18:00:30 +0100 Subject: [PATCH 45/46] further specify that a server should reject invalid relations through the cs api --- proposals/2674-event-relationships.md | 1 + 1 file changed, 1 insertion(+) diff --git a/proposals/2674-event-relationships.md b/proposals/2674-event-relationships.md index 007a413914..00bc09e232 100644 --- a/proposals/2674-event-relationships.md +++ b/proposals/2674-event-relationships.md @@ -34,6 +34,7 @@ The target event must exist in the same room as the relating event is sent. Both of those fields are required. An event is said to contain a relationship if its `content` contains a relationship with all the required fields under the `m.relates_to` key. If any of these conditions is not met, clients and servers should treat the event as if it does not contain a relationship. +Servers should reject events not meeting these conditions with an HTTP 400 error when they are received via the client-server API Here's a (partial) example of an event relating to another event: From feb337739933461248241cca6c5d8b52d8110510 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 23 Nov 2021 10:34:18 -0700 Subject: [PATCH 46/46] linebreak Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- proposals/2674-event-relationships.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/proposals/2674-event-relationships.md b/proposals/2674-event-relationships.md index 00bc09e232..95f077bada 100644 --- a/proposals/2674-event-relationships.md +++ b/proposals/2674-event-relationships.md @@ -34,7 +34,8 @@ The target event must exist in the same room as the relating event is sent. Both of those fields are required. An event is said to contain a relationship if its `content` contains a relationship with all the required fields under the `m.relates_to` key. If any of these conditions is not met, clients and servers should treat the event as if it does not contain a relationship. -Servers should reject events not meeting these conditions with an HTTP 400 error when they are received via the client-server API +Servers should reject events not meeting these conditions with an HTTP 400 error when +they are received via the client-server API. Here's a (partial) example of an event relating to another event: