Spec annotations (#1475)

data/api/client-server/room_send.yaml

@@ -1,4 +1,5 @@
 # Copyright 2016 OpenMarket Ltd
+# Copyright 2023 The Matrix.org Foundation C.I.C.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -88,5 +89,13 @@ paths:
                   A unique identifier for the event.
             required:
               - event_id
+        400:
+          description: |-
+            The request is invalid. A [standard error response](/client-server-api/#standard-error-response)
+            will be returned. As well as the normal common error codes, other reasons for rejection include:
+
+            - `M_DUPLICATE_ANNOTATION`: The request is an attempt to send a [duplicate annotation](/client-server-api/#avoiding-duplicate-annotations).
+          schema:
+            "$ref": "definitions/errors/error.yaml"
       tags:
         - Room participation

data/event-schemas/examples/m.reaction.yaml

@@ -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": "👍"
+        }
+    }
+}

data/event-schemas/schema/m.reaction.yaml

@@ -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: "👍"