From df3f0af5d4b89cf14ece827f01b52bab19f3a888 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Commaille?=
 <76261501+zecakeh@users.noreply.github.com>
Date: Tue, 19 Sep 2023 17:59:00 +0200
Subject: [PATCH] Fix schema of `m.mentions` object (#1635)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
---
 .../internal/newsfragments/1635.clarification      |  1 +
 content/client-server-api/modules/mentions.md      | 14 ++++++++++++++
 data/api/client-server/definitions/m.mentions.yaml | 12 ++++--------
 3 files changed, 19 insertions(+), 8 deletions(-)
 create mode 100644 changelogs/internal/newsfragments/1635.clarification

diff --git a/changelogs/internal/newsfragments/1635.clarification b/changelogs/internal/newsfragments/1635.clarification
new file mode 100644
index 00000000..a5bd245c
--- /dev/null
+++ b/changelogs/internal/newsfragments/1635.clarification
@@ -0,0 +1 @@
+Fix schema of `m.mentions` object.
diff --git a/content/client-server-api/modules/mentions.md b/content/client-server-api/modules/mentions.md
index 32309740..0cdbad77 100644
--- a/content/client-server-api/modules/mentions.md
+++ b/content/client-server-api/modules/mentions.md
@@ -13,6 +13,20 @@ the event to reference the entity being mentioned.
 
 {{% definition path="api/client-server/definitions/m.mentions" %}}
 
+An event's content will then look like this:
+
+```json
+{
+    "body": "Hello Alice!",
+    "msgtype": "m.text",
+    "format": "org.matrix.custom.html",
+    "formatted_body": "Hello <a href='https://matrix.to/#/@alice:example.org'>Alice</a>!",
+    "m.mentions": {
+        "user_ids": ["@alice:example.org"]
+    }
+}
+```
+
 Additionally, see the [`.m.rule.is_user_mention`](#_m_rule_is_user_mention) and
 [`.m.rule.is_room_mention`](#_m_rule_is_room_mention) push rules.
 Users should not add their own Matrix ID to the `m.mentions` property as outgoing
diff --git a/data/api/client-server/definitions/m.mentions.yaml b/data/api/client-server/definitions/m.mentions.yaml
index 806897b4..271ee5c5 100644
--- a/data/api/client-server/definitions/m.mentions.yaml
+++ b/data/api/client-server/definitions/m.mentions.yaml
@@ -18,17 +18,13 @@ description: |-
   Describes whether the event mentions other users or the room. This is contained
   within the event's `content` alongside other fields for the relevant event type.
 example: {
-    "body": "Hello Alice!",
-    "msgtype": "m.text",
-    "format": "org.matrix.custom.html",
-    "formatted_body": "Hello <a href='https://matrix.to/#/@alice:example.org'>Alice</a>!",
-    "m.mentions": {
-        "user_ids": ["@alice:example.org"]
-    }
+    "user_ids": ["@alice:example.org"]
 }
 properties:
   user_ids:
-    type: string[]
+    type: array
+    items:
+      type: string
     description: A list of Matrix IDs of mentioned users.
   room:
     type: boolean