From 9e1a60a2c3ae112b9bfed87ae7289d5e6cf328a2 Mon Sep 17 00:00:00 2001
From: Patrick Cloke <patrickc@matrix.org>
Date: Tue, 16 May 2023 11:58:07 -0400
Subject: [PATCH] Use jsonschema.

---
 content/client-server-api/modules/mentions.md | 23 ++----------
 .../client-server/definitions/m.mentions.yaml | 37 +++++++++++++++++++
 2 files changed, 41 insertions(+), 19 deletions(-)
 create mode 100644 data/api/client-server/definitions/m.mentions.yaml

diff --git a/content/client-server-api/modules/mentions.md b/content/client-server-api/modules/mentions.md
index 8a6478de..21ac54c0 100644
--- a/content/client-server-api/modules/mentions.md
+++ b/content/client-server-api/modules/mentions.md
@@ -7,11 +7,11 @@ This module allows users to "mention" other users and rooms within a room event.
 This is primarily used as an indicator that the recipient should receive a notification
 about the event.
 This is achieved by including metadata in the `m.mentions` content property of
-the event. The `m.mentions` property consists of an object with two fields:
+the event to reference the entity being mentioned.
 
-* `user_ids`: A list of Matrix IDs of mentioned users.
-* `room`: A boolean set to `true` to mention the room, for an `@room` notification. (`room` should otherwise
-  not be included on the event.)
+`m.mentions` is defined as follows:
+
+{{% definition path="api/client-server/definitions/m.mentions" %}}
 
 Although it is possible to silently mention users, it is recommended to include a
 [Matrix URI](/appendices/#uris) in the HTML body of  an [m.room.message](#mroommessage)
@@ -19,21 +19,6 @@ event. This applies only to [m.room.message](#mroommessage) events where the `ms
 `m.text`, `m.emote`, or `m.notice`. The `format` for the event must be
 `org.matrix.custom.html` and therefore requires a `formatted_body`.
 
-To make a mention, reference the entity being mentioned in the
-`m.mentions` property, like so:
-
-```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"]
-    }
-}
-```
-
 Similarly, the entire room can be mentioned:
 
 ```json
diff --git a/data/api/client-server/definitions/m.mentions.yaml b/data/api/client-server/definitions/m.mentions.yaml
new file mode 100644
index 00000000..806897b4
--- /dev/null
+++ b/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.)