Update spec for MSC3952: intentional mentions (#1508)

See MSC3952.

data/api/client-server/definitions/m.mentions.yaml

@@ -0,0 +1,37 @@
+# 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.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+type: object
+title: m.mentions
+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"]
+    }
+}
+properties:
+  user_ids:
+    type: string[]
+    description: A list of Matrix IDs of mentioned users.
+  room:
+    type: boolean
+    description: |-
+      A boolean set to `true` to mention the room, for an `@room` notification.
+      (`room` should otherwise not be included on the event.)