Changelog
This is version v1.3 of the Matrix specification.
Git commit | https://github.com/matrix-org/matrix-spec/tree/v1.3 |
---|---|
Release date | June 16, 2022 |
Changes since last release
Client-Server API
- Deprecations
- Backwards Compatible Changes
- 1002: Make
from
optional onGET /_matrix/client/v3/messages
to allow requesting events from the start or end of the room history, as per MSC3567. - 1056: Add refresh tokens, per MSC2918.
- 1062: Relax the restrictions on Rich Replies, as per MSC3676.
- 1062: Describe a structured system for event relationships, as per MSC2674.
- 1062: Describe how relationships between events can be “aggregated”, as per MSC2675 and MSC3666.
- 1099: Add support for a new
knock_restricted
join rule in supported room versions, as per MSC3787. - 1113: Add refresh tokens, per MSC2918.
- 1002: Make
- Spec Clarifications
- 1003: Adjust the OpenAPI specification so that the type
Flow information
is explicitly defined when the client-server API is rendered. - 1021: Correct the default value for
invite
where it is not specified in anm.room.power_levels
event. - 1032: Update various links which pointed to the old
matrix-doc
github repository. - 1035: Removed
m.room.message.feedback
per MSC3582. - 1051: Fix various typos throughout the specification.
- 1054: Fix various typos throughout the specification.
- 1059: Fix various typos throughout the specification.
- 1081: Fix various typos throughout the specification.
- 1097: Fix various typos throughout the specification.
- 1100: Clarify that state keys starting with
@
are in fact reserved. Regressed from #3658. - 1110: Fix various typos throughout the specification.
- 1115: Fix various typos throughout the specification.
- 1126: Fix various typos throughout the specification.
- 1127: Fix various typos throughout the specification.
- 1128: Fix various typos throughout the specification.
- 1129: Fix various typos throughout the specification.
- 3669: Remove unenforced size limit on the
name
field ofm.room.name
events. - 3679: Remove erroneous
room_id
field from examples ofm.read
,m.typing
in/sync
andm.fully_read
in room account data. - 3681: Fix various typos throughout the specification.
- 3690: Clarify the behaviour of
event_match
in push rule conditions. - 3708: Fix various typos throughout the specification.
- 3711: Fix incorrectly referenced
m.login.appservice
login identifier, instead usingm.login.application_service
. - 3730: Fix membership state transitions to denote that
invite->knock
andexternal->leave
are valid transitions. - 987: Clarify that the url field in
m.room.avatar
events is not required. - 989: Clarify that the
type
in user-interactive authentication can be omitted.
- 1003: Adjust the OpenAPI specification so that the type
Server-Server API
- Backwards Compatible Changes
- Spec Clarifications
- 1032: Update various links which pointed to the old
matrix-doc
github repository. - 1038: Clarify the format for the Authorization header.
- 1045: Clarify what a “valid event” means when performing checks on a received PDU.
- 1055: Clarify that
valid_until_ts
is in milliseconds, like other timestamps used in Matrix. - 1067: Clarify the format for the Authorization header.
- 1070: Clarify that checks on PDUs should refer to the state before an event.
- 1099: Clarify the historical handling of non-integer power levels.
- 1110: Fix various typos throughout the specification.
- 3703: Correct misleading text for
/send_join
response. - 3727: Clarify that the
content
forX-Matrix
signature validation is the parsed JSON body. - 998: Remove largely unused
origin
field from PDUs.
- 1032: Update various links which pointed to the old
Application Service API
Identity Service API
Push Gateway API
Room Versions
- Backwards Compatible Changes
- Spec Clarifications
- 1037: Improve readability and understanding of the state resolution algorithms.
- 1042: Improve readability and understanding of the state resolution algorithms.
- 1043: Improve readability and understanding of the state resolution algorithms.
- 1050: Improve readability of the authorization rules.
- 1093: For room versions 8, 9, and 10: clarify which homeserver is required to sign the join event.
- 1099: Clarify that room versions 1 through 9 accept stringy power levels, as noted by MSC3667.
- 1103: For all room versions: Add
m.federate
to the authorization rules, as originally intended. - 1107: For room versions 2 through 10: More explicitly define the mainline of a power event and the mainline ordering of other events.
- 1120: Improve readability and understanding of the state resolution algorithms.
- 1158: For room versions 2–10: correct a mistaken clarification to the state resolution algorithm.
- 3737: For room versions 7, 8, 9, and 10: fix join membership authorization rules when
join_rule
isknock
.
Appendices
v1.2
Git commit | https://github.com/matrix-org/matrix-doc/tree/v1.2 |
---|---|
Release date | February 02, 2022 |
Client-Server API
Breaking Changes
- The
prev_content
field is now returned inside theunsigned
property of events, rather than at the top level, as per MSC3442. (#3524) - The
aliases
property from the chunks returned by/publicRooms
, as per MSC2432. (#3624)
New Endpoints
- Add the Space Hierarchy API (
GET /_matrix/client/v1/rooms/{roomId}/hierarchy
) as per MSC2946. (#3610) - Add
/_matrix/client/v1/register/m.login.registration_token/validity
as per MSC3231. (#3616)
Backwards Compatible Changes
- Extend
/_matrix/client/r0/login
to accept am.login.appservice
, as per MSC2778. (#3324) - Add support for
restricted
rooms as per MSC3083, MSC3289, and MSC3375. (#3387) - Add
is_guest
to/account/whoami
as per MSC3069. (#3605) - Expand guest access to sending any room event and state event as per MSC3419. (#3605)
- Add Spaces and room types as per MSC1772 and MSC2946. (#3610)
- Add new
m.set_displayname
,m.set_avatar_url
, andm.3pid_changes
capabilities as per MSC3283. (#3614) - Add support for fallback keys (optional keys used once one-time keys run out), as per MSC2732. (#3615)
- Add token-authenticated registration support as per MSC3231. (#3616)
Spec Clarifications
- Make
AesHmacSha2KeyDescription
consistent withKeyDescription
in markingname
as optional. (#3481) - Fix various typos throughout the specification. (#3482, #3495, #3509, #3535, #3591, #3601, #3611, #3671, #3680)
- Explicitly mention RFC5870 in the definition of
m.location
events (#3492) - Add
403 M_FORBIDDEN
error code to/profile/{userId}
as per MSC3550. (#3530) - Clarify the description of the
/sync
API, including a fix to an ASCII art diagram. (#3543) - Clarify that
base_url
in clientwell_known
may or may not include trailing slash. (#3562) - Clarify which signature to check when decrypting
m.olm.v1.curve25519-aes-sha2
messages. (#3573) - Clarify what “Stripped State” is and what purpose it serves, as per MSC3173. (#3606)
- Clarify how to interpret missing one-time key counts. (#3636)
- Correct the schema for the responses for various API endpoints. (#3650)
- Clarify that group mentions are no longer in the specification. (#3652)
- Distinguish between “federation” event format as exchanged by the Federation API, and the “client” event formats as used in the client-server and AS APIs. (#3658)
- Fix the rendering of the responses for various API endpoints. (#3674)
Server-Server API
New Endpoints
- Add the Space Hierarchy API (
GET /_matrix/federation/v1/hierarchy/{roomId}
) as per MSC2946. (#3610, #3660)
Backwards Compatible Changes
Spec Clarifications
- Fix various typos throughout the specification. (#3527, #3528)
- Clarify that
GET /_matrix/federation/v1/event_auth/{roomId}/{eventId}
does not return the auth chain for the full state of the room. (#3583) - Fix the rendering of the responses for various API endpoints. (#3674)
Application Service API
Spec Clarifications
- Distinguish between “federation” event format as exchanged by the Federation API, and the “client” event formats as used in the client-server and AS APIs. (#3658)
- Fix the rendering of the responses for various API endpoints. (#3674)
- Correct the documentation for the response value for
GET /_matrix/app/v1/thirdparty/protocol/{protocol}
. (#3675)
Identity Service API
Backwards Compatible Changes
Spec Clarifications
- Fix the rendering of the responses for various API endpoints. (#3674)
Push Gateway API
Spec Clarifications
- Fix the rendering of the responses for various API endpoints. (#3674)
Room Versions
Backwards Compatible Changes
Spec Clarifications
- Fully specify room versions to indicate what exactly is carried over from parent versions. (#3432, #3661)
- Clarifications to sections on event IDs and event formats. (#3501)
- Remove a number of fields which were incorrectly shown to form part of the
unsigned
data of a Federation PDU. (#3522) - Fix heading order of room version specifications to be consistent. (#3683)
- Add missing “Signing key validity period” section to room version 6. (#3683)
- Fix auth rules to allow membership of
knock
->leave
in v7, v8, and v9. (#3694)
Appendices
Backwards Compatible Changes
- Describe “Common Namespaced Identifier Grammar” as per MSC2758. (#3171)
- Describe the
matrix:
URI scheme as per MSC2312. (#3608)
v1.1
Git commit | https://github.com/matrix-org/matrix-doc/tree/v1.1 |
---|---|
Release date | November 09, 2021 |
Client-Server API
Breaking Changes
- Document
curve25519-hkdf-sha256
key agreement method for SAS verification, and deprecate old method as per MSC2630. (#2687) - Add
m.key.verification.ready
andm.key.verification.done
to key verification framework as per MSC2366. (#3139)
Deprecations
- Deprecate starting verifications that don’t start with
m.key.verification.request
as per MSC3122. (#3199)
New Endpoints
- Add key backup (
/room_keys/*
) endpoints as per MSC1219. (#2387, #2639) - Add
POST /keys/device_signing/upload
andPOST /keys/signatures/upload
as per MSC1756. (#2536) - Add
/knock
endpoint as per MSC2403. (#3154) - Add
/login/sso/redirect/{idpId}
as per MSC2858. (#3163)
Removed Endpoints
- Remove unimplemented
m.login.oauth2
andm.login.token
user-interactive authentication mechanisms as per MSC2610 and MSC2611. (#2609)
Backwards Compatible Changes
- Document how clients can advise recipients that it is withholding decryption keys as per MSC2399. (#2399)
- Add cross-signing properties to the response of
POST /keys/query
as per MSC1756. (#2536) - Document Secure Secret Storage and Sharing as per MSC1946 and MSC2472. (#2597)
- Add a
device_id
parameter to login fallback as per MSC2604. (#2709) - Added a common set of translations for SAS Emoji. (#2728)
- Added support for
reason
on all membership events and related endpoints as per MSC2367. (#2795) - Add a 404
M_NOT_FOUND
error to push rule endpoints as per MSC2663. (#2796) - Make
reason
andscore
parameters optional in the content reporting API as per MSC2414. (#2807) - Allow guests to get the list of members for a room as per MSC2689. (#2808)
- Add support for spoilers as per MSC2010 and MSC2557, and
color
attribute as per MSC2422. (#3098) - Add
<details>
and<summary>
to the suggested HTML subset as per MSC2184. (#3100) - Add key verification using in-room messages as per MSC2241. (#3139, #3150)
- Add information about using SSSS for cross-signing and key backup. (#3147)
- Add key verification method using QR codes as per MSC1544. (#3149)
- Document how clients can simplify usage of Secure Secret Storage as per MSC2874. (#3151)
- Add support for knocking, as per MSC2403. (#3154, #3254)
- Multiple SSO providers are possible through
m.login.sso
as per MSC2858. (#3163) - Add
device_id
to/account/whoami
response as per MSC2033. (#3166) - Downgrade identity server discovery failures to
FAIL_PROMPT
as per MSC2284. (#3169) - Re-version all endpoints to be
v3
as a starting point instead ofr0
as per MSC2844. (#3421)
Spec Clarifications
- Fix issues with
age
andunsigned
being shown in the wrong places. (#2591) - Fix definitions for room version capabilities. (#2592)
- Fix various typos throughout the specification. (#2594, #2599, #2809, #2878, #2885, #2888, #3116, #3339)
- Clarify link to OpenID Connect specification. (#2605)
- Clarify the behaviour of SSO login and UI-Auth. (#2608)
- Remove spurious
room_id
from/sync
examples. (#2629) - Reorganize information in Push Notifications module for clarity. (#2634)
- Improve consistency and clarity of event schema
title
s. (#2647) - Fix schema issues in
m.key.verification.accept
and secret storage. (#2653) - Reword “UI Authorization” to “User-Interactive Authentication” to be more clear. (#2667)
- Fix schemas for push rule actions to represent their alternative object form. (#2669)
- Fix usage of
highlight
tweak for consistency. (#2670) - Clarify the behaviour of
state
for/sync
with lazy-loading. (#2754) - Clarify description of
m.room.redaction
event. (#2814) - Mark
messages
as a required JSON body field inPUT /_matrix/client/r0/sendToDevice/{eventType}/{txnId}
calls. (#2928) - Correct examples of
client_secret
request body parameters so that they do not include invalid characters. (#2985) - Fix example MXC URI for
m.presence
. (#3091) - Clarify that event bodies are untrusted, as per MSC2801. (#3099)
- Fix the maximum event size restriction (65535 bytes -> 65536). (#3127)
- Update
Access-Control-Allow-Headers
recommendation to fit CORS specification. (#3225) - Explicitly state that
replacement_room
is a room ID inm.room.tombstone
events. (#3233) - Clarify that all request bodies are required. (#3238, #3332)
- Add missing titles to some scheams. (#3330)
- Add User-Interactive Authentication fields to cross-signing APIs as per MSC1756. (#3331)
- Mention that a canonical alias event should be added when a room is created with an alias. (#3337)
- Add an ‘API conventions’ section to the Appendices. (#3350)
- Clarify the documentation around the pagination tokens used by
/sync
,/rooms/{room_id}/messages
,/initialSync
,/rooms/{room_id}/initialSync
, and/notifications
. (#3353) - Remove the inaccurate ‘Pagination’ section. (#3366)
- Clarify how
redacted_because
is meant to work. (#3411) - Remove extraneous
mimetype
fromEncryptedFile
examples, as per MSC2582. (#3412) - Describe how MSC2844 affects the
/versions
endpoint. (#3420) - Fix documentation errors around
threepid_creds
. (#3471)
Server-Server API
New Endpoints
Backwards Compatible Changes
- Add cross-signing information to
GET /user/keys
andGET /user/devices/{userId}
,m.device_list_update
EDU, and a newm.signing_key_update
EDU as per MSC1756. (#2536) - Add support for knocking, as per MSC2403. (#3154)
Spec Clarifications
- Specify that
GET /_matrix/federation/v1/make_join/{roomId}/{userId}
can return a 404 if the room is unknown. (#2688) - Fix various typos throughout the specification. (#2888, #3116, #3128, #3207)
- Correct the
/_matrix/federation/v1/user/devices/{userId}
response which actually returns"self_signing_key"
instead of"self_signing_keys"
. (#3312) - Explain the reasons why
<hostname>
TLS certificate is needed rather than<delegated_hostname>
for SRV delegation. (#3322) - Tweak the example PDU diagram to better demonstrate situations with multiple
prev_events
. (#3340)
Application Service API
Spec Clarifications
- Fix various typos throughout the specification. (#2888)
Identity Service API
New Endpoints
Removed Endpoints
Spec Clarifications
- Fix various typos throughout the specification. (#2888)
- Clarify that some identifiers must be case folded prior to processing, as per MSC2265. (#3167, #3176)
- Describe how MSC2844 affects the
/versions
endpoint. (#3459)
Push Gateway API
Spec Clarifications
- Clarify where to get information about the various parameter values for the notify endpoint. (#2763)
Historical versions
Before version 1.1, versioning was applied at the level of individual API specifications. This section includes links to these versions of the APIs.
-
Client-Server API
-
Server-Server API
-
Application Service API
-
Identity Service API
-
Push Gateway API