From b36c24fb2cae97f76311ea0376a4b37785e104ce Mon Sep 17 00:00:00 2001 From: Bruno Windels Date: Mon, 5 Jul 2021 17:13:11 +0200 Subject: [PATCH 1/7] initial draft of reference relations msc --- proposals/xxxx-reference-relations.md | 56 +++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 proposals/xxxx-reference-relations.md diff --git a/proposals/xxxx-reference-relations.md b/proposals/xxxx-reference-relations.md new file mode 100644 index 00000000000..2d4a2454cd1 --- /dev/null +++ b/proposals/xxxx-reference-relations.md @@ -0,0 +1,56 @@ +# MSCXXXX: reference relationships + +## Proposal + +This proposal defines a relation type (using [MSC 2674 relations](https://github.com/matrix-org/matrix-doc/pull/2674)) for events to make a reference to another event. + +A `rel_type` of `m.reference` is defined for future handling replies and +threading. This let you define an event which references an existing +event. When aggregated, this currently doesn't do anything special, but in +future could bundle chains of references (i.e. threads). These do not yet +replace the [reply mechanism currently defined in the spec](https://matrix.org/docs/spec/client_server/latest#rich-replies). + +Reference relations are used by [MSC 2241](https://github.com/matrix-org/matrix-doc/pull/2241) to tie all events together for the same verification request. + +For instance, an `m.room.message` which references an existing event +would look like: + +```json +{ + "type": "m.room.message", + "content": { + "body": "i <3 shelties", + "m.relates_to": { + "rel_type": "m.reference", + "event_id": "$another_event_id" + } + } +} +``` + +## Server aggregation + +Even though [MSC 2674](https://github.com/matrix-org/matrix-doc/pull/2674) states that values for `rel_type` +should define how the server should aggregate the `rel_type`, this MSC does not define how references should be aggregated by the server on the target event. One possibly way would be to aggregate them as an array of event ids, but the final layout is deferred to [MSC 2675](https://github.com/matrix-org/matrix-doc/pull/2675). The aim of this MSC is to just document the status quo of how `m.reference` is used by [MSC 2241](https://github.com/matrix-org/matrix-doc/pull/2241), where server aggregations are not assumed by the client. + +## Limitations + +Different subtypes of references could be defined through additional fields on +the `m.relates_to` object, to distinguish between replies, threads, etc. +This MSC doesn't attempt to define these subtypes. + +## Edge Cases + +Can you reply (via m.references) to a [reaction](https://github.com/matrix-org/matrix-doc/pull/2677)/[edit](https://github.com/matrix-org/matrix-doc/pull/2677)? + * Yes, at the protocol level. But you shouldn't expect clients to do anything + useful with it. + * Replying to a reaction should be treated like a normal message and have the + reply behaviour ignored. + * Replying to an edit should be treated in the UI as if you had replied to + the original message. + +Do we need to support retrospective references? + * For something like "m.duplicate" to retrospectively declare that one event + dupes another, we might need to bundle two-levels deep (subject+ref and then + ref+target). We can cross this bridge when we get there though, as a 4th + aggregation type \ No newline at end of file From ab551e86309f150150671f17ce9d84dbcdb45c2c Mon Sep 17 00:00:00 2001 From: Bruno Windels Date: Mon, 5 Jul 2021 17:14:26 +0200 Subject: [PATCH 2/7] change MSC number --- ...{xxxx-reference-relations.md => 3267-reference-relations.md} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename proposals/{xxxx-reference-relations.md => 3267-reference-relations.md} (98%) diff --git a/proposals/xxxx-reference-relations.md b/proposals/3267-reference-relations.md similarity index 98% rename from proposals/xxxx-reference-relations.md rename to proposals/3267-reference-relations.md index 2d4a2454cd1..f6c94f22398 100644 --- a/proposals/xxxx-reference-relations.md +++ b/proposals/3267-reference-relations.md @@ -1,4 +1,4 @@ -# MSCXXXX: reference relationships +# MSC 3267: reference relationships ## Proposal From a5a2c616b5fe0950136a3085094fda0eb30e77b4 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 19 May 2022 19:48:00 -0600 Subject: [PATCH 3/7] Apply formatting --- proposals/3267-reference-relations.md | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/proposals/3267-reference-relations.md b/proposals/3267-reference-relations.md index f6c94f22398..ef1a51295e1 100644 --- a/proposals/3267-reference-relations.md +++ b/proposals/3267-reference-relations.md @@ -2,7 +2,9 @@ ## Proposal -This proposal defines a relation type (using [MSC 2674 relations](https://github.com/matrix-org/matrix-doc/pull/2674)) for events to make a reference to another event. +This proposal defines a relation type (using +[MSC2674 relations](https://github.com/matrix-org/matrix-doc/pull/2674)) +for events to make a reference to another event. A `rel_type` of `m.reference` is defined for future handling replies and threading. This let you define an event which references an existing @@ -10,7 +12,8 @@ event. When aggregated, this currently doesn't do anything special, but in future could bundle chains of references (i.e. threads). These do not yet replace the [reply mechanism currently defined in the spec](https://matrix.org/docs/spec/client_server/latest#rich-replies). -Reference relations are used by [MSC 2241](https://github.com/matrix-org/matrix-doc/pull/2241) to tie all events together for the same verification request. +Reference relations are used by [MSC 2241](https://github.com/matrix-org/matrix-doc/pull/2241) +to tie all events together for the same verification request. For instance, an `m.room.message` which references an existing event would look like: @@ -30,14 +33,20 @@ would look like: ## Server aggregation -Even though [MSC 2674](https://github.com/matrix-org/matrix-doc/pull/2674) states that values for `rel_type` -should define how the server should aggregate the `rel_type`, this MSC does not define how references should be aggregated by the server on the target event. One possibly way would be to aggregate them as an array of event ids, but the final layout is deferred to [MSC 2675](https://github.com/matrix-org/matrix-doc/pull/2675). The aim of this MSC is to just document the status quo of how `m.reference` is used by [MSC 2241](https://github.com/matrix-org/matrix-doc/pull/2241), where server aggregations are not assumed by the client. +Even though [MSC2674](https://github.com/matrix-org/matrix-doc/pull/2674) states +that values for `rel_type` should define how the server should aggregate the +`rel_type`, this MSC does not define how references should be aggregated by the +server on the target event. One possibly way would be to aggregate them as an +array of event ids, but the final layout is deferred to [MSC2675](https://github.com/matrix-org/matrix-doc/pull/2675). +The aim of this MSC is to just document the status quo of how `m.reference` +is used by [MSC2241](https://github.com/matrix-org/matrix-doc/pull/2241), where +server aggregations are not assumed by the client. ## Limitations Different subtypes of references could be defined through additional fields on the `m.relates_to` object, to distinguish between replies, threads, etc. -This MSC doesn't attempt to define these subtypes. +This MSC doesn't attempt to define these subtypes. ## Edge Cases @@ -53,4 +62,4 @@ 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 \ No newline at end of file + aggregation type From 62b5b0f07a1a52f76b37ff0c8867bad9a190490c Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 19 May 2022 19:53:05 -0600 Subject: [PATCH 4/7] Convert to point at present rather than ideal --- proposals/3267-reference-relations.md | 37 ++++++++++++++++----------- 1 file changed, 22 insertions(+), 15 deletions(-) diff --git a/proposals/3267-reference-relations.md b/proposals/3267-reference-relations.md index ef1a51295e1..fc124c9919d 100644 --- a/proposals/3267-reference-relations.md +++ b/proposals/3267-reference-relations.md @@ -1,4 +1,4 @@ -# MSC 3267: reference relationships +# MSC3267: reference relationships ## Proposal @@ -6,22 +6,25 @@ This proposal defines a relation type (using [MSC2674 relations](https://github.com/matrix-org/matrix-doc/pull/2674)) for events to make a reference to another event. -A `rel_type` of `m.reference` is defined for future handling replies and -threading. This let you define an event which references an existing -event. When aggregated, this currently doesn't do anything special, but in -future could bundle chains of references (i.e. threads). These do not yet -replace the [reply mechanism currently defined in the spec](https://matrix.org/docs/spec/client_server/latest#rich-replies). +A `rel_type` of `m.reference` is defined as a generic way to associate an +event with another event. There are no aggregation semantics applied to +this relation. -Reference relations are used by [MSC 2241](https://github.com/matrix-org/matrix-doc/pull/2241) +In future, this relation or similar could replace [replies](https://spec.matrix.org/v1.2/client-server-api/#rich-replies) +and aggregate into a chain of replies (simple threads). + +Reference relations are used by [MSC2241](https://github.com/matrix-org/matrix-doc/pull/2241) to tie all events together for the same verification request. For instance, an `m.room.message` which references an existing event would look like: -```json +```json5 { + // Unimportant fields omitted "type": "m.room.message", "content": { + "msgtype": "m.text", "body": "i <3 shelties", "m.relates_to": { "rel_type": "m.reference", @@ -33,14 +36,13 @@ would look like: ## Server aggregation -Even though [MSC2674](https://github.com/matrix-org/matrix-doc/pull/2674) states +[MSC2674](https://github.com/matrix-org/matrix-doc/pull/2674) states that values for `rel_type` should define how the server should aggregate the -`rel_type`, this MSC does not define how references should be aggregated by the -server on the target event. One possibly way would be to aggregate them as an -array of event ids, but the final layout is deferred to [MSC2675](https://github.com/matrix-org/matrix-doc/pull/2675). -The aim of this MSC is to just document the status quo of how `m.reference` -is used by [MSC2241](https://github.com/matrix-org/matrix-doc/pull/2241), where -server aggregations are not assumed by the client. +`rel_type`, and as such this MSC deliberately has no behaviour. + +In future, aggregation might be achieved with a list of event IDs for +representation by [MSC2675](https://github.com/matrix-org/matrix-doc/pull/2675) or +similar. ## Limitations @@ -63,3 +65,8 @@ Do we need to support retrospective references? 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 + +## Unstable prefix + +Unfortunately not applicable - this MSC was used in production and appears in the +specified version of the [key verification framework](https://spec.matrix.org/v1.2/client-server-api/#key-verification-framework). From 6eedd7af36659f4b5e4f3f7d51da96100f83daa0 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 20 May 2022 10:30:30 -0600 Subject: [PATCH 5/7] Clarify that multiple relations is a thing we don't have and won't fix here --- proposals/3267-reference-relations.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/proposals/3267-reference-relations.md b/proposals/3267-reference-relations.md index fc124c9919d..f41332807e8 100644 --- a/proposals/3267-reference-relations.md +++ b/proposals/3267-reference-relations.md @@ -11,7 +11,8 @@ event with another event. There are no aggregation semantics applied to this relation. In future, this relation or similar could replace [replies](https://spec.matrix.org/v1.2/client-server-api/#rich-replies) -and aggregate into a chain of replies (simple threads). +and aggregate into a chain of replies (simple threads), provided enough +maintenance goes into the system to support multiple relations (see limitations). Reference relations are used by [MSC2241](https://github.com/matrix-org/matrix-doc/pull/2241) to tie all events together for the same verification request. @@ -50,6 +51,10 @@ 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. +This relation cannot be used in conjunction with another relation due to `rel_type` +being a single value. This is known and unfortunately not resolved by this MSC. +A future MSC might address the concern. + ## 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)? From f37834d74d9b465654238c581afadba0deb6245d Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 26 May 2022 21:40:32 -0600 Subject: [PATCH 6/7] Fix wording to match reality, again --- proposals/3267-reference-relations.md | 49 +++++++++++++++++---------- 1 file changed, 32 insertions(+), 17 deletions(-) diff --git a/proposals/3267-reference-relations.md b/proposals/3267-reference-relations.md index f41332807e8..c4328d14adf 100644 --- a/proposals/3267-reference-relations.md +++ b/proposals/3267-reference-relations.md @@ -7,12 +7,16 @@ This proposal defines a relation type (using for events to make a reference to another event. A `rel_type` of `m.reference` is defined as a generic way to associate an -event with another event. There are no aggregation semantics applied to -this relation. +event with another event. As a bundle, `m.reference` relations appear as +an object with a single `chunk` field. The `chunk` is an array of objects +with a single `event_id` field for all the child events which `m.reference` +the parent. -In future, this relation or similar could replace [replies](https://spec.matrix.org/v1.2/client-server-api/#rich-replies) -and aggregate into a chain of replies (simple threads), provided enough -maintenance goes into the system to support multiple relations (see limitations). +There are no implied semantics by a reference relation: the feature or event +type which makes use of the `rel_type` should specify what sort of semantic +behaviour there is, if any. For example, describing that a poll response event +*references* the poll start event, or that a location update *references* a +previous location update. Reference relations are used by [MSC2241](https://github.com/matrix-org/matrix-doc/pull/2241) to tie all events together for the same verification request. @@ -39,17 +43,30 @@ would look like: [MSC2674](https://github.com/matrix-org/matrix-doc/pull/2674) states that values for `rel_type` should define how the server should aggregate the -`rel_type`, and as such this MSC deliberately has no behaviour. +`rel_type`. For `m.reference`, child events are bundled to appear as follows +under `m.relations`: -In future, aggregation might be achieved with a list of event IDs for -representation by [MSC2675](https://github.com/matrix-org/matrix-doc/pull/2675) or -similar. +```json5 +{ + "m.reference": { + "chunk": [ + {"event_id": "$one"}, + {"event_id": "$two"}, + {"event_id": "$three"} + ] + } +} +``` + +Note that currently only the `event_id` is noted in the chunk, however a future +MSC might add more fields. ## Limitations Different subtypes of references could be defined through additional fields on -the `m.relates_to` object, to distinguish between replies, threads, etc. -This MSC doesn't attempt to define these subtypes. +the `m.relates_to` object, to distinguish between other forms of semantic behaviour +indepdent of type (hypothetical threads, replies, etc if we didn't have a system +for them already). This MSC doesn't attempt to define these subtypes. This relation cannot be used in conjunction with another relation due to `rel_type` being a single value. This is known and unfortunately not resolved by this MSC. @@ -57,18 +74,16 @@ A future MSC might address the concern. ## 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)? +Can you reference an event which doesn't have logical meaning? Eg to a [reaction](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. + * The relationship is effectively pointless, so the event would appear as though + there was no reference relationship. 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 + ref+target). We can cross this bridge when we get there though, as another aggregation type ## Unstable prefix From 2c2d6ae1f9c8ef7c394eefee874890374f57398f Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 5 Jul 2022 18:05:31 +0100 Subject: [PATCH 7/7] fix a typo --- proposals/3267-reference-relations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3267-reference-relations.md b/proposals/3267-reference-relations.md index c4328d14adf..7b11d649f02 100644 --- a/proposals/3267-reference-relations.md +++ b/proposals/3267-reference-relations.md @@ -65,7 +65,7 @@ MSC might add more fields. Different subtypes of references could be defined through additional fields on the `m.relates_to` object, to distinguish between other forms of semantic behaviour -indepdent of type (hypothetical threads, replies, etc if we didn't have a system +independent of type (hypothetical threads, replies, etc if we didn't have a system for them already). This MSC doesn't attempt to define these subtypes. This relation cannot be used in conjunction with another relation due to `rel_type`