diff --git a/changelogs/internal/newsfragments/1635.clarification b/changelogs/internal/newsfragments/1635.clarification
new file mode 100644
index 000000000..a5bd245c6
--- /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 32309740e..0cdbad77c 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 Alice!",
+ "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 806897b41..271ee5c55 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 Alice!",
- "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