Merge 53150b739b into 6edb6ba1cd

* Clarify that SSO login applies to the legacy authentication API

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

* Do not point to specific authentication API for obtaining access token

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

* Add warnings about incompatibility with OAuth 2.0 to endpoints that use UIA

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

* Add changelog

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

* Add note about API standards not applying to OAuth 2.0

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

* Apply suggestions from code review

---------

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
Co-authored-by: Travis Ralston <travpc@gmail.com>

changelogs/application_service/newsfragments/2130.clarification

@@ -1 +0,0 @@
-Clarify in the application service registration schema the `url: null` behaviour.

changelogs/client_server/newsfragments/2068.clarification

@@ -1 +0,0 @@
-Clarify behaviour when the `topic` key of a `m.room.topic` event is absent, null, or empty.

changelogs/client_server/newsfragments/2077.clarification

@@ -1 +0,0 @@
-Fix the example of the `GET /sync` endpoint and the `m.room.member` example used in several places.

changelogs/client_server/newsfragments/2083.clarification

@@ -1 +0,0 @@
-Clarify the format of third-party invites, including the fact that identity server public keys can be encoded using standard or URL-safe base64.

changelogs/client_server/newsfragments/2095.feature

@@ -1 +0,0 @@
-Add `m.topic` content block to enable rich text in `m.room.topic` events as per [MSC3765](https://github.com/matrix-org/matrix-spec-proposals/pull/3765).

changelogs/client_server/newsfragments/2101.clarification

@@ -1 +0,0 @@
-"Public" rooms in profile look-ups are defined through their join rule and history visibility.

changelogs/client_server/newsfragments/2102.clarification

@@ -1 +0,0 @@
-"Public" rooms in user directory queries are defined through their join rule and history visibility.

changelogs/client_server/newsfragments/2104.clarification

@@ -1 +0,0 @@
-Rooms published in `/publicRooms` don't necessarily have `public` join rules or `world_readable` history visibility.

changelogs/client_server/newsfragments/2106.clarification

@@ -1 +0,0 @@
-"Public" rooms with respect to call invites are defined through their join rule.

changelogs/client_server/newsfragments/2107.clarification

@@ -1 +0,0 @@
-"Public" rooms have no specific meaning with respect to moderation policy lists.

changelogs/client_server/newsfragments/2108.clarification

@@ -1 +0,0 @@
-"Public" rooms with respect to presence are defined through their join rule.

changelogs/client_server/newsfragments/2109.clarification

@@ -1 +0,0 @@
-Spaces are subject to the same access mechanisms as rooms.

changelogs/client_server/newsfragments/2121.clarification

@@ -1 +0,0 @@
-Fix various typos throughout the specification.

changelogs/client_server/newsfragments/2122.feature

@@ -1 +0,0 @@
-Include device keys with Olm-encrypted events as per [MSC4147](https://github.com/matrix-org/matrix-spec-proposals/pull/4147).

changelogs/client_server/newsfragments/2125.feature

@@ -1 +0,0 @@
-Add `/_matrix/client/v1/room_summary/{roomIdOrAlias}` and extend `/_matrix/client/v1/rooms/{roomId}/hierarchy` with the new optional properties `allowed_room_ids`, `encryption` and `room_version` as per [MSC3266](https://github.com/matrix-org/matrix-spec-proposals/pull/3266).

changelogs/client_server/newsfragments/2125.new

@@ -1 +0,0 @@
-Add `GET /_matrix/client/v1/room_summary/{roomIdOrAlias}`, as per [MSC3266](https://github.com/matrix-org/matrix-spec-proposals/pull/3266).

changelogs/client_server/newsfragments/2140.clarification

@@ -1 +0,0 @@
-Clarify that Well-Known URIs are available on the server name's hostname. Contributed by @HarHarLinks.

changelogs/client_server/newsfragments/2141.feature

@@ -1 +0,0 @@
-Add the OAuth 2.0 based authentication API, as per [MSC3861](https://github.com/matrix-org/matrix-spec-proposals/pull/3861) and its sub-proposals.

changelogs/client_server/newsfragments/2144.clarification

@@ -1 +0,0 @@
-Fix various typos throughout the specification.

changelogs/client_server/newsfragments/2147.new

@@ -1 +0,0 @@
-Add `GET /_matrix/client/v1/auth_metadata`, as per [MSC2965](https://github.com/matrix-org/matrix-spec-proposals/pull/2965).

changelogs/client_server/newsfragments/2148.feature

@@ -1 +0,0 @@
-Add the OAuth 2.0 based authentication API, as per [MSC3861](https://github.com/matrix-org/matrix-spec-proposals/pull/3861) and its sub-proposals.

changelogs/client_server/newsfragments/2149.feature

@@ -1 +0,0 @@
-Add the OAuth 2.0 based authentication API, as per [MSC3861](https://github.com/matrix-org/matrix-spec-proposals/pull/3861) and its sub-proposals.

changelogs/client_server/newsfragments/2150.feature

@@ -1 +0,0 @@
-Add the OAuth 2.0 based authentication API, as per [MSC3861](https://github.com/matrix-org/matrix-spec-proposals/pull/3861) and its sub-proposals.

changelogs/client_server/newsfragments/2151.feature

@@ -1 +0,0 @@
-Add the OAuth 2.0 based authentication API, as per [MSC3861](https://github.com/matrix-org/matrix-spec-proposals/pull/3861) and its sub-proposals.

changelogs/client_server/newsfragments/2154.clarification

@@ -1 +0,0 @@
-Add missing fields in example for `ExportedSessionData`.

changelogs/client_server/newsfragments/2158.feature

@@ -1 +0,0 @@
-Add `/_matrix/client/v1/room_summary/{roomIdOrAlias}` and extend `/_matrix/client/v1/rooms/{roomId}/hierarchy` with the new optional properties `allowed_room_ids`, `encryption` and `room_version` as per [MSC3266](https://github.com/matrix-org/matrix-spec-proposals/pull/3266).

changelogs/client_server/newsfragments/2159.feature

@@ -1 +0,0 @@
-Add the OAuth 2.0 based authentication API, as per [MSC3861](https://github.com/matrix-org/matrix-spec-proposals/pull/3861) and its sub-proposals.

changelogs/client_server/newsfragments/2167.clarification

@@ -0,0 +1 @@
+Clarify that `format` is required if `formatted_body` is specified.

changelogs/identity_service/newsfragments/2083.clarification

@@ -1 +0,0 @@
-Clarify that public keys can be encoded using standard or URL-safe base64.

changelogs/internal/newsfragments/2081.clarification

@@ -1 +0,0 @@
-Adjust margins in rendered endpoints.

changelogs/internal/newsfragments/2088.clarification

@@ -1 +0,0 @@
-Replace Hugo shortcodes in OpenAPI output.

changelogs/internal/newsfragments/2115.clarification

@@ -1 +0,0 @@
-Add [well-known funding manifest urls](https://floss.fund/funding-manifest/) to spec to authorise https://matrix.org/funding.json. Contributed by @HarHarLinks.

changelogs/internal/newsfragments/2123.clarification

@@ -1 +0,0 @@
-Fix the historical info box when generating the historical spec in CI.

changelogs/internal/newsfragments/2137.clarification

@@ -1 +0,0 @@
-Update the header navigation menu with links to modern matrix.org. Contributed by @HarHarLinks.

changelogs/server_server/newsfragments/2067.clarification

@@ -1 +0,0 @@
-Add a note to the invite endpoints that invites to local users may be received twice over federation if the homeserver is already in the room.

changelogs/server_server/newsfragments/2083.clarification

@@ -1 +0,0 @@
-Clarify the format of third-party invites, including the fact that identity server public keys can be encoded using standard or URL-safe base64.

changelogs/server_server/newsfragments/2095.feature

@@ -1 +0,0 @@
-Add `m.topic` content block to enable rich text in `m.room.topic` events as per [MSC3765](https://github.com/matrix-org/matrix-spec-proposals/pull/3765).

changelogs/server_server/newsfragments/2100.clarification

@@ -1 +0,0 @@
-Clarify that auth event of `content.join_authorised_via_users_server` is only necessary for `m.room.member` with a `membership` of `join`.

changelogs/server_server/newsfragments/2104.clarification

@@ -1 +0,0 @@
-Rooms published in `/publicRooms` don't necessarily have `public` join rules or `world_readable` history visibility.

changelogs/server_server/newsfragments/2125.feature

@@ -1 +0,0 @@
-Extend `/_matrix/federation/v1/hierarchy/{roomId}` with the new optional properties `encryption` and `room_version` as per [MSC3266](https://github.com/matrix-org/matrix-spec-proposals/pull/3266).

changelogs/server_server/newsfragments/2128.clarification

@@ -1 +0,0 @@
-Fix various typos throughout the specification.

changelogs/server_server/newsfragments/2140.clarification

@@ -1 +0,0 @@
-Clarify that Well-Known URIs are available on the server name's hostname. Contributed by @HarHarLinks.

config/_default/hugo.toml

@@ -67,7 +67,7 @@ current_version_url = "https://spec.matrix.org/latest"
 # The following is used when status = "stable", and is displayed in various UI elements on a released version
 # of the spec.
 # major = "1"
-# minor = "14"
+# minor = "15"
 
 # User interface configuration
 [params.ui]

content/changelog/v1.15.md

@@ -0,0 +1,97 @@
+---
+title: v1.15 Changelog
+linkTitle: v1.15
+type: docs
+layout: changelog
+outputs:
+  - html
+  - checklist
+date: 2025-06-26
+---
+
+## Client-Server API
+
+**New Endpoints**
+
+- Add `GET /_matrix/client/v1/room_summary/{roomIdOrAlias}`, as per [MSC3266](https://github.com/matrix-org/matrix-spec-proposals/pull/3266). ([#2125](https://github.com/matrix-org/matrix-spec/issues/2125))
+- Add `GET /_matrix/client/v1/auth_metadata`, as per [MSC2965](https://github.com/matrix-org/matrix-spec-proposals/pull/2965). ([#2147](https://github.com/matrix-org/matrix-spec/issues/2147))
+
+**Backwards Compatible Changes**
+
+- Add `m.topic` content block to enable rich text in `m.room.topic` events as per [MSC3765](https://github.com/matrix-org/matrix-spec-proposals/pull/3765). ([#2095](https://github.com/matrix-org/matrix-spec/issues/2095))
+- Include device keys with Olm-encrypted events as per [MSC4147](https://github.com/matrix-org/matrix-spec-proposals/pull/4147). ([#2122](https://github.com/matrix-org/matrix-spec/issues/2122))
+- Add `/_matrix/client/v1/room_summary/{roomIdOrAlias}` and extend `/_matrix/client/v1/rooms/{roomId}/hierarchy` with the new optional properties `allowed_room_ids`, `encryption` and `room_version` as per [MSC3266](https://github.com/matrix-org/matrix-spec-proposals/pull/3266). ([#2125](https://github.com/matrix-org/matrix-spec/issues/2125), [#2158](https://github.com/matrix-org/matrix-spec/issues/2158))
+- Add the OAuth 2.0 based authentication API, as per [MSC3861](https://github.com/matrix-org/matrix-spec-proposals/pull/3861) and its sub-proposals. ([#2141](https://github.com/matrix-org/matrix-spec/issues/2141), [#2148](https://github.com/matrix-org/matrix-spec/issues/2148), [#2149](https://github.com/matrix-org/matrix-spec/issues/2149), [#2150](https://github.com/matrix-org/matrix-spec/issues/2150), [#2151](https://github.com/matrix-org/matrix-spec/issues/2151), [#2159](https://github.com/matrix-org/matrix-spec/issues/2159), [#2164](https://github.com/matrix-org/matrix-spec/issues/2164))
+
+**Spec Clarifications**
+
+- Clarify behaviour when the `topic` key of a `m.room.topic` event is absent, null, or empty. ([#2068](https://github.com/matrix-org/matrix-spec/issues/2068))
+- Fix the example of the `GET /sync` endpoint and the `m.room.member` example used in several places. ([#2077](https://github.com/matrix-org/matrix-spec/issues/2077))
+- Clarify the format of third-party invites, including the fact that identity server public keys can be encoded using standard or URL-safe base64. ([#2083](https://github.com/matrix-org/matrix-spec/issues/2083))
+- "Public" rooms in profile look-ups are defined through their join rule and history visibility. ([#2101](https://github.com/matrix-org/matrix-spec/issues/2101))
+- "Public" rooms in user directory queries are defined through their join rule and history visibility. ([#2102](https://github.com/matrix-org/matrix-spec/issues/2102))
+- Rooms published in `/publicRooms` don't necessarily have `public` join rules or `world_readable` history visibility. ([#2104](https://github.com/matrix-org/matrix-spec/issues/2104))
+- "Public" rooms with respect to call invites are defined through their join rule. ([#2106](https://github.com/matrix-org/matrix-spec/issues/2106))
+- "Public" rooms have no specific meaning with respect to moderation policy lists. ([#2107](https://github.com/matrix-org/matrix-spec/issues/2107))
+- "Public" rooms with respect to presence are defined through their join rule. ([#2108](https://github.com/matrix-org/matrix-spec/issues/2108))
+- Spaces are subject to the same access mechanisms as rooms. ([#2109](https://github.com/matrix-org/matrix-spec/issues/2109))
+- Fix various typos throughout the specification. ([#2121](https://github.com/matrix-org/matrix-spec/issues/2121), [#2144](https://github.com/matrix-org/matrix-spec/issues/2144))
+- Clarify that Well-Known URIs are available on the server name's hostname. Contributed by @HarHarLinks. ([#2140](https://github.com/matrix-org/matrix-spec/issues/2140))
+- Add missing fields in example for `ExportedSessionData`. ([#2154](https://github.com/matrix-org/matrix-spec/issues/2154))
+
+
+## Server-Server API
+
+**Backwards Compatible Changes**
+
+- Add `m.topic` content block to enable rich text in `m.room.topic` events as per [MSC3765](https://github.com/matrix-org/matrix-spec-proposals/pull/3765). ([#2095](https://github.com/matrix-org/matrix-spec/issues/2095))
+- Extend `/_matrix/federation/v1/hierarchy/{roomId}` with the new optional properties `encryption` and `room_version` as per [MSC3266](https://github.com/matrix-org/matrix-spec-proposals/pull/3266). ([#2125](https://github.com/matrix-org/matrix-spec/issues/2125))
+
+**Spec Clarifications**
+
+- Add a note to the invite endpoints that invites to local users may be received twice over federation if the homeserver is already in the room. ([#2067](https://github.com/matrix-org/matrix-spec/issues/2067))
+- Clarify the format of third-party invites, including the fact that identity server public keys can be encoded using standard or URL-safe base64. ([#2083](https://github.com/matrix-org/matrix-spec/issues/2083))
+- Clarify that auth event of `content.join_authorised_via_users_server` is only necessary for `m.room.member` with a `membership` of `join`. ([#2100](https://github.com/matrix-org/matrix-spec/issues/2100))
+- Rooms published in `/publicRooms` don't necessarily have `public` join rules or `world_readable` history visibility. ([#2104](https://github.com/matrix-org/matrix-spec/issues/2104))
+- Fix various typos throughout the specification. ([#2128](https://github.com/matrix-org/matrix-spec/issues/2128))
+- Clarify that Well-Known URIs are available on the server name's hostname. Contributed by @HarHarLinks. ([#2140](https://github.com/matrix-org/matrix-spec/issues/2140))
+
+
+## Application Service API
+
+**Spec Clarifications**
+
+- Clarify in the application service registration schema the `url: null` behaviour. ([#2130](https://github.com/matrix-org/matrix-spec/issues/2130))
+
+
+## Identity Service API
+
+**Spec Clarifications**
+
+- Clarify that public keys can be encoded using standard or URL-safe base64. ([#2083](https://github.com/matrix-org/matrix-spec/issues/2083))
+
+
+## Push Gateway API
+
+No significant changes.
+
+
+## Room Versions
+
+No significant changes.
+
+
+## Appendices
+
+No significant changes.
+
+
+## Internal Changes/Tooling
+
+**Spec Clarifications**
+
+- Adjust margins in rendered endpoints. ([#2081](https://github.com/matrix-org/matrix-spec/issues/2081))
+- Replace Hugo shortcodes in OpenAPI output. ([#2088](https://github.com/matrix-org/matrix-spec/issues/2088))
+- Add [well-known funding manifest urls](https://floss.fund/funding-manifest/) to spec to authorise https://matrix.org/funding.json. Contributed by @HarHarLinks. ([#2115](https://github.com/matrix-org/matrix-spec/issues/2115))
+- Fix the historical info box when generating the historical spec in CI. ([#2123](https://github.com/matrix-org/matrix-spec/issues/2123))
+- Update the header navigation menu with links to modern matrix.org. Contributed by @HarHarLinks. ([#2137](https://github.com/matrix-org/matrix-spec/issues/2137))

content/client-server-api/_index.md

@@ -12,6 +12,12 @@ clients which maintain a full local persistent copy of server state.
 
 ## API Standards
 
+{{% boxes/note %}}
+These standards only apply to the APIs defined in the Matrix specification. APIs
+used by this specification but defined in other specifications, like the [OAuth
+2.0 API](#oauth-20-api), use their own rules.
+{{% /boxes/note %}}
+
 The mandatory baseline for client-server communication in Matrix is
 exchanging JSON objects over HTTP APIs. More efficient transports may be
 specified in future as optional extensions.

content/client-server-api/modules/sso_login.md

@@ -6,9 +6,10 @@ allow users to log into applications via a single web-based
 authentication portal. Examples include OpenID Connect, "Central
 Authentication Service" (CAS) and SAML.
 
-This module allows a Matrix homeserver to delegate user authentication
+This module allows a Matrix homeserver that supports the [legacy authentication
-to an external authentication server supporting one of these protocols.
+API](#legacy-api) to delegate user authentication to an external authentication
-In this process, there are three systems involved:
+server supporting one of these protocols. In this process, there are three
+systems involved:
 
 -   A Matrix client, using the APIs defined in this specification, which
     is seeking to authenticate a user to a Matrix homeserver.
@@ -24,7 +25,7 @@ used to communicate with the authentication server. Different Matrix
 homeserver implementations might support different SSO protocols.
 
 Clients and homeservers implementing the SSO flow will need to consider
-both [login](#login) and [user-interactive authentication](#user-interactive-authentication-api). The flow is
+both [login](#legacy-login) and [user-interactive authentication](#user-interactive-authentication-api). The flow is
 similar in both cases, but there are slight differences.
 
 Typically, SSO systems require a single "callback" URI to be configured

data/api/client-server/administrative_contact.yaml

@@ -201,6 +201,11 @@ paths:
 
         Homeservers should prevent the caller from adding a 3PID to their account if it has
         already been added to another user's account on the homeserver.
+
+        {{% boxes/warning %}}
+        Since this endpoint uses User-Interactive Authentication, it cannot be used when the access token was obtained
+        via the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
+        {{% /boxes/warning %}}
       operationId: add3PID
       security:
         - accessTokenQuery: []

data/api/client-server/cross_signing.yaml

@@ -26,7 +26,7 @@ paths:
         Publishes cross-signing keys for the user.
 
         This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).
-        
+
         User-Interactive Authentication MUST be performed, except in these cases:
         - there is no existing cross-signing master key uploaded to the homeserver, OR
         - there is an existing cross-signing master key and it exactly matches the
@@ -34,11 +34,16 @@ paths:
           keys provided in the request (self-signing key, user-signing key) they MUST also
           match the existing keys stored on the server. In other words, the request contains
           no new keys.
-        
+
         This allows clients to freely upload one set of keys, but not modify/overwrite keys if
-        they already exist. Allowing clients to upload the same set of keys more than once 
+        they already exist. Allowing clients to upload the same set of keys more than once
         makes this endpoint idempotent in the case where the response is lost over the network,
         which would otherwise cause a UIA challenge upon retry.
+
+        {{% boxes/warning %}}
+        When this endpoint requires User-Interactive Authentication, it cannot be used when the access token was obtained
+        via the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
+        {{% /boxes/warning %}}
       operationId: uploadCrossSigningKeys
       security:
         - accessTokenQuery: []

data/api/client-server/definitions/security.yaml

@@ -14,8 +14,8 @@
 accessTokenQuery:
   type: apiKey
   description: |-
-    **Deprecated.** The `access_token` returned by a call to `/login` or `/register`, as a query
+    **Deprecated.** The `access_token` obtained during [account registration](/client-server-api/#account-registration)
-    parameter.
+    or [login](/client-server-api/#login), as a query parameter.
 
     It can also be the `as_token` of an application service.
   name: access_token
@@ -23,11 +23,11 @@ accessTokenQuery:
 accessTokenBearer:
   type: http
   description: |-
-    The `access_token` returned by a call to `/login` or `/register`, using the
+    The `access_token` obtained during [account registration](/client-server-api/#account-registration)
-    `Authorization: Bearer` header.
+    or [login](/client-server-api/#login), using the `Authorization: Bearer` header.
 
     It can also be the `as_token` of an application service.
-    
+
     This is the preferred method.
   scheme: bearer
 appserviceAccessTokenQuery:
@@ -42,6 +42,6 @@ appserviceAccessTokenBearer:
   description: |-
     The `as_token` of an application service, using the `Authorization: Bearer`
     header.
-    
+
     This is the preferred method.
   scheme: bearer

data/api/client-server/device_management.yaml

@@ -137,6 +137,11 @@ paths:
         This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).
 
         Deletes the given device, and invalidates any access token associated with it.
+
+        {{% boxes/warning %}}
+        Since this endpoint uses User-Interactive Authentication, it cannot be used when the access token was obtained
+        via the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
+        {{% /boxes/warning %}}
       operationId: deleteDevice
       security:
         - accessTokenQuery: []
@@ -189,6 +194,11 @@ paths:
         This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).
 
         Deletes the given devices, and invalidates any access token associated with them.
+
+        {{% boxes/warning %}}
+        Since this endpoint uses User-Interactive Authentication, it cannot be used when the access token was obtained
+        via the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
+        {{% /boxes/warning %}}
       operationId: deleteDevices
       security:
         - accessTokenQuery: []

data/event-schemas/schema/m.room.message$m.audio.yaml

@@ -15,8 +15,8 @@ properties:
           "1.10": This property can act as a caption for the audio.
       format:
         description: |-
-          The format used in the `formatted_body`. Currently only
+          The format used in the `formatted_body`. This is required if `formatted_body`
-          `org.matrix.custom.html` is supported.
+          is specified. Currently only `org.matrix.custom.html` is supported.
         type: string
         x-addedInMatrixVersion: "1.10"
       formatted_body:

data/event-schemas/schema/m.room.message$m.emote.yaml

@@ -14,8 +14,8 @@ properties:
         type: string
       format:
         description: |-
-          The format used in the `formatted_body`. Currently only
+          The format used in the `formatted_body`. This is required if `formatted_body`
-          `org.matrix.custom.html` is supported.
+          is specified. Currently only `org.matrix.custom.html` is supported.
         type: string
       formatted_body:
         description: |-

data/event-schemas/schema/m.room.message$m.file.yaml

@@ -15,8 +15,8 @@ properties:
           "1.10": This property can act as a caption for the file.
       format:
         description: |-
-          The format used in the `formatted_body`. Currently only
+          The format used in the `formatted_body`. This is required if `formatted_body`
-          `org.matrix.custom.html` is supported.
+          is specified. Currently only `org.matrix.custom.html` is supported.
         type: string
         x-addedInMatrixVersion: "1.10"
       formatted_body:

data/event-schemas/schema/m.room.message$m.image.yaml

@@ -15,8 +15,8 @@ properties:
           "1.10": This property can act as a caption for the image.
       format:
         description: |-
-          The format used in the `formatted_body`. Currently only
+          The format used in the `formatted_body`. This is required if `formatted_body`
-          `org.matrix.custom.html` is supported.
+          is specified. Currently only `org.matrix.custom.html` is supported.
         type: string
         x-addedInMatrixVersion: "1.10"
       formatted_body:

data/event-schemas/schema/m.room.message$m.key.verification.request.yaml

@@ -22,8 +22,8 @@ properties:
           verification.
       format:
         description: |-
-          The format used in the `formatted_body`. Currently only
+          The format used in the `formatted_body`. This is required if `formatted_body`
-          `org.matrix.custom.html` is supported.
+          is specified. Currently only `org.matrix.custom.html` is supported.
         type: string
       formatted_body:
         description: |-

data/event-schemas/schema/m.room.message$m.notice.yaml

@@ -14,8 +14,8 @@ properties:
         type: string
       format:
         description: |-
-          The format used in the `formatted_body`. Currently only
+          The format used in the `formatted_body`. This is required if `formatted_body`
-          `org.matrix.custom.html` is supported.
+          is specified. Currently only `org.matrix.custom.html` is supported.
         type: string
       formatted_body:
         description: |-

data/event-schemas/schema/m.room.message$m.text.yaml

@@ -14,8 +14,8 @@ properties:
         type: string
       format:
         description: |-
-          The format used in the `formatted_body`. Currently only
+          The format used in the `formatted_body`. This is required if `formatted_body`
-          `org.matrix.custom.html` is supported.
+          is specified. Currently only `org.matrix.custom.html` is supported.
         type: string
       formatted_body:
         description: |-

data/event-schemas/schema/m.room.message$m.video.yaml

@@ -15,8 +15,8 @@ properties:
           "1.10": This property can act as a caption for the video.
       format:
         description: |-
-          The format used in the `formatted_body`. Currently only
+          The format used in the `formatted_body`. This is required if `formatted_body`
-          `org.matrix.custom.html` is supported.
+          is specified. Currently only `org.matrix.custom.html` is supported.
         type: string
         x-addedInMatrixVersion: "1.10"
       formatted_body: