diff --git a/changelogs/client_server/newsfragments/1206.feature b/changelogs/client_server/newsfragments/1206.feature new file mode 100644 index 00000000..16bcd216 --- /dev/null +++ b/changelogs/client_server/newsfragments/1206.feature @@ -0,0 +1 @@ +Add `m.reference` relations, as per [MSC3267](https://github.com/matrix-org/matrix-spec-proposals/pull/3267). diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index a814144c..8c18bc4f 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -1974,6 +1974,7 @@ behaviour. This specification describes the following relationship types: * [Rich replies](#rich-replies) (**Note**: does not use `rel_type`). +* [References](#reference-relations) #### Aggregations @@ -2643,3 +2644,4 @@ systems. {{% cs-module name="server_notices" %}} {{% cs-module name="moderation_policies" %}} {{% cs-module name="spaces" %}} +{{< cs-module name="reference_relations" >}} diff --git a/content/client-server-api/modules/reference_relations.md b/content/client-server-api/modules/reference_relations.md new file mode 100644 index 00000000..52018caa --- /dev/null +++ b/content/client-server-api/modules/reference_relations.md @@ -0,0 +1,51 @@ +--- +type: module +--- + +### Reference relations + +{{% added-in v="1.4" %}} + +Generically referencing another event can be done with a `rel_type` of `m.reference` +as a form of [relationship](#forming-relationships-between-events). There is no +implied meaning behind the reference, and is usually context-dependent. Such an +example is the [key verification framework](#key-verification-framework) which uses +reference relations to associate distinct events with a specific verification attempt. + +When bundled, a reference relations appear as an object with a `chunk` field to +indicate all the events which `m.reference` the event (the parent). Currently, +only a single `event_id` field is present on the events in the `chunk`. + +{{% boxes/note %}} +Clients which wish to use threads or replies are expected to use other relationship +types than references. References are typically used to associate data rather than +messages. +{{% /boxes/note %}} + +An example `m.reference` would be: + +```json5 +{ + "content": { + "m.relates_to": { + "rel_type": "m.reference", + "event_id": "$another_event" + } + // other content fields as required + } + // other fields as required by events +} +``` + +The [bundle](#aggregations) under `m.relations` would appear similar to the following: + +```json5 +{ + "m.reference": { + "chunk": [ + { "event_id": "$one" }, + { "event_id": "$two" } + ] + } +} +``` diff --git a/data/event-schemas/schema/m.key.verification.m.relates_to.yaml b/data/event-schemas/schema/m.key.verification.m.relates_to.yaml index 670fd606..038344b9 100644 --- a/data/event-schemas/schema/m.key.verification.m.relates_to.yaml +++ b/data/event-schemas/schema/m.key.verification.m.relates_to.yaml @@ -10,7 +10,8 @@ properties: enum: - m.reference description: |- - The relationship type. + The relationship type. Currently, this can only be an + [`m.reference`](/client-server-api/#reference-relations) relationship type. event_id: type: string description: |-