Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2026-02-19 20:43:42 +01:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

Merge branch 'main' into johannes/msc3765

Browse source
This commit is contained in:
Richard van der Hoff 2025-04-29 17:15:17 +01:00 committed by GitHub
parent 7f0431b95f fca171427f
commit 760745bdc2
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
70 changed files with 596 additions and 263 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

26
assets/scss/_styles_project.scss
View file

@ -316,13 +316,19 @@ Custom SCSS for the Matrix spec
h2 { h2 {
font-weight: $font-weight-bold; font-weight: $font-weight-bold;
font-size: 1.3rem; font-size: 1.3rem;
margin: 3rem 0 .5rem 0; margin: 1.5rem 0 1rem 0;
} }
h3 { h3 {
font-weight: $font-weight-bold; font-weight: $font-weight-bold;
font-size: 1.1rem; font-size: 1.1rem;
margin: 1.5rem 0 .75rem 0; margin: 1.5rem 0 1rem 0;
}
/* Reduce top margin of h3 if previous sibling is a h2 */
h2 + h3 {
margin-top: 1rem;
} }
hr { hr {
@ -367,11 +373,6 @@ Custom SCSS for the Matrix spec
} }
} }
// add some space between two tables when they are right next to each other
& + table {
margin-top: 4rem;
}
caption { caption {
caption-side: top; caption-side: top;
color: $dark; color: $dark;
@ -443,6 +444,17 @@ Custom SCSS for the Matrix spec
} }
} }
/* Have consistent spacing around tables and examples */
table, .highlight {
margin-top: 0;
margin-bottom: 2rem;
/* We don't need the margin on the last child of the .rendered-data block */
&:last-child {
margin-bottom: 0;
}
}
pre { pre {
border: 0; border: 0;
border-left: solid 5px $secondary; border-left: solid 5px $secondary;

1
changelogs/appendices/newsfragments/1506.clarification
View file

@ -1 +0,0 @@
Clarify that arbitrary unicode is allowed in user/room IDs and room aliases.

1
changelogs/client_server/newsfragments/2036.clarification
View file

@ -1 +0,0 @@
The `POST /_matrix/client/v3/rooms/{roomId}/initialSync` endpoint is no longer deprecated, as it is still used for peeking.

1
changelogs/client_server/newsfragments/2038.clarification
View file

@ -1 +0,0 @@
Clarify wording in the `/join` endpoints' summaries and descriptions. Contributed by @HarHarLinks.

1
changelogs/client_server/newsfragments/2046.clarification
View file

@ -1 +0,0 @@
Clarify formats of string types.

2
changelogs/client_server/newsfragments/2051.clarification
View file

@ -1,2 +0,0 @@
Document the `instance_id` field of `Protocol Instance` in the responses to
`GET /_matrix/client/v3/thirdparty/protocols` and `GET /_matrix/client/v3/thirdparty/protocol/{protocol}`.

1
changelogs/client_server/newsfragments/2055.clarification
View file

@ -1 +0,0 @@
Applying redactions is a SHOULD for clients.

1
changelogs/client_server/newsfragments/2059.removal
View file

@ -1 +0,0 @@
Remove `server_name` parameter from `/_matrix/client/v3/join/{roomIdOrAlias}` and `/_matrix/client/v3/knock/{roomIdOrAlias}` as per [MSC4213](https://github.com/matrix-org/matrix-spec-proposals/pull/4213).

1
changelogs/client_server/newsfragments/2064.clarification
View file

@ -1 +0,0 @@
Clarify which rooms are returned from `/hierarchy`.

1
changelogs/client_server/newsfragments/2068.clarification Normal file
View file

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

1
changelogs/client_server/newsfragments/2072.clarification
View file

@ -1 +0,0 @@
Clients can choose which history visibility options they offer to users when creating rooms.

1
changelogs/client_server/newsfragments/2077.clarification Normal file
View file

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

1
changelogs/client_server/newsfragments/2080.clarification
View file

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

2
changelogs/client_server/newsfragments/2083.clarification Normal file
View file

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

1
changelogs/client_server/newsfragments/2091.clarification
View file

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

0
changelogs/client_server/newsfragments/2047.clarification → changelogs/client_server/newsfragments/2121.clarification
View file

1
changelogs/identity_service/newsfragments/2083.clarification Normal file
View file

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

1
changelogs/internal/newsfragments/2033.clarification
View file

@ -1 +0,0 @@
Generate the changelog release info with Hugo, rather than the changelog generation script.

1
changelogs/internal/newsfragments/2041.clarification
View file

@ -1 +0,0 @@
Update release steps documentation.

1
changelogs/internal/newsfragments/2042.clarification
View file

@ -1 +0,0 @@
Remove unused `release_date` from Hugo config.

1
changelogs/internal/newsfragments/2045.clarification
View file

@ -1 +0,0 @@
Clarify that v1.0 of Matrix was a release prior to the current global versioning system.

1
changelogs/internal/newsfragments/2049.clarification
View file

@ -1 +0,0 @@
Fix syntax highlighting and click-to-copy buttons for code blocks by purging less CSS.

1
changelogs/internal/newsfragments/2061.clarification
View file

@ -1 +0,0 @@
Fix the version of the Identity Service API when Matrix 1.0 was introduced.

1
changelogs/internal/newsfragments/2069.clarification
View file

@ -1 +0,0 @@
Fix parsing of nested slices in `resolve-refs` and `resolve-allof` partials.

1
changelogs/internal/newsfragments/2073.clarification
View file

@ -1 +0,0 @@
Deduplicate the definition of `RoomKeysUpdateResponse`.

1
changelogs/internal/newsfragments/2074.clarification
View file

@ -1 +0,0 @@
Deduplicate the definitions of `Invite3pid`.

1
changelogs/internal/newsfragments/2076.clarification
View file

@ -1 +0,0 @@
Support more locations for examples in OpenAPI definitions and JSON schemas.

1
changelogs/internal/newsfragments/2078.clarification
View file

@ -1 +0,0 @@
Add link to the git commit for the unstable changelog.

1
changelogs/internal/newsfragments/2081.clarification Normal file
View file

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

1
changelogs/internal/newsfragments/2115.clarification Normal file
View file

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

1
changelogs/room_versions/newsfragments/2065.clarification
View file

@ -1 +0,0 @@
For room versions 6 and 7, clarify in the authorization rules that `m.federate` must be checked and that events with rejected auth events must be rejected, for parity with all the other room versions.

1
changelogs/room_versions/newsfragments/2066.clarification
View file

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

1
changelogs/room_versions/newsfragments/2070.clarification
View file

@ -1 +0,0 @@
Refactor PDU definitions to reduce duplication.

1
changelogs/server_server/newsfragments/2050.clarification
View file

@ -1 +0,0 @@
Remove the `origin` field in `PUT /send_join` responses, because it was never sent in the first place.

1
changelogs/server_server/newsfragments/2063.clarification
View file

@ -1 +0,0 @@
Clarify that `m.join_rules` should be in the `auth_events` of an `m.room.member` event with a `membership` of `knock`.

1
changelogs/server_server/newsfragments/2076.clarification
View file

@ -1 +0,0 @@
Remove an erroneous `room_id` field in a few examples.

2
changelogs/server_server/newsfragments/2083.clarification Normal file
View file

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

0
changelogs/client_server/newsfragments/2048.clarification → changelogs/server_server/newsfragments/2128.clarification
View file

2
config/_default/hugo.toml
View file

@ -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 # The following is used when status = "stable", and is displayed in various UI elements on a released version
# of the spec. # of the spec.
# major = "1" # major = "1"
# minor = "13" # minor = "14"
# User interface configuration # User interface configuration
[params.ui] [params.ui]

93
content/changelog/v1.14.md Normal file
View file

@ -0,0 +1,93 @@
---
title: v1.14 Changelog
linkTitle: v1.14
type: docs
layout: changelog
outputs:
- html
- checklist
date: 2025-03-27
---
## Client-Server API
**New Endpoints**
- Add `POST /_matrix/client/v3/users/{userId}/report`, as per [MSC4260](https://github.com/matrix-org/matrix-spec-proposals/pull/4260). ([#2093](https://github.com/matrix-org/matrix-spec/issues/2093))
**Removed Endpoints**
- Remove `server_name` parameter from `/_matrix/client/v3/join/{roomIdOrAlias}` and `/_matrix/client/v3/knock/{roomIdOrAlias}`, as per [MSC4213](https://github.com/matrix-org/matrix-spec-proposals/pull/4213). ([#2059](https://github.com/matrix-org/matrix-spec/issues/2059))
**Spec Clarifications**
- The `POST /_matrix/client/v3/rooms/{roomId}/initialSync` endpoint is no longer deprecated, as it is still used for peeking. ([#2036](https://github.com/matrix-org/matrix-spec/issues/2036))
- Clarify wording in the `/join` endpoints' summaries and descriptions. Contributed by @HarHarLinks. ([#2038](https://github.com/matrix-org/matrix-spec/issues/2038))
- Clarify formats of string types. ([#2046](https://github.com/matrix-org/matrix-spec/issues/2046))
- Fix various typos throughout the specification. ([#2047](https://github.com/matrix-org/matrix-spec/issues/2047), [#2048](https://github.com/matrix-org/matrix-spec/issues/2048), [#2080](https://github.com/matrix-org/matrix-spec/issues/2080), [#2091](https://github.com/matrix-org/matrix-spec/issues/2091))
- Document the `instance_id` field of `Protocol Instance` in the responses to `GET /_matrix/client/v3/thirdparty/protocols` and `GET /_matrix/client/v3/thirdparty/protocol/{protocol}`. ([#2051](https://github.com/matrix-org/matrix-spec/issues/2051))
- Applying redactions is a SHOULD for clients. ([#2055](https://github.com/matrix-org/matrix-spec/issues/2055))
- Clarify which rooms are returned from `/hierarchy`. ([#2064](https://github.com/matrix-org/matrix-spec/issues/2064))
- Clients can choose which history visibility options they offer to users when creating rooms. ([#2072](https://github.com/matrix-org/matrix-spec/issues/2072))
## Server-Server API
**Spec Clarifications**
- Remove the `origin` field in `PUT /send_join` responses, because it was never sent in the first place. ([#2050](https://github.com/matrix-org/matrix-spec/issues/2050))
- Clarify that `m.join_rules` should be in the `auth_events` of an `m.room.member` event with a `membership` of `knock`. ([#2063](https://github.com/matrix-org/matrix-spec/issues/2063))
- Remove an erroneous `room_id` field in a few examples. ([#2076](https://github.com/matrix-org/matrix-spec/issues/2076))
## Application Service API
No significant changes.
## Identity Service API
No significant changes.
## Push Gateway API
No significant changes.
## Room Versions
**Backwards Compatible Changes**
- Update the default room version to 11, as per [MSC4239](https://github.com/matrix-org/matrix-spec-proposals/pull/4239). ([#2105](https://github.com/matrix-org/matrix-spec/issues/2105))
**Spec Clarifications**
- For room versions 6 and 7, clarify in the authorization rules that `m.federate` must be checked and that events with rejected auth events must be rejected, for parity with all the other room versions. ([#2065](https://github.com/matrix-org/matrix-spec/issues/2065))
- Fix various typos throughout the specification. ([#2066](https://github.com/matrix-org/matrix-spec/issues/2066))
- Refactor PDU definitions to reduce duplication. ([#2070](https://github.com/matrix-org/matrix-spec/issues/2070))
- Clarify the maximum `depth` value for room versions 6, 7, 8, 9, 10, and 11. ([#2114](https://github.com/matrix-org/matrix-spec/issues/2114))
## Appendices
**Spec Clarifications**
- Clarify that arbitrary unicode is allowed in user/room IDs and room aliases. ([#1506](https://github.com/matrix-org/matrix-spec/issues/1506))
## Internal Changes/Tooling
**Spec Clarifications**
- Generate the changelog release info with Hugo, rather than the changelog generation script. ([#2033](https://github.com/matrix-org/matrix-spec/issues/2033))
- Update release steps documentation. ([#2041](https://github.com/matrix-org/matrix-spec/issues/2041))
- Remove unused `release_date` from Hugo config. ([#2042](https://github.com/matrix-org/matrix-spec/issues/2042))
- Clarify that v1.0 of Matrix was a release prior to the current global versioning system. ([#2045](https://github.com/matrix-org/matrix-spec/issues/2045))
- Fix syntax highlighting and click-to-copy buttons for code blocks by purging less CSS. ([#2049](https://github.com/matrix-org/matrix-spec/issues/2049))
- Fix the version of the Identity Service API when Matrix 1.0 was introduced. ([#2061](https://github.com/matrix-org/matrix-spec/issues/2061))
- Fix parsing of nested slices in `resolve-refs` and `resolve-allof` partials. ([#2069](https://github.com/matrix-org/matrix-spec/issues/2069))
- Deduplicate the definition of `RoomKeysUpdateResponse`. ([#2073](https://github.com/matrix-org/matrix-spec/issues/2073))
- Deduplicate the definitions of `Invite3pid`. ([#2074](https://github.com/matrix-org/matrix-spec/issues/2074))
- Support more locations for examples in OpenAPI definitions and JSON schemas. ([#2076](https://github.com/matrix-org/matrix-spec/issues/2076))
- Add link to the git commit for the unstable changelog. ([#2078](https://github.com/matrix-org/matrix-spec/issues/2078))

6
content/client-server-api/modules/report_content.md
View file

@ -29,3 +29,9 @@ is in before accepting a report.
based on whether or not the reporting user is joined to the room. This is based on whether or not the reporting user is joined to the room. This is
because users can be exposed to harmful content without being joined to a because users can be exposed to harmful content without being joined to a
room. For instance, through room directories or invites. room. For instance, through room directories or invites.
{{% added-in v="1.14" %}} Similarly, servers MUST NOT restrict user reports
based on whether or not the reporting user is joined to any rooms that the
reported user is joined to. This is because users can be exposed to harmful
content without being joined to a room. For instance, through user
directories or invites.

2
content/client-server-api/modules/secrets.md
View file

@ -58,7 +58,7 @@ available on all their clients. Unless the user specifies otherwise,
clients will try to use the default key to decrypt secrets. clients will try to use the default key to decrypt secrets.
Clients that want to present a simplified interface to users by not supporting Clients that want to present a simplified interface to users by not supporting
multiple keys should use the default key if one is specified. If not default multiple keys should use the default key if one is specified. If no default
key is specified, the client may behave as if there is no key is present at key is specified, the client may behave as if there is no key is present at
all. When such a client creates a key, it should mark that key as being the all. When such a client creates a key, it should mark that key as being the
default key. default key.

46
content/client-server-api/modules/third_party_invites.md
View file

@ -5,8 +5,8 @@ This module adds in support for inviting new members to a room where
their Matrix user ID is not known, instead addressing them by a third-party their Matrix user ID is not known, instead addressing them by a third-party
identifier such as an email address. There are two flows here; one identifier such as an email address. There are two flows here; one
if a Matrix user ID is known for the third-party identifier, and one if if a Matrix user ID is known for the third-party identifier, and one if
not. Either way, the client calls [`/invite`](#post_matrixclientv3roomsroomidinvite) with the details of the not. Either way, the client calls [`/invite`](#thirdparty_post_matrixclientv3roomsroomidinvite)
third-party identifier. with the details of the third-party identifier.
The homeserver asks the identity server whether a Matrix user ID is The homeserver asks the identity server whether a Matrix user ID is
known for that identifier: known for that identifier:
@ -37,10 +37,12 @@ A client asks a server to invite a user by their third-party identifier.
#### Server behaviour #### Server behaviour
Upon receipt of an [`/invite`](#post_matrixclientv3roomsroomidinvite), the server is expected to look up the Upon receipt of an [`/invite`](#thirdparty_post_matrixclientv3roomsroomidinvite),
third-party identifier with the provided identity server. If the lookup the server is expected to look up the third-party identifier with the provided
yields a result for a Matrix User ID then the normal invite process can identity server by making a call to [`/_matrix/identity/v2/lookup`](/identity-service-api/#post_matrixidentityv2lookup).
be initiated. This process ends up looking like this: If the lookup yields a result for a Matrix User ID then the normal [invite
process](/server-server-api/#inviting-to-a-room) can be initiated. This process
ends up looking like this:
``` ```
+---------+ +-------------+ +-----------------+ +---------+ +-------------+ +-----------------+
@ -66,10 +68,11 @@ be initiated. This process ends up looking like this:
| | | | | |
``` ```
However, if the lookup does not yield a bound User ID, the homeserver However, if the lookup does not yield a bound User ID, the homeserver must store
must store the invite on the identity server and emit a valid the invite on the identity server with a call to
`m.room.third_party_invite` event to the room. This process ends up [`/_matrix/identity/v2/store-invite`](/identity-service-api/#post_matrixidentityv2store-invite)
looking like this: and emit a valid [`m.room.third_party_invite`](#mroomthird_party_invite) event
to the room. This process ends up looking like this:
``` ```
+---------+ +-------------+ +-----------------+ +---------+ +-------------+ +-----------------+
@ -101,15 +104,18 @@ looking like this:
| | | | | |
``` ```
All homeservers MUST verify the signature in the event's The third-party user will then need to verify their identity, which results in a
`content.third_party_invite.signed` object. request to [`/_matrix/federation/v1/3pid/onbind`](/server-server-api/#put_matrixfederationv13pidonbind)
from the identity server to the homeserver that bound the third-party identifier
to a user. The homeserver then exchanges the `m.room.third_party_invite` event
in the room for a complete [`m.room.member`](#mroommember) event with
`content.membership: invite` and a `content.third_party_invite` property for the
user that has bound the third-party identifier. If the invitee is on a different
homeserver than the inviting user, the invitee's homeserver makes a request to
[`/_matrix/federation/v1/exchange_third_party_invite/{roomId}`](/server-server-api/#put_matrixfederationv1exchange_third_party_inviteroomid).
The third-party user will then need to verify their identity, which All homeservers MUST verify the signature in the `m.room.member` event's
results in a call from the identity server to the homeserver that bound `content.third_party_invite.signed` object.
the third-party identifier to a user. The homeserver then exchanges the
`m.room.third_party_invite` event in the room for a complete
`m.room.member` event for `membership: invite` for the user that has
bound the third-party identifier.
If a homeserver is joining a room for the first time because of an If a homeserver is joining a room for the first time because of an
`m.room.third_party_invite`, the server which is already participating `m.room.third_party_invite`, the server which is already participating
@ -193,8 +199,8 @@ at any time - the completion is not shown in the diagram.
H1 MUST verify the request from H3 to ensure the `signed` property is H1 MUST verify the request from H3 to ensure the `signed` property is
correct as well as the `key_validity_url` as still being valid. This is correct as well as the `key_validity_url` as still being valid. This is
done by making a request to the [identity server done by making a request to the identity server's
/isvalid](/identity-service-api/#get_matrixidentityv2pubkeyisvalid) [`/pubkey/isvalid`](/identity-service-api/#get_matrixidentityv2pubkeyisvalid)
endpoint, using the provided URL rather than constructing a new one. The endpoint, using the provided URL rather than constructing a new one. The
query string and response for the provided URL must match the Identity query string and response for the provided URL must match the Identity
Service Specification. Service Specification.

2
content/rooms/_index.md
View file

@ -52,7 +52,7 @@ stable and unstable periodically for a variety of reasons, including
discovered security vulnerabilities and age. discovered security vulnerabilities and age.
Clients should not ask room administrators to upgrade their rooms if the Clients should not ask room administrators to upgrade their rooms if the
room is running a stable version. Servers SHOULD use **room version 10** as room is running a stable version. Servers SHOULD use **room version 11** as
the default room version when creating new rooms. the default room version when creating new rooms.
The available room versions are: The available room versions are:

4
content/rooms/fragments/v6-event-format.md Normal file
View file

@ -0,0 +1,4 @@
Events in rooms of this version have the following structure:
{{% definition path="api/server-server/definitions/pdu_v6" %}}

2
content/rooms/v10.md
View file

@ -281,7 +281,7 @@ completeness.
### Event format ### Event format
{{% rver-fragment name="v4-event-format" %}} {{% rver-fragment name="v6-event-format" %}}
### State resolution ### State resolution

11
content/rooms/v6.md
View file

@ -39,6 +39,13 @@ in [room version 5](/rooms/v5).
[See above](#redactions). [See above](#redactions).
### Event format
{{% added-in v=6 %}} Through enforcement of [Canonical JSON](#canonical-json),
the `depth` limit has been reduced in this room version.
{{% rver-fragment name="v6-event-format" %}}
### Authorization rules ### Authorization rules
{{% added-in v=6 %}} Rule 4, which related specifically to events {{% added-in v=6 %}} Rule 4, which related specifically to events
@ -229,10 +236,6 @@ completeness.
{{% rver-fragment name="v4-event-ids" %}} {{% rver-fragment name="v4-event-ids" %}}
### Event format
{{% rver-fragment name="v4-event-format" %}}
#### Deprecated event content schemas #### Deprecated event content schemas
{{% rver-fragment name="v1-deprecated-formatting-off-spec" %}} {{% rver-fragment name="v1-deprecated-formatting-off-spec" %}}

2
content/rooms/v7.md
View file

@ -225,7 +225,7 @@ completeness.
### Event format ### Event format
{{% rver-fragment name="v4-event-format" %}} {{% rver-fragment name="v6-event-format" %}}
#### Deprecated event content schemas #### Deprecated event content schemas

2
content/rooms/v8.md
View file

@ -109,7 +109,7 @@ completeness.
### Event format ### Event format
{{% rver-fragment name="v4-event-format" %}} {{% rver-fragment name="v6-event-format" %}}
#### Deprecated event content schemas #### Deprecated event content schemas

2
content/rooms/v9.md
View file

@ -74,7 +74,7 @@ completeness.
### Event format ### Event format
{{% rver-fragment name="v4-event-format" %}} {{% rver-fragment name="v6-event-format" %}}
#### Deprecated event content schemas #### Deprecated event content schemas

46
content/server-server-api.md
View file

@ -970,9 +970,8 @@ the event to other servers in the room.
## Third-party invites ## Third-party invites
{{% boxes/note %}} {{% boxes/note %}}
More information about third-party invites is available in the More information about third-party invites is available in the Client-Server API
[Client-Server API](/client-server-api) under under the [Third-party invites](/client-server-api/#third-party-invites) module.
the Third-party Invites module.
{{% /boxes/note %}} {{% /boxes/note %}}
When a user wants to invite another user in a room but doesn't know the When a user wants to invite another user in a room but doesn't know the
@ -985,38 +984,41 @@ API](/identity-service-api).
### Cases where an association exists for a third-party identifier ### Cases where an association exists for a third-party identifier
If the third-party identifier is already bound to a Matrix ID, a lookup If the third-party identifier is already bound to a Matrix ID, a [lookup
request on the identity server will return it. The invite is then request](/identity-service-api/#post_matrixidentityv2lookup) on the identity
processed by the inviting homeserver as a standard `m.room.member` server will return it. The invite is then processed by the inviting homeserver
invite event. This is the simplest case. as a [standard `m.room.member` invite event](#inviting-to-a-room). This is the
simplest case.
### Cases where an association doesn't exist for a third-party identifier ### Cases where an association doesn't exist for a third-party identifier
If the third-party identifier isn't bound to any Matrix ID, the inviting If the third-party identifier isn't bound to any Matrix ID, the inviting
homeserver will request the identity server to store an invite for this homeserver will request the identity server to [store an invite](/identity-service-api/#invitation-storage)
identifier and to deliver it to whoever binds it to its Matrix ID. It for this identifier and to deliver it to whoever binds it to its Matrix ID. It
will also send an `m.room.third_party_invite` event in the room to will also send an [`m.room.third_party_invite`](/client-server-api/#mroomthird_party_invite)
specify a display name, a token and public keys the identity server event in the room to specify a display name, a token and public keys the
provided as a response to the invite storage request. identity server provided as a response to the invite storage request.
When a third-party identifier with pending invites gets bound to a When a third-party identifier with pending invites gets bound to a Matrix ID,
Matrix ID, the identity server will send a POST request to the ID's the identity server will send a request to the [`/3pid/onbind`](#put_matrixfederationv13pidonbind)
homeserver as described in the [Invitation endpoint of the the ID's homeserver as described in the [Invitation
Storage](/identity-service-api#invitation-storage) Storage](/identity-service-api#invitation-storage) section of the Identity
section of the Identity Service API. Service API.
The following process applies for each invite sent by the identity The following process applies for each invite sent by the identity
server: server:
The invited homeserver will create an `m.room.member` invite event The invited homeserver will create an [`m.room.member`](/client-server-api/#mroommember)
containing a special `third_party_invite` section containing the token invite event containing a special `third_party_invite` section containing the
and a signed object, both provided by the identity server. token and a `signed` object, both provided by the identity server.
If the invited homeserver is in the room the invite came from, it can If the invited homeserver is in the room the invite came from, it can
auth the event and send it. auth the event and send it.
However, if the invited homeserver isn't in the room the invite came However, if the invited homeserver isn't in the room the invite came
from, it will need to request the room's homeserver to auth the event. from, it will need to request the inviting homeserver to auth the event
at the [`/exchange_third_party_invite`](#put_matrixfederationv1exchange_third_party_inviteroomid)
endpoint.
{{% http-api spec="server-server" api="third_party_invite" %}} {{% http-api spec="server-server" api="third_party_invite" %}}
@ -1337,7 +1339,7 @@ calculated as follows.
The *content hash* of an event covers the complete event including the The *content hash* of an event covers the complete event including the
*unredacted* contents. It is calculated as follows. *unredacted* contents. It is calculated as follows.
First, any existing `unsigned`, `signature`, and `hashes` members are First, any existing `unsigned`, `signatures`, and `hashes` properties are
removed. The resulting object is then encoded as [Canonical removed. The resulting object is then encoded as [Canonical
JSON](/appendices#canonical-json), and the JSON is hashed using JSON](/appendices#canonical-json), and the JSON is hashed using
SHA-256. SHA-256.

97
data/api/client-server/report_content.yaml
View file

@ -45,7 +45,9 @@ paths:
properties: properties:
reason: reason:
type: string type: string
description: The reason the room is being reported. description: The reason the room is being reported. May be blank.
required:
- reason
required: true required: true
security: security:
- accessTokenQuery: [] - accessTokenQuery: []
@ -88,12 +90,11 @@ paths:
Reports an event as inappropriate to the server, which may then notify Reports an event as inappropriate to the server, which may then notify
the appropriate people. The caller must be joined to the room to report the appropriate people. The caller must be joined to the room to report
it. it.
It might be possible for clients to deduce whether an event exists by Furthermore, it might be possible for clients to deduce whether a reported
timing the response, as only a report for an event that does exist event exists by timing the response. This is because only a report for an
will require the homeserver to check whether a user is joined to existing event will require the homeserver to do further processing. To
the room. To combat this, homeserver implementations should add combat this, homeservers MAY add a random delay when generating a response.
a random delay when generating a response.
operationId: reportEvent operationId: reportEvent
parameters: parameters:
- in: path - in: path
@ -164,6 +165,88 @@ paths:
} }
tags: tags:
- Reporting content - Reporting content
"/users/{userId}/report":
post:
x-addedInMatrixVersion: "1.14"
summary: Report a user as inappropriate.
description: |-
Reports a user as inappropriate to the server, which may then notify
the appropriate people. How such information is delivered is left up to
implementations. The caller is not required to be joined to any rooms
that the reported user is joined to.
Clients may wish to [ignore](#ignoring-users) users after reporting them.
Clients could infer whether a reported user exists based on the 404 response.
Homeservers that wish to conceal this information MAY return 200 responses
regardless of the existence of the reported user.
Furthermore, it might be possible for clients to deduce whether a reported
user exists by timing the response. This is because only a report for an
existing user will require the homeserver to do further processing. To
combat this, homeservers MAY add a random delay when generating a response.
operationId: reportUser
parameters:
- in: path
name: userId
description: The user being reported.
required: true
example: "@someguy:example.com"
schema:
type: string
format: mx-user-id
pattern: "^@"
requestBody:
content:
application/json:
schema:
type: object
example: {
"reason": "this makes me sad"
}
properties:
reason:
type: string
description: The reason the room is being reported. May be blank.
required:
- reason
required: true
security:
- accessTokenQuery: []
- accessTokenBearer: []
responses:
"200":
description: |
The user has been reported successfully or the server chose
to not disclose whether the users exists.
content:
application/json:
schema:
type: object
examples:
response:
value: {}
"404":
description: |-
The user was not found on the homeserver.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "The user was not found."
}
"429":
description: This request was rate-limited.
content:
application/json:
schema:
$ref: definitions/errors/rate_limited.yaml
tags:
- Reporting content
servers: servers:
- url: "{protocol}://{hostname}{basePath}" - url: "{protocol}://{hostname}{basePath}"
variables: variables:

46
data/api/client-server/sync.yaml
View file

@ -441,17 +441,57 @@ paths:
"state": { "state": {
"events": [ "events": [
{ {
"$ref": "../../event-schemas/examples/m.room.member.yaml" "content": {
"avatar_url": "mxc://example.org/SFHyPlCeYUSFFxlgbQYZmoEoe",
"displayname": "Example user",
"membership": "join"
},
"event_id": "$143273976499sgjks:example.org",
"origin_server_ts": 1432735824653,
"sender": "@example:example.org",
"state_key": "@example:example.org",
"type": "m.room.member",
"unsigned": {
"age": 45603,
"membership": "join"
}
} }
] ]
}, },
"timeline": { "timeline": {
"events": [ "events": [
{ {
"$ref": "../../event-schemas/examples/m.room.member.yaml" "content": {
"avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF",
"displayname": "Alice Margatroid",
"membership": "join",
"reason": "Looking for support"
},
"event_id": "$143273582443PhrSn:example.org",
"origin_server_ts": 1432735824653,
"sender": "@alice:example.org",
"state_key": "@alice:example.org",
"type": "m.room.member",
"unsigned": {
"age": 1234,
"membership": "join"
}
}, },
{ {
"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" "content": {
"body": "This is an example text message",
"format": "org.matrix.custom.html",
"formatted_body": "<b>This is an example text message</b>",
"msgtype": "m.text"
},
"event_id": "$143273582443PhrSn:example.org",
"origin_server_ts": 1432735824653,
"sender": "@example:example.org",
"type": "m.room.message",
"unsigned": {
"age": 1234,
"membership": "join"
}
} }
], ],
"limited": true, "limited": true,

9
data/api/client-server/third_party_membership.yaml
View file

@ -57,9 +57,6 @@ paths:
- A signature of the token, signed with the identity server's private key - A signature of the token, signed with the identity server's private key
- The matrix user ID who invited them to the room - The matrix user ID who invited them to the room
If a token is requested from the identity server, the homeserver will
append a `m.room.third_party_invite` event to the room.
operationId: inviteBy3PID operationId: inviteBy3PID
security: security:
- accessTokenQuery: [] - accessTokenQuery: []
@ -72,6 +69,8 @@ paths:
example: "!d41d8cd:matrix.org" example: "!d41d8cd:matrix.org"
schema: schema:
type: string type: string
format: mx-room-id
pattern: "^!"
requestBody: requestBody:
content: content:
application/json: application/json:
@ -90,7 +89,9 @@ paths:
value: {} value: {}
"403": "403":
description: |- description: |-
You do not have permission to invite the user to the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are: You do not have permission to invite the user to the room. A
meaningful `errcode` and description error text will be returned.
Example reasons for rejections are:
- The invitee has been banned from the room. - The invitee has been banned from the room.
- The invitee is already a member of the room. - The invitee is already a member of the room.

15
data/api/identity/v2_pubkey.yaml
View file

@ -43,7 +43,8 @@ paths:
properties: properties:
public_key: public_key:
type: string type: string
description: Unpadded Base64 encoded public key. description: |-
[Unpadded Base64](/appendices/#unpadded-base64)-encoded public key.
required: required:
- public_key - public_key
examples: examples:
@ -74,7 +75,8 @@ paths:
- in: query - in: query
name: public_key name: public_key
required: true required: true
description: The unpadded base64-encoded public key to check. description: |-
The [unpadded Base64](/appendices/#unpadded-base64)-encoded public key to check.
example: VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c example: VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c
schema: schema:
type: string type: string
@ -105,7 +107,14 @@ paths:
- in: query - in: query
name: public_key name: public_key
required: true required: true
description: The unpadded base64-encoded public key to check. description: |-
The [unpadded Base64](/appendices/#unpadded-base64)-encoded public
key to check.
This MUST be the exact same encoded string returned in the response
of the [`/store-invite`](/identity-service-api/#post_matrixidentityv2store-invite)
endpoint, or found in the corresponding [`m.room.third_party_invite`](/client-server-api/#mroomthird_party_invite)
event, so it may use the standard or URL-safe alphabets.
example: VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c example: VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c
schema: schema:
type: string type: string

14
data/api/identity/v2_store_invite.yaml
View file

@ -42,7 +42,7 @@ paths:
(if present) from the request here. (if present) from the request here.
Also, the generated ephemeral public key will be listed as valid on Also, the generated ephemeral public key will be listed as valid on
requests to `/_matrix/identity/v2/pubkey/ephemeral/isvalid`. requests to [`/_matrix/identity/v2/pubkey/ephemeral/isvalid`](/identity-service-api/#get_matrixidentityv2pubkeyephemeralisvalid).
Currently, invites may only be issued for 3pids of the `email` medium. Currently, invites may only be issued for 3pids of the `email` medium.
@ -70,10 +70,14 @@ paths:
room_id: room_id:
type: string type: string
description: The Matrix room ID to which the user is invited description: The Matrix room ID to which the user is invited
format: mx-room-id
pattern: "^!"
example: "!something:example.org" example: "!something:example.org"
sender: sender:
type: string type: string
description: The Matrix user ID of the inviting user description: The Matrix user ID of the inviting user
format: mx-user-id
pattern: "^@"
example: "@bob:example.com" example: "@bob:example.com"
room_alias: room_alias:
type: string type: string
@ -81,12 +85,16 @@ paths:
The Matrix room alias for the room to which the user is The Matrix room alias for the room to which the user is
invited. This should be retrieved from the `m.room.canonical_alias` invited. This should be retrieved from the `m.room.canonical_alias`
state event. state event.
format: mx-room-alias
pattern: "^#"
example: "#somewhere:example.org" example: "#somewhere:example.org"
room_avatar_url: room_avatar_url:
type: string type: string
description: |- description: |-
The Content URI for the room to which the user is invited. This should The Content URI for the room to which the user is invited. This should
be retrieved from the `m.room.avatar` state event. be retrieved from the `m.room.avatar` state event.
format: mx-mxc-uri
pattern: "^mxc:\\/\\/"
example: mxc://example.org/s0meM3dia example: mxc://example.org/s0meM3dia
room_join_rules: room_join_rules:
type: string type: string
@ -108,6 +116,8 @@ paths:
type: string type: string
description: The Content URI for the avatar of the user ID initiating the description: The Content URI for the avatar of the user ID initiating the
invite. invite.
format: mx-mxc-uri
pattern: "^mxc:\\/\\/"
example: mxc://example.org/an0th3rM3dia example: mxc://example.org/an0th3rM3dia
room_type: room_type:
type: string type: string
@ -146,7 +156,7 @@ paths:
public_key: public_key:
type: string type: string
description: | description: |
The public key, encoded using [unpadded Base64](/appendices/#unpadded-base64). The public key, encoded using standard or URL-safe [unpadded Base64](/appendices/#unpadded-base64).
key_validity_url: key_validity_url:
type: string type: string
description: | description: |

7
data/api/server-server/definitions/components/pdu_base.yaml
View file

@ -41,13 +41,6 @@ properties:
type: object type: object
description: The content of the event. description: The content of the event.
example: {"key": "value"} example: {"key": "value"}
depth:
type: integer
description: |-
The maximum depth of the `prev_events`, plus one. Must be less than the
maximum value for an integer (2^63 - 1). If the room's depth is already at
the limit, the depth must be set to the limit.
example: 12
hashes: hashes:
$ref: "event_hash.yaml" $ref: "event_hash.yaml"
signatures: signatures:

7
data/api/server-server/definitions/pdu_v1.yaml
View file

@ -28,6 +28,13 @@ allOf:
type: string type: string
description: For redaction events, the ID of the event being redacted. description: For redaction events, the ID of the event being redacted.
example: "$def456:matrix.org" example: "$def456:matrix.org"
depth:
type: integer
description: |-
The maximum depth of the `prev_events`, plus one. Must be less than the
maximum value for an integer (2^63 - 1). If the room's depth is already at
the limit, the depth must be set to the limit.
example: 12
auth_events: auth_events:
type: array type: array
description: |- description: |-

14
data/api/server-server/definitions/pdu_v11.yaml
View file

@ -17,6 +17,16 @@ description: A persistent data unit (event) for room version 11 and beyond.
example: example:
$ref: "../examples/pdu_v11.json" $ref: "../examples/pdu_v11.json"
allOf: allOf:
# v11 is the v4 event, but without redacts. # v11 is the v6 event, but without redacts.
- $ref: "components/pdu_base.yaml" - $ref: "components/pdu_base.yaml"
- $ref: "components/auth_events_prev_events_v4.yaml" - $ref: "components/auth_events_prev_events_v4.yaml"
- type: object
properties:
# v6 enforces Canonical JSON and therefore needs a depth limit change
depth:
type: integer
description: |-
The maximum depth of the `prev_events`, plus one. Must be less than the
maximum value for an integer (2^53 - 1). If the room's depth is already at
the limit, the depth must be set to the limit.
example: 12

7
data/api/server-server/definitions/pdu_v3.yaml
View file

@ -24,6 +24,13 @@ allOf:
type: string type: string
description: For redaction events, the ID of the event being redacted. description: For redaction events, the ID of the event being redacted.
example: "$def/456+oldevent" example: "$def/456+oldevent"
depth:
type: integer
description: |-
The maximum depth of the `prev_events`, plus one. Must be less than the
maximum value for an integer (2^63 - 1). If the room's depth is already at
the limit, the depth must be set to the limit.
example: 12
auth_events: auth_events:
type: array type: array
items: items:

7
data/api/server-server/definitions/pdu_v4.yaml
View file

@ -26,3 +26,10 @@ allOf:
type: string type: string
description: For redaction events, the ID of the event being redacted. description: For redaction events, the ID of the event being redacted.
example: "$def_456-oldevent" example: "$def_456-oldevent"
depth:
type: integer
description: |-
The maximum depth of the `prev_events`, plus one. Must be less than the
maximum value for an integer (2^63 - 1). If the room's depth is already at
the limit, the depth must be set to the limit.
example: 12

36
data/api/server-server/definitions/pdu_v6.yaml Normal file
View file

@ -0,0 +1,36 @@
# Copyright 2025 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: Persistent Data Unit
description: |-
A persistent data unit (event) for room versions 4, 5, 6, 7, 8, 9 and 10.
example:
$ref: "../examples/pdu_v4.json"
allOf:
- $ref: "components/pdu_base.yaml"
- $ref: "components/auth_events_prev_events_v4.yaml"
- type: object
properties:
redacts:
type: string
description: For redaction events, the ID of the event being redacted.
example: "$def_456-oldevent"
# v6 enforces Canonical JSON and therefore needs a depth limit change
depth:
type: integer
description: |-
The maximum depth of the `prev_events`, plus one. Must be less than the
maximum value for an integer (2^53 - 1). If the room's depth is already at
the limit, the depth must be set to the limit.
example: 12

100
data/api/server-server/third_party_invite.yaml
View file

@ -35,6 +35,8 @@ paths:
example: "!abc123:matrix.org" example: "!abc123:matrix.org"
schema: schema:
type: string type: string
format: mx-room-id
pattern: "^!"
requestBody: requestBody:
content: content:
application/json: application/json:
@ -50,16 +52,22 @@ paths:
description: |- description: |-
The room ID the event is for. Must match the ID given in The room ID the event is for. Must match the ID given in
the path. the path.
format: mx-room-id
pattern: "^!"
example: "!abc123:matrix.org" example: "!abc123:matrix.org"
sender: sender:
type: string type: string
description: |- description: |-
The user ID of the user who sent the original `m.room.third_party_invite` The user ID of the user who sent the original `m.room.third_party_invite`
event. event.
format: mx-user-id
pattern: "^@"
example: "@joe:matrix.org" example: "@joe:matrix.org"
state_key: state_key:
type: string type: string
description: The user ID of the invited user description: The user ID of the invited user
format: mx-user-id
pattern: "^@"
example: "@someone:example.org" example: "@someone:example.org"
content: content:
type: object type: object
@ -82,45 +90,7 @@ paths:
third-party identifier. third-party identifier.
example: alice example: alice
signed: signed:
type: object $ref: ../../event-schemas/schema/components/signed_third_party_invite.yaml
description: |-
A block of content which has been signed, which servers can use to
verify the event.
title: Invite Signatures
properties:
signatures:
type: object
title: Signatures
additionalProperties:
type: object
additionalProperties:
type: string
description: |-
The server signatures for this event.
The signature is calculated using the process
described at [Signing JSON](/appendices/#signing-json).
example:
magic.forest:
ed25519:3: fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg
mxid:
type: string
description: The invited matrix user ID
example: "@alice:localhost"
token:
type: string
description: The token used to verify the event
example: abc123
required:
- signatures
- mxid
- token
example:
mxid: "@alice:localhost"
token: abc123
signatures:
magic.forest:
ed25519:3: fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg
required: required:
- display_name - display_name
- signed - signed
@ -215,6 +185,8 @@ paths:
mxid: mxid:
type: string type: string
description: The user that is now bound to the third-party identifier. description: The user that is now bound to the third-party identifier.
format: mx-user-id
pattern: "^@"
example: "@alice:matrix.org" example: "@alice:matrix.org"
invites: invites:
type: array type: array
@ -237,59 +209,23 @@ paths:
mxid: mxid:
type: string type: string
description: The now-bound user ID that received the invite. description: The now-bound user ID that received the invite.
format: mx-user-id
pattern: "^@"
example: "@alice:matrix.org" example: "@alice:matrix.org"
room_id: room_id:
type: string type: string
description: The room ID the invite is valid for. description: The room ID the invite is valid for.
format: mx-room-id
pattern: "^!"
example: "!somewhere:example.org" example: "!somewhere:example.org"
sender: sender:
type: string type: string
description: The user ID that sent the invite. description: The user ID that sent the invite.
format: mx-user-id
pattern: "^@"
example: "@bob:matrix.org" example: "@bob:matrix.org"
# TODO (TravisR): Make this reusable when doing IS spec changes
# also make sure it isn't lying about anything, like the key version
signed: signed:
type: object $ref: ../../event-schemas/schema/components/signed_third_party_invite.yaml
title: Identity Server Signatures
description: |-
Signature from the identity server using a long-term private
key.
properties:
mxid:
type: string
description: |-
The user ID that has been bound to the third-party
identifier.
example: "@alice:matrix.org"
token:
type: string
# TODO: What is this actually?
description: A token.
example: Hello World
signatures:
type: object
title: Identity Server Signature
description: |-
The signature from the identity server. The `string` key
is the identity server's domain name, such as vector.im
additionalProperties:
type: object
title: Identity Server Domain Signature
description: The signature for the identity server.
properties:
ed25519:0:
type: string
description: The signature.
example: SomeSignatureGoesHere
required:
- ed25519:0
example:
vector.im:
ed25519:0: SomeSignatureGoesHere
required:
- mxid
- token
- signatures
required: required:
- medium - medium
- address - address

1
data/event-schemas/examples/m.room.member.yaml
View file

@ -1,6 +1,7 @@
{ {
"$ref": "core/state_event.json", "$ref": "core/state_event.json",
"state_key": "@alice:example.org", "state_key": "@alice:example.org",
"sender": "@alice:example.org",
"type": "m.room.member", "type": "m.room.member",
"content": { "content": {
"membership": "join", "membership": "join",

45
data/event-schemas/schema/components/signed_third_party_invite.yaml Normal file
View file

@ -0,0 +1,45 @@
title: SignedThirdPartyInvite
description: |-
A block of content which has been signed by the identity server, which
homeservers can use to verify the event. Clients should ignore this.
type: object
properties:
mxid:
description: |-
The user ID that has been bound to the third-party identifier.
type: string
format: mx-user-id
pattern: "^@"
example: "@alice:example.org"
signatures:
title: IdentityServerSignatures
description: |-
The identity server signatures for this block. This is a map of identity
server name to signing key identifier to base64-encoded signature.
The signatures are calculated using the process described at
[Signing JSON](/appendices/#signing-json).
type: object
additionalProperties:
type: object
additionalProperties:
type: string
example: {
"magic.forest": {
"ed25519:3": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg"
}
}
token:
description: |-
The token generated by the identity server at the
[`/store_invite`](/identity-service-api/#post_matrixidentityv2store-invite)
endpoint.
It matches the `state_key` of the corresponding [`m.room.third_party_invite`](/client-server-api/#mroomthird_party_invite)
event.
type: string
example: "abc123"
required:
- mxid
- signatures
- token

91
data/event-schemas/schema/m.room.member.yaml
View file

@ -2,17 +2,27 @@
allOf: allOf:
- $ref: core-event-schema/state_event.yaml - $ref: core-event-schema/state_event.yaml
description: |- description: |-
Adjusts the membership state for a user in a room. It is preferable to use the membership APIs (`/rooms/<room id>/invite` etc) when performing membership actions rather than adjusting the state directly as there are a restricted set of valid transformations. For example, user A cannot force user B to join a room, and trying to force this state change directly will fail. Adjusts the membership state for a user in a room. It is preferable to use the membership APIs
(`/rooms/<room id>/invite` etc) when performing membership actions rather than adjusting the
state directly as there are a restricted set of valid transformations. For example, user A cannot
force user B to join a room, and trying to force this state change directly will fail.
The following membership states are specified: The following membership states are specified:
- `invite` - The user has been invited to join a room, but has not yet joined it. They may not participate in the room until they join. - `invite` - The user has been invited to join a room, but has not yet joined it. They may not
- `join` - The user has joined the room (possibly after accepting an invite), and may participate in it. participate in the room until they join.
- `leave` - The user was once joined to the room, but has since left (possibly by choice, or possibly by being kicked). - `join` - The user has joined the room (possibly after accepting an invite), and may participate
- `ban` - The user has been banned from the room, and is no longer allowed to join it until they are un-banned from the room (by having their membership state set to a value other than `ban`). in it.
- `knock` - The user has knocked on the room, requesting permission to participate. They may not participate in the room until they join. - `leave` - The user was once joined to the room, but has since left (possibly by choice, or
possibly by being kicked).
- `ban` - The user has been banned from the room, and is no longer allowed to join it until they
are un-banned from the room (by having their membership state set to a value other than `ban`).
- `knock` - The user has knocked on the room, requesting permission to participate. They may not
participate in the room until they join.
The `third_party_invite` property will be set if this invite is an `invite` event and is the successor of an `m.room.third_party_invite` event, and absent otherwise. The `third_party_invite` property will be set if this invite is an `invite` event and is the
successor of an [`m.room.third_party_invite`](/client-server-api/#mroomthird_party_invite) event,
and absent otherwise.
This event may also include an `invite_room_state` key inside the event's `unsigned` data. This event may also include an `invite_room_state` key inside the event's `unsigned` data.
If present, this contains an array of [stripped state events](/client-server-api/#stripped-state) If present, this contains an array of [stripped state events](/client-server-api/#stripped-state)
@ -57,63 +67,54 @@ properties:
- ban - ban
type: string type: string
is_direct: is_direct:
description: Flag indicating if the room containing this event was created with the intention of being a direct chat. See [Direct Messaging](/client-server-api/#direct-messaging). description: |-
Flag indicating if the room containing this event was created with the intention of being
a direct chat. See [Direct Messaging](/client-server-api/#direct-messaging).
type: boolean type: boolean
join_authorised_via_users_server: join_authorised_via_users_server:
x-addedInMatrixVersion: "1.2" x-addedInMatrixVersion: "1.2"
type: string type: string
description: |- description: |-
Usually found on `join` events, this field is used to denote which homeserver (through representation of a user with sufficient power level) Usually found on `join` events, this field is used to denote which homeserver (through
authorised the user's join. More information about this field can be found in the [Restricted Rooms Specification](/client-server-api/#restricted-rooms). representation of a user with sufficient power level) authorised the user's join. More
information about this field can be found in the [Restricted Rooms Specification](/client-server-api/#restricted-rooms).
Client and server implementations should be aware of the [signing implications](/rooms/v8/#authorization-rules) of including this Client and server implementations should be aware of the [signing implications](/rooms/v8/#authorization-rules)
field in further events: in particular, the event must be signed by the server which of including this field in further events: in particular, the event must be signed by the
owns the user ID in the field. When copying the membership event's `content` server which owns the user ID in the field. When copying the membership event's `content`
(for profile updates and similar) it is therefore encouraged to exclude this (for profile updates and similar) it is therefore encouraged to exclude this field in the
field in the copy, as otherwise the event might fail event authorization. copy, as otherwise the event might fail event authorization.
reason: reason:
x-addedInMatrixVersion: "1.1" x-addedInMatrixVersion: "1.1"
type: string type: string
description: |- description: |-
Optional user-supplied text for why their membership has changed. For kicks and bans, this is typically the reason for the kick or ban. Optional user-supplied text for why their membership has changed. For kicks and bans,
For other membership changes, this is a way for the user to communicate their intent without having to send a message to the room, such this is typically the reason for the kick or ban. For other membership changes, this is a
as in a case where Bob rejects an invite from Alice about an upcoming concert, but can't make it that day. way for the user to communicate their intent without having to send a message to the
room, such as in a case where Bob rejects an invite from Alice about an upcoming concert,
but can't make it that day.
Clients are not recommended to show this reason to users when receiving an invite due to the potential for spam and abuse. Hiding the Clients are not recommended to show this reason to users when receiving an invite due to
reason behind a button or other component is recommended. the potential for spam and abuse. Hiding the reason behind a button or other component is
recommended.
third_party_invite: third_party_invite:
title: ThirdPartyInvite
description: |-
A third-party invite, if this `m.room.member` is the successor to an
[`m.room.third_party_invite`](/client-server-api/#mroomthird_party_invite)
event.
type: object
properties: properties:
display_name: display_name:
description: A name which can be displayed to represent the user instead of their third-party identifier description: |-
A name which can be displayed to represent the user instead of their
third-party identifier
type: string type: string
signed: signed:
description: 'A block of content which has been signed, which servers can use to verify the event. Clients should ignore this.' $ref: components/signed_third_party_invite.yaml
properties:
mxid:
description: The invited matrix user ID. Must be equal to the user_id property of the event.
type: string
signatures:
description: 'A single signature from the verifying server, in the format specified by the Signing Events section of the server-server API.'
title: Signatures
type: object
additionalProperties:
type: object
additionalProperties:
type: string
token:
description: The token property of the containing third_party_invite object.
type: string
required:
- mxid
- signatures
- token
title: signed
type: object
required: required:
- display_name - display_name
- signed - signed
title: Invite
type: object
required: required:
- membership - membership
title: EventContent title: EventContent

48
data/event-schemas/schema/m.room.third_party_invite.yaml
View file

@ -1,28 +1,56 @@
--- ---
allOf: allOf:
- $ref: core-event-schema/state_event.yaml - $ref: core-event-schema/state_event.yaml
description: "Acts as an `m.room.member` invite event, where there isn't a target user_id to invite. This event contains a token and a public key whose private key must be used to sign the token. Any user who can present that signature may use this invitation to join the target room." description: |-
Acts as an `m.room.member` invite event, where there isn't a target user_id to
invite. This event contains a token and a public key whose private key must be
used to sign the token. Any user who can present that signature may use this
invitation to join the target room.
properties: properties:
content: content:
properties: properties:
display_name: display_name:
description: "A user-readable string which represents the user who has been invited. This should not contain the user's third-party ID, as otherwise when the invite is accepted it would leak the association between the matrix ID and the third-party ID." description: |-
A user-readable string which represents the user who has been invited.
This should not contain the user's third-party ID, as otherwise when
the invite is accepted it would leak the association between the
matrix ID and the third-party ID.
type: string type: string
key_validity_url: key_validity_url:
description: "A URL which can be fetched, with querystring public_key=public_key, to validate whether the key has been revoked. The URL must return a JSON object containing a boolean property named 'valid'." description: |-
A URL which can be fetched, with querystring public_key=public_key, to
validate whether the key has been revoked. The URL must return a JSON
object containing a boolean property named 'valid'.
type: string type: string
format: uri
public_key: public_key:
description: A base64-encoded ed25519 key with which token must be signed (though a signature from any entry in public_keys is also sufficient). This exists for backwards compatibility. description: |-
An Ed25519 key with which the token must be signed (though a signature
from any entry in `public_keys` is also sufficient).
The key is encoded using [Unpadded Base64](/appendices/#unpadded-base64),
using the standard or URL-safe alphabets.
This exists for backwards compatibility.
type: string type: string
public_keys: public_keys:
description: Keys with which the token may be signed. description: Keys with which the token may be signed.
items: items:
properties: properties:
key_validity_url: key_validity_url:
description: "An optional URL which can be fetched, with querystring public_key=public_key, to validate whether the key has been revoked. The URL must return a JSON object containing a boolean property named 'valid'. If this URL is absent, the key must be considered valid indefinitely." description: |-
An optional URL which can be fetched, with querystring
`public_key=<public_key>`, to validate whether the key has been
revoked. The URL must return a JSON object containing a boolean
property named `valid`. If this URL is absent, the key must be
considered valid indefinitely.
type: string type: string
public_key: public_key:
description: A base-64 encoded ed25519 key with which token may be signed. description: |-
An Ed25519 key with which the token may be signed.
The key is encoded using [Unpadded Base64](/appendices/#unpadded-base64),
using the standard or URL-safe alphabets.
type: string type: string
required: required:
- public_key - public_key
@ -35,11 +63,15 @@ properties:
- public_key - public_key
type: object type: object
state_key: state_key:
description: 'The token, of which a signature must be produced in order to join the room.' description: |-
The token, of which a signature must be produced in order to join the
room.
type: string type: string
type: type:
enum: enum:
- m.room.third_party_invite - m.room.third_party_invite
type: string type: string
title: 'An invitation to a room issued to a third-party identifier, rather than a matrix user ID.' title: |-
An invitation to a room issued to a third-party identifier, rather than a
matrix user ID.
type: object type: object

25
data/event-schemas/schema/m.room.topic.yaml
View file

@ -2,18 +2,21 @@
allOf: allOf:
- $ref: core-event-schema/state_event.yaml - $ref: core-event-schema/state_event.yaml
description: |- description: |-
A topic is a short message detailing what is currently being discussed A topic is a short message detailing what is currently being discussed
in the room. It can also be used as a way to display extra information in the room. It can also be used as a way to display extra information
about the room, which may not be suitable for the room name. The room about the room, which may not be suitable for the room name. The room
topic can be set when creating a room using topic can also be set when creating a room using
[`/createRoom`](client-server-api/#post_matrixclientv3createroom), either [`/createRoom`](client-server-api/#post_matrixclientv3createroom), either
with the `topic` key or by specifying a full event in `initial_state`. with the `topic` key or by specifying a full event in `initial_state`.
In order to prevent formatting abuse in room topics, clients SHOULD If the `topic` property is absent, null, or empty then the topic is unset. In other words,
limit the length of topics during both entry and display, for instance, an empty `topic` property effectively resets the room to having no topic.
by capping the number of displayed lines. Additionally, clients SHOULD
ignore things like headings and enumerations (or format them as regular In order to prevent formatting abuse in room topics, clients SHOULD
text). limit the length of topics during both entry and display, for instance,
by capping the number of displayed lines. Additionally, clients SHOULD
ignore things like headings and enumerations (or format them as regular
text).
properties: properties:
content: content:
properties: properties:

5
data/string-formats.yaml
View file

@ -51,6 +51,11 @@ mx-room-id:
url: appendices#room-ids url: appendices#room-ids
# regex: "^!" # regex: "^!"
mx-room-alias:
title: Room Alias
url: appendices#room-aliases
# regex: "^#"
mx-server-name: mx-server-name:
title: Server Name title: Server Name
url: appendices#server-name url: appendices#server-name

1
static/.well-known/funding-manifest-urls Normal file
View file

@ -0,0 +1 @@
https://matrix.org/funding.json