Spec annotations (#1475)
Richard van der Hoff
1 year ago
committed by
GitHub
parent
a225025cab
commit
715f6a301d
@ -0,0 +1 @@
|
||||
Add `m.annotation` relations (reactions), as per [MSC2677](https://github.com/matrix-org/matrix-spec-proposals/pull/2677).
|
||||
@ -0,0 +1,93 @@
|
||||
### Event annotations and reactions
|
||||
|
||||
{{% added-in v="1.7" %}}
|
||||
|
||||
#### `m.annotation` relationship type
|
||||
|
||||
Annotations are events that use an [event
|
||||
relationship](#forming-relationships-between-events) with a `rel_type` of
|
||||
`m.annotation`.
|
||||
|
||||
Annotations are normally used for "reactions": for example, if the user wants
|
||||
to react to an event with a thumbs-up, then the client sends an annotation
|
||||
event with the corresponding emoji (👍). Another potential usage is to allow
|
||||
bots to send an event indicating the success or failure of a command.
|
||||
|
||||
Along with the normal properties `event_id` and `rel_type`, an `m.relates_to`
|
||||
property with `rel_type: m.annotion` should contain a `key` that indicates the
|
||||
annotation being applied. For example, when reacting with emojis, the key
|
||||
contains the emoji being used.
|
||||
|
||||
An example `m.annotation` relationship is shown below:
|
||||
|
||||
```json
|
||||
"m.relates_to": {
|
||||
"rel_type": "m.annotation",
|
||||
"event_id": "$some_event_id",
|
||||
"key": "👍"
|
||||
}
|
||||
```
|
||||
|
||||
{{% boxes/note %}}
|
||||
Any `type` of event is eligible for an annotation, including state events.
|
||||
{{% /boxes/note %}}
|
||||
|
||||
#### Events
|
||||
|
||||
{{% event event="m.reaction" %}}
|
||||
|
||||
#### Client behaviour {id="annotations-client-behaviour"}
|
||||
|
||||
The intention of annotations is that they are counted up, rather than being
|
||||
displayed individually. Clients must keep count of the number of annotations
|
||||
with a given event `type` and annotation `key` they observe for each event;
|
||||
these counts are typically presented alongside the event in the timeline.
|
||||
|
||||
When performing this count:
|
||||
|
||||
* Each event `type` and annotation `key` should normally be counted
|
||||
separately, though whether to actually do so is an implementation decision.
|
||||
|
||||
* Annotation events sent by [ignored users](#ignoring-users) should be
|
||||
excluded from the count.
|
||||
|
||||
* Multiple identical annotations (i.e., with the same event `type` and
|
||||
annotation `key`) from the same user (i.e., events with the same `sender`)
|
||||
should be treated as a single annotation.
|
||||
|
||||
* Implementations should ignore any annotation event which refers to an event
|
||||
which itself has an `m.relates_to` with `rel_type: m.annotation` or
|
||||
`rel_type: m.replace`. In other words, it is not possible to annotate a
|
||||
[replacement event](#event-replacements) or an annotation. Annotations should
|
||||
instead refer to the original event.
|
||||
|
||||
* When an annotation is redacted, it is removed from the count.
|
||||
|
||||
{{% boxes/note %}}
|
||||
It is not possible to edit a reaction, since replacement events do not change
|
||||
`m.relates_to` (see [Applying `m.new_content`](#applying-mnew_content)), and
|
||||
there is no other meaningful content within `m.reaction`. If a user wishes to
|
||||
change their reaction, the original reaction should be redacted and a new one
|
||||
sent in its place.
|
||||
{{% /boxes/note %}}
|
||||
|
||||
#### Server behaviour
|
||||
|
||||
##### Avoiding duplicate annotations
|
||||
|
||||
Homeservers should prevent users from sending a second annotation for a given
|
||||
event with identical event `type` and annotation `key` (unless the first event
|
||||
has been redacted).
|
||||
|
||||
Attempts to send such an annotation should be rejected with a 400 error and an
|
||||
error code of `M_DUPLICATE_ANNOTATION`.
|
||||
|
||||
Note that this does not guarantee that duplicate annotations will not arrive
|
||||
over federation. Clients are responsible for deduplicating received
|
||||
annotations when [counting annotations](#annotations-client-behaviour).
|
||||
|
||||
##### Server-side aggregation of `m.annotation` relationships
|
||||
|
||||
`m.annotation` relationships are *not*
|
||||
[aggregated](#aggregations-of-child-events) by the server. In other words,
|
||||
`m.annotation` is not included in the `m.relations` property.
|
||||
@ -0,0 +1,11 @@
|
||||
{
|
||||
"$ref": "core/room_event.json",
|
||||
"type": "m.reaction",
|
||||
"content": {
|
||||
"m.relates_to": {
|
||||
"rel_type": "m.annotation",
|
||||
"event_id": "$some_event_id",
|
||||
"key": "👍"
|
||||
}
|
||||
}
|
||||
}
|
||||
@ -0,0 +1,37 @@
|
||||
allOf:
|
||||
- $ref: core-event-schema/room_event.yaml
|
||||
description: |-
|
||||
Indicates a reaction to a previous event.
|
||||
|
||||
Has no defined `content` properties of its own. Its only purpose is to hold an
|
||||
[`m.relates_to`](/client-server-api/#definition-mrelates_to) property.
|
||||
|
||||
Since they contain no content other than `m.relates_to`, `m.reaction` events
|
||||
are normally not encrypted, as there would be no benefit in doing so.
|
||||
type: object
|
||||
properties:
|
||||
content:
|
||||
type: object
|
||||
properties:
|
||||
m.relates_to:
|
||||
description: |-
|
||||
Indicates the event being reacted to, and the type of reaction.
|
||||
type: object
|
||||
title: ReactionRelatesTo
|
||||
properties:
|
||||
rel_type:
|
||||
type: string
|
||||
enum: ["m.annotation"]
|
||||
event_id:
|
||||
type: string
|
||||
description: |-
|
||||
The event ID of the event that this is a reaction to.
|
||||
example: "$some_event_id"
|
||||
key:
|
||||
type: string
|
||||
description: |-
|
||||
An emoji representing the reaction being made. Should include the
|
||||
unicode emoji presentation selector (`\uFE0F`) for codepoints
|
||||
which allow it (see the [emoji variation sequences
|
||||
list](https://www.unicode.org/Public/UCD/latest/ucd/emoji/emoji-variation-sequences.txt)).
|
||||
example: "👍"
|
||||
Loading…
Reference in New Issue