Fix schema of m.mentions object (#1635)

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

changelogs/internal/newsfragments/1635.clarification

@@ -0,0 +1 @@
+Fix schema of `m.mentions` object.

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

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!",
+    "user_ids": ["@alice:example.org"]
-    "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"]
-    }
 }
 properties:
   user_ids:
-    type: string[]
+    type: array
+    items:
+      type: string
     description: A list of Matrix IDs of mentioned users.
   room:
     type: boolean