Spec

14 posts tagged with "Spec" (See all Category)

Atom Feed

Matrix v1.12 release

07.10.2024 19:53 — Releases Travis Ralston

Hey all,

Welcome to the Matrix 1.12! It’s been just over 3 months since Matrix 1.11 introduced authenticated media, and today we’re bringing more Trust & Safety features to the ecosystem, alongside the normal clarifications and general improvements to the protocol. This release is also technically a few days late on the quarter, but it’s for good reason! Folks from across the ecosystem got together in Berlin for the Matrix Conference, and after things wrapped up we were busy following up on ideas started on site. We can’t wait to see all of these ideas materialize as MSCs, but in the meantime, back to the honorary Q3 release of the spec:

Matrix 1.12 marks the recommended date for all servers to enable their media freeze, similar to matrix.org’s back in early September 2024. Servers which haven’t yet enabled their media freeze are strongly encouraged to do so, if it makes sense for their users. Matrix 1.12 also brings some improvements and clarifications to authenticated media, and a total of 9 MSCs covering a wide range of features.

Read on for a few highlights, and the full changelog at the end of this post.

Continue reading…

Matrix v1.11 release

20.06.2024 16:52 — Releases Travis Ralston

Hey all,

We’ve just released the milestone Matrix 1.11 update for the protocol. It’s been almost exactly 3 months since the last release, Matrix 1.10, keeping us on track for our once-a-quarter release schedule.

There are 9 MSCs released in Matrix 1.11 today, but there’s one specific MSC we’d like to draw your attention to: MSC3916 - Authenticated Media. Until today, Matrix had a design flaw which allows a user to access media unauthenticated if they knew the URL. This has been used to share files in social media posts, link images outside of chats, and generally imply that a homeserver is a CDN for the internet. Some of these use cases are legitimate, though many are not. This is fixed with MSC3916.

This post covers MSC3916 and its implementation guidelines in more detail, but the full changelog for Matrix 1.11 is available at the end, as always.

Continue reading…

Matrix v1.10 release

22.03.2024 16:52 — Releases Travis Ralston

Hey all,

Matrix 1.10 is here! We aim to release the specification once in each calendar quarter, and with Q1 wrapping up in a few days we’re due for this quarter’s release. It has been 5 months since the last release (Matrix 1.9) brought in some protocol maintenance for us though, and the implementation teams have been hard at work building the Matrix 2.0 stack concurrent to the Matrix 1.10 work released today.

A total of 9 MSCs are released in Matrix 1.10, covering a wide range of maintenance, Matrix 2.0 preparation, and features for clients to use. This post focuses a bit on the Matrix 2.0 front and what’s expected in Matrix 1.11’s release cycle, but read on to the changelog at the bottom for full details on the changes which make up Matrix 1.10.

MSC3077: Multi-stream VoIP

MSC3077 and its related proposal MSC3291 (muting in VoIP calls) lay some foundational groundwork for proper group VoIP to land in Matrix - an objective of Matrix 2.0. Currently this is taking shape at MSC3898 and MSC3401, though Element’s VoIP team is considering a possible third alternative which runs MSC3401 over something like LiveKit’s SFU - stay tuned for updates there. In the meantime, users in native 1:1 calls can enjoy proper screen sharing and mute capabilities ahead of the 1:N call support later this year.

As always, early review is appreciated though please note that MSC3898 and MSC3401 are particularly in flux at the moment.

Up next in Matrix 1.11 and beyond

Over the next 2-3 months, we’ll be focusing on the following MSCs:

  • Trust & Safety improvements (at the protocol level).
    • MSC3823 - Account suspension
    • MSC3939 - Account locking
    • MSC3916 - Authentication for media (time permitting)
    • MSC4117 - Reversible redactions (pre-implementation review)
    • MSCs around a “reporting v2” flow in light of various legislation and compliance requirements. These MSCs are currently being written and should be up for pre-implementation review within the Matrix 1.11 cycle.
  • Early review of Matrix 2.0 features as they become ready.
    • Sliding sync (MSC3575) + applicable extensions.
    • Group VoIP - Exact MSCs to be determined, as they may change following implementation.
    • OIDC Authentication - Exact MSCs to be determined.
  • Pre-implementation review of Extensible Events core content blocks MSCs.
    • Many of these MSCs require updates before they are ready for formal review.
    • MSC3954 - Emotes
    • MSC3955 - Notices / automated events
    • MSC3927 - Audio
    • MSC3551 - Files
    • MSC3552 - Images and Stickers
    • MSC3553 - Videos

Additionally, we’ll be continuing to define the expectations of a Spec Core Team member, particularly as it relates to the upcoming Governing Board for the Foundation. This exercise has been extremely valuable to us so far, and will help identify areas the Foundation and SCT may need support from each other.

The full changelog

Read on for full details of what’s in Matrix 1.10:

Client-Server API

Backwards Compatible Changes

  • Allow /versions to optionally accept authentication, as per MSC4026. (#1728)
  • Add local erasure requests, as per MSC4025. (#1730)
  • Use the body field as optional media caption, as per MSC2530. (#1731)
  • Add server support discovery endpoint, as per MSC1929. (#1733)
  • Add support for multi-stream VoIP, as per MSC3077. (#1735)
  • Specify that the Retry-After header may be used to rate-limit a client, as per MSC4041. (#1737)
  • Add support for recursion on the GET /relations endpoints, as per MSC3981. (#1746)

Spec Clarifications

  • The strike element is deprecated in the HTML spec. Clients should prefer s instead. (#1629)
  • Clarify that read receipts should be batched by thread as well as by room. (#1685)
  • Clarify that threads can be created based on replies. (#1687)
  • Clarify in the reply fallbacks example that the prefix sequence should be repeated for each line. (#1690)
  • Clarify the format of account data objects for secret storage. (#1695, #1734)
  • Clarify that the key backup MAC is implemented incorrectly and does not pass the ciphertext through HMAC-SHA-256. (#1712)
  • Clarify one-time key and fallback key types in examples. (#1715)
  • Clarify that the HKDF calculation for SAS uses base64-encoded keys rather than the raw key bytes. (#1719)
  • Clarify how to perform the ECDH exchange in step 12 of the SAS process. (#1720)
  • Document the deprecation policy of HTML tags, as per MSC4077. (#1732)
  • The font element is deprecated in the HTML spec. Clients should prefer span with the data-mx-bg-color and data-mx-color attributes instead. (#1739)
  • Disambiguate uses of PublicRoomsChunk in the GET /hierarchy endpoint. (#1740)
  • Clarify that sdpMid and sdpMLineIndex are not required in m.call.candidates. (#1742)
  • Fix various typos throughout the specification. (#1748)
  • Clearly indicate that each Content-Type may have distinct behaviour on non-JSON requests/responses. (#1756)
  • Clarify that the m.push_rules account data type cannot be set using the /account_data API, as per MSC4010. (#1763)

Server-Server API

Spec Clarifications

  • Clarify Server-Server API request signing example by using the POST HTTP method, as GET requests don't have request bodies. (#1721)
  • Disambiguate uses of PublicRoomsChunk in the GET /hierarchy endpoint. (#1740)
  • Clarify that the children_state, room_type and allowed_room_ids properties in the items of the children array of the response of the GET /hierarchy endpoint are not required. (#1741)

Application Service API

Spec Clarifications

  • Clarify that the /login and /register endpoints should fail when using the m.login.application_service login type without a valid as_token. (#1744)

Identity Service API

No significant changes.

Push Gateway API

No significant changes.

Room Versions

Spec Clarifications

  • For room versions 7 through 11: Clarify that invite->knock is not a legal transition. (#1717)

Appendices

No significant changes.

Internal Changes/Tooling

Spec Clarifications

  • Update the spec release process. (#1680)
  • Minor clarifications to the contributing guide. (#1697)
  • Update Docsy to v0.8.0. (#1699, #1762)
  • Fix npm release script for @matrix-org/spec. (#1713)
  • Add some clarifications around implementation requirements for MSCs. (#1718)
  • Update HTML templates to include links to object schema definitions. (#1724)
  • Factor out all the common parameters of the various /relations apis. (#1745)
  • Add support for $ref URIs containing fragments in OpenAPI definitions and JSON schemas. (#1751, #1754)

Matrix v1.9 release

29.11.2023 17:44 — Releases Travis Ralston

Hey all,

We’ve just pushed out Matrix 1.9! Our last release was Matrix 1.8 and brought us a whole new room version. Matrix 1.9 continues a theme of an annual maintenance release, bringing with it mostly clarifications and bug fixes.

Today’s release sees just 1 MSC formally merged to the specification, though this is expected for a maintenance release. For the last 2 months (and beyond), we have largely been focused on changes which haven’t settled enough to be MSCs yet, such as interactions with the More Instant Messaging Interoperability (MIMI) working group at the IETF.

This post covers a lot of what we’ve been up to for the last few months, and what we expect to get done for the Matrix 1.10 release cycle. As always, the full changelog for Matrix 1.9 is at the bottom of the post :)

Messaging interoperability

One of the major features of Matrix is its ability to connect multitudes of messaging providers with a common communications fabric - a feature that is extremely useful in light of the EU’s Digital Markets Act (DMA) which requires gatekeepers to interoperate with other messaging providers.

We’ve been working with the MIMI working group at the IETF to establish a federation protocol for DMA-style messaging alongside our own experiments like MSC3995: Linearized Matrix. The proposed protocol for MIMI is based upon the Linearized Matrix work, but is primarily designed for an MLS-centric environment.

Discussions and experiments will continue over the next several months, and you can read all about our progress so far in TWIM 2023-11-10.

Custom emoji/stickers

We mentioned in Matrix 1.8’s release that we’d be taking a look at MSC2545, MSC1951, MSC4027, and MSC3892 - a family of MSCs collectively called “custom emoji/stickers”. Our review started relatively late in the Matrix 1.9 release cycle (sorry), and we started thinking about interactions with MSC3916/MSC3911 where media is linked to a specific event.

We haven’t had a chance to really dig into the specific possible concerns on these two features overlapping, but do welcome feedback and suggestions for what might impact custom emoji/stickers over on our dedicated tracking issue. We’ll continue working through the problem space in the Matrix 1.10 release cycle, and hope to get both linked media and custom emoji/stickers up for FCP.

Upcoming in Matrix 1.10

With each release we aim to have a plan for what the next release will look like, giving us a direction or theme to follow. Noting that the next release cycle has a lot of holidays (and FOSDEM) in it, we’ve got an initial list of things to look at, grouped by theme:

  • Authenticated media
    • MSC3916 - Authentication for media
    • MSC3911 - Linking media to events
  • Custom emoji/stickers
  • MSC4074 - Server-side annotation aggregation
  • MSC4048 - Authenticated key backup
  • Extensible Events
  • Encrypted Appservices
    • MSC2409 - Sending EDUs to appservices
    • MSC3202 - Encrypted appservices
  • MSC2702 - Content-Disposition semantics for media
  • MSC3939 - Account locking

This list is not final and will be iterated upon over the next couple of weeks. If you’ve got an MSC to add or remove, let us know in the SCT Office on Matrix. For all of the MSCs above, we aim to get them to a FCP-accepted state at a minimum, and merged to the spec if time permits (and makes sense - looking at you, Extensible Events).

The full changelog

Matrix 1.9 is a relatively light maintenance release, but it still has a changelog! Read on for full details.

Client-Server API

Backwards Compatible Changes

  • Add the m.rule.suppress_edits default push rule, as per MSC3958. (#1617)

Spec Clarifications

  • Fix m.call.negotiate schema and example. (#1546)
  • Clarify that the via property is required for m.space.parent and m.space.child as per MSC1772. Contributed by @PaarthShah. (#1618)
  • Add a note to the /publicRooms API that the server name is case sensitive. (#1638)
  • Clarify that an m.room.name event with an absent name field is not expected behavior. (#1639)
  • Fix schemas used for account data and presence events in GET /initialSync. (#1647)
  • Fix various typos throughout the specification. (#1658, #1661, #1665)
  • Fix .m.rule.suppress_notices push rule not being valid JSON. (#1671)
  • Add missing properties for event_property_is and event_property_contains push conditions to PushConditions object. (#1673)
  • Indicate that fallback keys should have a fallback property set to true. (#1676)
  • Clarify that thread roots are not considered within the thread. (#1677)

Server-Server API

Spec Clarifications

  • Fix schema of m.receipt EDU. (#1636)
  • Fix various typos throughout the specification. (#1661)
  • Clarify that federation requests for non-local users are invalid. (#1672)

Application Service API

No significant changes.

Identity Service API

No significant changes.

Push Gateway API

No significant changes.

Room Versions

No significant changes.

Appendices

Spec Clarifications

  • Clarify timestamp specification with respect to leap seconds. (#1627)
  • Fix various typos throughout the specification. (#1652)

Internal Changes/Tooling

Backwards Compatible Changes

  • Add more CI checks for OpenAPI definitions and JSON Schemas. (#1656)
  • Generate server-server OpenAPI definition. (#1657)

Spec Clarifications

  • Replace all mentions of Swagger by OpenAPI. (#1633)
  • Fix enum types in JSON schemas. (#1634)
  • Fix schema of m.mentions object. (#1635)
  • Fix rendering of m.receipt event in Client-Server API. (#1637)
  • Remove required fieldname in appservice Protocol definition. (#1646)
  • Fix github action workflow responsible for releasing of @matrix-org/spec package. (#1648)
  • Upgrade GitHub actions. (#1660)

Matrix v1.8 release

23.08.2023 16:25 — Releases Travis Ralston

Hey all,

Matrix 1.8 is out now! The last release, Matrix 1.7, was full of features and laid out a plan for what Matrix 1.8 was expected to become. We spent most of our time focusing on the MSC3995-related MSCs from that original plan, but made an effort to get the other stuff looked at as well.

With this release we see a total of 9 MSCs achieve their formally adopted status. The full changelog at the bottom has all the details, but please read on for what’s new in room version 11, and Matrix 1.9’s roadmap :)

Room version 11

Matrix 1.8 features a new room version! Normally a room version wouldn’t have a particular theme, but for v11 we aimed to clean up the different algorithms and event format details. After 10 prior room versions there were some artifacts of the past sticking around (but not causing problems necessarily) - many of them are cleaned up here.

Specified originally as MSC3820, v11 introduces the following changes:

  • MSC2174 - Move redacts to the content of m.room.redaction events.
  • MSC2175 - Remove creator from m.room.create events (use sender instead).
  • MSC3989 - Remove origin from events.
  • MSC2176, MSC3821 - General updates to redaction algorithm.

Alongside being a cleanup room version, v11 is the initial base we used for our efforts in the IETF world. It provides an easier starting point for new server implementations, particularly when paired with Linearized Matrix (described as both an IETF Internet-Draft and MSC3995).

In future room versions the cleanup effort will continue, alongside additional features for supporting the IETF use cases. Watch this space for updates.

Upcoming in Matrix 1.9

We’re continuing the trend of planning ahead and have the following themes planned for work in Matrix 1.9:

  • Anything required by the MIMI/IETF efforts we’re undertaking. This currently includes:
    • Extensible Events
    • Role-Based Access Control (RBAC; new MSC expected)
    • Next generation of Linearized Matrix (already)
    • MSC4044 and MSC4045
    • Binary-encoded events (maybe, but probable)
    • Canonical DMs (maybe)
    • Sending events as rooms/servers instead of just users (maybe)
    • Further room version cleanup as needed
  • Merging MSC3939.
  • Accepting a combination of MSC2545, MSC1951, MSC3892, and MSC4027. This may involve creating a new MSC to cover the functionality of each, plus the needful for IETF and Extensible Events efforts.
  • Merging MSC3391 (time permitting).

A lot of this stuff might take the shape of opening MSCs or thinking about the problems, but we’re also very optimistic about getting them through FCP before November 2023. Watch this space for updates :)

The full changelog

There’s so many more things than what we covered in this blog post - flip through the changelog below for a full idea of what’s landed.

Client-Server API

Backwards Compatible Changes

  • Require callers to be joined to the room to report its events, as per MSC2249. (#1517)

Spec Clarifications

  • Fix missing type property in the JSON schema definition of the m.reaction event. Contributed by @chebureki. (#1552)
  • Make sure examples types match schema in definitions. (#1563)
  • Allow null in room_types in POST /publicRooms endpoints schemas. (#1564)
  • Fix broken header formatting. Contributed by @midnightveil. (#1578)
  • Render binary request and response bodies. (#1579)
  • Fix description of MAC calculation in SAS verification. (#1590)
  • Update link to SAS emoji definition data. (#1593)
  • Fix various typos throughout the specification. (#1597)

Server-Server API

Deprecations

  • Deprecate matrix SRV lookup steps during server discovery, as per MSC4040. (#1624)

Backwards Compatible Changes

  • Add matrix-fed SRV lookup steps to server discovery, as per MSC4040. (#1624)

Spec Clarifications

  • Document why /state_ids can respond with a 404. (#1521)
  • Fix response definition for POST /_matrix/federation/v1/user/keys/claim. (#1559)
  • Fix examples in server keys definition. (#1560)
  • Make sure examples types match schema in definitions. (#1563)
  • Allow null in room_types in POST /publicRooms endpoints schemas. (#1564)
  • Fix broken header formatting. Contributed by @midnightveil. (#1578)
  • Remove spurious mention of a "default port" with respect to SRV record lookup. (#1615)
  • Switch to ordered list for server name resolution steps. (#1623)

Application Service API

Spec Clarifications

  • Fix type of custom fields in thirdparty lookup queries. (#1584)

Identity Service API

Spec Clarifications

  • Make sure examples types match schema in definitions. (#1563)

Push Gateway API

No significant changes.

Room Versions

Backwards Compatible Changes

  • Add room version 11 as per MSC3820. (#1604)
  • Move redacts from top level to content on m.room.redaction events in room version 11, as per MSC2174. (#1604)
  • Remove creator from m.room.creator events in room version 11, as per MSC2175. (#1604)
  • Remove remaining usage of origin from events in room version 11, as per MSC3989. (#1604)
  • Update the redaction rules in room version 11, as per MSC2176 and MSC3821. (#1604)

Appendices

Backwards Compatible Changes

Spec Clarifications

  • Clarify spec re canonical JSON to handle negative-zero; also, give an example of negative-zero and a large power of ten. (#1573)

Internal Changes/Tooling

Backwards Compatible Changes

  • Upgrade Swagger data to OpenAPI 3.1. (#1310)
  • Create @matrix-org/spec npm package to ship the SAS Emoji data definitions & translations. (#1620)

Spec Clarifications

  • Update the CI to validate the file extension of changelog entries. (#1542)
  • Disclosure sections now only display their title when collapsed. (#1549)
  • Fix the sidebar in recent versions of Hugo. (#1551)
  • Bump jsonschema to validate JSON Schemas against Draft 2020-12. (#1556)
  • Use Redocly CLI to validate OpenAPI definitions. (#1558)
  • Use tag name as the OpenAPI definition version. (#1561)
  • Make sure version in x-changedInMatrixVersion is a string. (#1562)
  • Clarify usage of ABNF for grammar in the documentation style guide. (#1582)
  • Remove unnecessary oneOfs in JSON schemas. (#1585)
  • Update the version of Hugo used to render the spec to v0.113.0. (#1591)
  • Fix rendered changelog with new version of towncrier. (#1598)
  • Improve the layout of tables on desktop displays. Contributed by Martin Fischer. (#1601)

Matrix v1.7 release

25.05.2023 18:56 — Releases Travis Ralston

Hey all,

Matrix 1.7 has just been released! The last spec release was about 3 months ago, keeping us on track for regular quarterly releases. Unlike Matrix 1.6 though, today’s release is packed with plenty of features, some of which we’d like to call out here. Not all implementations will have support for these features yet though, and that’s okay (expected, even).

Adding support for a spec release can be a significant body of work. Instead of implementations having everything ready for spec release day, the idea is that they gain support over the next few months. If you’re able, please help those projects get v1.7’s features.

Today, we see 15 MSCs achieve their formally adopted status. All of them bring forward some much-needed features to Matrix, and a few highlights are below. Read on to the full changelog for a complete overview, and for a sneak peak at what the Spec Core Team (SCT) is planning to look at for v1.8 👀

Continue reading…

Matrix v1.6 release

14.02.2023 17:04 — Releases Travis Ralston

Hey all,

Matrix 1.6 is out there! Like Matrix 1.5 back in November, this release is largely a maintenance update. Matrix 1.1 through 1.4 have been relatively major upgrades, so a little time between features doesn’t feel like a bad idea :)

As with all spec releases, we encourage implementations to gradually update over the next few months rather than have support for everything on release day - please be kind to the projects you use, and help them gain support if able.

Matrix 1.6 sees just 7 MSCs get merged, though this is to be expected from a maintenance release. Check out Matthew’s Matrix 2.0 talk at FOSDEM for an idea of what’s expected over the next few releases.

We’ve covered a couple of the MSCs below, but read on to the full changelog for the full picture.

Continue reading…

Matrix v1.5 release

17.11.2022 16:56 — Releases Travis Ralston
Last update: 17.11.2022 16:44

Hey all,

We’ve just released Matrix 1.5, a largely maintenance update for the spec. We intentionally haven’t landed any major features in this release as Matrix 1.4, just shy of 2 months ago, had introduced fairly large features for clients and servers to consider. As with all spec releases, we encourage implementations to gradually update over the next few months rather than expect them to have support for everything on release day.

Matrix 1.5 sees just 2 MSCs get merged, though this is to be expected from a maintenance release. We expect that the next release (in Q1 2023) will have a few more exciting features to it :)

We’ve covered both MSCs below, but read on to the full changelog for the full picture.

MSC3267: Reference relations

Already supported implicitly by the spec up until now, reference relations are a way to simply reference another event. Usually these sorts of relations are used for events which need to be related to each other, but a dedicated relationship type doesn’t make a lot of sense.

In-room verification and MSC3381: Polls are examples of how these relations get used.

MSC3905: Clarify appservice interest in user IDs

MSC3905 fixes an issue in the specification where appservices (usually bridges) specifying a users regex without homeserver domain would end up receiving far more event traffic than they would have intended. With the MSC, appservices are now only considered interested in “local” users, regardless of how vague their users namespace is.

Overall this should have no effect on most bridges/appservices, however if an appservice in the wild really does need to listen to all users on all homeservers, it can specify a non-exclusive namespace on all rooms instead.

While writing this MSC into the spec we took some time to clarify the appservice registration requirements more generally: check them out here.

The full changelog

MSCs are how the spec changes in the way it does - adding, fixing, and maintaining features for the whole ecosystem to use. Check out the full changelog below, and the Spec Change Proposals page for more information on how these MSCs got merged (hint: they submitted a proposal, which anyone can do - take a look at the Matrix Live episode where Matthew covers the proposal process).

Client-Server API

Backwards Compatible Changes

  • Add m.reference relations, as per MSC3267. (#1206)
  • Add missing documentation for m.key.verification.request msgtype for in-room verification. (#1271)

Spec Clarifications

  • Fix various typos throughout the specification. (#1260, #1265, #1276)
  • Fix naming of device_one_time_keys_count in /sync. (#1266)
  • Improve display of event subtypes. (#1283)
  • Improve documentation about ephemeral events. (#1284)
  • Define a 400 response from /_matrix/client/v3/directory/rooms/{roomAlias}. (#1286)
  • Clarify parts of the end-to-end encryption sections. (#1294, #1345)
  • Various clarifications throughout the specification. (#1306)
  • Replace set_sound push rule action by set_tweak. (#1318)
  • Clarify the behavior of PUT /_matrix/client/v3/pushrules/{scope}/{kind}/{ruleId}. (#1319)
  • Clarify that .m.rule.master has a higher priority than any push rule. (#1320)
  • Require request field refresh_token at endpoint POST /_matrix/client/v3/refresh. (#1323)
  • Fix a number of broken links in the specification. (#1330)
  • Add example read receipt to GET /_matrix/client/v3/sync response example. (#1341)

Server-Server API

Spec Clarifications

  • Fix a number of broken links in the specification. (#1330)

Application Service API

Spec Clarifications

  • Clarify that application services can only register an interest in local users, as per MSC3905. (#1305)

Identity Service API

Spec Clarifications

  • Fix a number of broken links in the specification. (#1330)

Push Gateway API

No significant changes.

Room Versions

Spec Clarifications

  • Reword the event auth rules to clarify that users cannot demote other users with the same power level. (#1269)
  • Various clarifications to the text on event authorisation rules. (#1270)
  • Fix a number of broken links in the specification. (#1330)

Appendices

No significant changes.

Internal Changes/Tooling

Backwards Compatible Changes

  • Update docsy theme to v0.5.0 + matrix.org modifications (https://github.com/matrix-org/docsy/commit/a0032f8db919a6c67ba6cdef2c455f105b6272a2). (#1295)

Spec Clarifications

  • Improve error messages emitted by resolve-additional-types template. (#1303)
  • Fix link to API viewer. (#1308)
  • Stop rendering the subsections of the Client-Server API and Room Versions specs as their own separate pages. (#1317)
  • Use a link checker to ensure that we do not have broken links. (#1329, #1338)
  • Update instructions to preview Swagger definitions. (#1331)
  • Make definition anchors more unique. (#1339)
  • Generate the unstable changelogs with towncrier, for consistency. (#1340)
  • Update CONTRIBUTING.md to mention that non-content changes to this repo should have an "internal" changelog entry. (#1342)
  • Update module summary table with new modules: Event Replacements, Threading and Reference Relations. (#1344)
  • Disable RSS generation for the spec. (#1346)

Matrix v1.3 release

16.06.2022 17:16 — Releases Travis Ralston
Last update: 15.06.2022 22:00

Hey all,

It’s another quarter and therefore another spec release! Matrix 1.2 was released back in February, and while a bit late in the quarter this time around we’ve still got some exciting additions coming to you in this release.

Like last time, the speed of these releases might feel a bit quick for developers: fret not if you’re still working on v1.1 or v1.2 implementations. We’re not expecting that implementations update as soon as a new spec release is published, but rather that the ecosystem gradually update over the course of the next few months. Implementations should be aiming for as close to realtime as they can get though, particularly considering v1.4 is expected to have some large features (more on that later on).

Matrix 1.3 sees 14 MSCs get merged, but we can’t possibly go into detail on them all here. We’ve picked some notable highlights and recommend the full changelog at the bottom for a complete idea of what’s been going on.

Aggregations and the relationships made along the way

It’s no secret that MSC1849-style server-side aggregation of related messages have been in the review backlog for a while. We ended up splitting MSC1849 down into more reviewable chunks like MSC2675, allowing us to finally land the first pieces into Matrix 1.3 today.

In the spec there aren’t currently any defined relationships which make use of aggregations or even the rel_type described by MSC2674, but we do expect that v1.4 of the spec will have support for at least threads (MSC3440) and edits (MSC2676), filling the gap. For now, we’ve decided that holding aggregations back until v1.4 doesn’t make a lot of sense, so we have launched them into the world as-is for custom relations or for clients & servers to prepare for what’s expected to be coming in v1.4 of the spec.

To further prepare for threads, we’ve also removed some restrictions of rich replies through MSC3676, thus allowing replies to be constructed with non-text messages like images. Check out the new rich replies module for more information.

Join if you can, or just knock

When we launched restricted rooms in Matrix 1.2 we noted that we forgot to handle a case where someone might want to support both knocking and restricted rooms at the same time. We’ve fixed that with a stop-gap join rule from MSC3787 in room version 10.

The new knock_restricted join rule allows the room to keep its desire to be restricted whilst also allowing members who do not meet the criteria to knock on the room instead. We’ll likely expand on this sort of mixing of join rules in proposals like MSC3386 down the line, however for now this should cover the gap in support. Next up: figuring out how to make encrypted room history available to these new joiners in a safe way.

A thread for next time

Originally planned for this release, MSC3440-style threads are anticipated to be ready for v1.4 (next quarter) with support for notifications and, of course, a whole new way to communicate in a room.

Threads are one of the more complicated features we’ve tried to land in recent history as it has a large impact on a wide variety of the spec: everything from event relationships (fixed in this release) to read receipts to push notifications needs to be worked out to build a system that not only users can understand, but also the developers trying to build it. With this massive surface area we just weren’t comfortable with adding threads to v1.3 as-is, given problems like notifications aren’t yet fully solved.

Alongside threads, we also anticipate that MSC2676-style message editing will be landing in v1.4, finally specifying how to update an event’s contents without having to redact & re-send. Although message editing has been supported for a long time in some clients, we're excited that it will finally become part of the official specification, meaning it can be implemented more widely. Messaging clients are encouraged to give the proposal an early read and possibly even attempt implementation if not already done to help us ensure the system is in a reasonable state for inclusion in the spec, though we do note that feature requests for edits will likely be deferred to a future MSC.

Keep an eye on This Week In Matrix for updates on what v1.4 is expected to include, and how things are progressing.

The full changelog

MSCs are how the spec changes in the way it does - adding, fixing, and maintaining features for the whole ecosystem to use. The blog post can’t cover them all, but that doesn’t make them any less important! Check out the full changelog below, and the Spec Change Proposals page for more information on how these MSCs got merged (hint: they submitted a proposal, which anyone can do - take a look at the Matrix Live episode where Matthew covers the proposal process).

Client-Server API

Deprecations

  • Deprecate the sender_key and device_id on m.megolm.v1.aes-sha2 events, and the sender_key on m.room_key_request to-device messages, as per MSC3700. (#1101)

Backwards Compatible Changes

  • Make from optional on GET /_matrix/client/v3/messages to allow requesting events from the start or end of the room history, as per MSC3567. (#1002)
  • Add refresh tokens, per MSC2918. (#1056, #1113)
  • 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. (#1062)
  • Add support for a new knock_restricted join rule in supported room versions, as per MSC3787. (#1099)

Spec Clarifications

  • Clarify that the url field in m.room.avatar events is not required. (#987)
  • Clarify that the type in user-interactive authentication can be omitted. (#989)
  • Adjust the OpenAPI specification so that the type Flow information is explicitly defined when the client-server API is rendered. (#1003)
  • Correct the default value for invite where it is not specified in an m.room.power_levels event. (#1021)
  • Update various links which pointed to the old matrix-doc github repository. (#1032)
  • Removed m.room.message.feedback per MSC3582. (#1035)
  • Fix various typos throughout the specification. (#1051, #1054, #1059, #1081, #1097, #1110, #1115, #1126, #1127, #1128, #1129, #3681, #3708)
  • Clarify that state keys starting with @ are in fact reserved. Regressed from #3658. (#1100)
  • Remove unenforced size limit on the name field of m.room.name events. (#3669)
  • Remove erroneous room_id field from examples of m.read, m.typing in /sync and m.fully_read in room account data. (#3679)
  • Clarify the behaviour of event_match in push rule conditions. (#3690)
  • Fix incorrectly referenced m.login.appservice login identifier, instead using m.login.application_service. (#3711)
  • Fix membership state transitions to denote that invite->knock and external->leave are valid transitions. (#3730)

Server-Server API

Backwards Compatible Changes

  • Add a destination property to the Authorization header, as per MSC3383. (#1067)

Spec Clarifications

  • Remove largely unused origin field from PDUs. (#998)
  • Update various links which pointed to the old matrix-doc github repository. (#1032)
  • Clarify the format for the Authorization header. (#1038, #1067)
  • Clarify what a "valid event" means when performing checks on a received PDU. (#1045)
  • Clarify that valid_until_ts is in milliseconds, like other timestamps used in Matrix. (#1055)
  • Clarify that checks on PDUs should refer to the state before an event. (#1070)
  • Clarify the historical handling of non-integer power levels. (#1099)
  • Fix various typos throughout the specification. (#1110)
  • Correct misleading text for /send_join response. (#3703)
  • Clarify that the content for X-Matrix signature validation is the parsed JSON body. (#3727)

Application Service API

Backwards Compatible Changes

Identity Service API

No significant changes.

Push Gateway API

No significant changes.

Room Versions

Backwards Compatible Changes

  • Add room version 10 as per MSC3604. (#1099)
  • Enforce integer power levels in room version 10 as per MSC3667. (#1099)
  • Add a knock_restricted join rule supported by room version 10 as per MSC3787. (#1099)
  • Update the default room version to 9 as per MSC3589. (#3739)

Spec Clarifications

  • Improve readability and understanding of the state resolution algorithms. (#1037, #1042, #1043, #1120)
  • Improve readability of the authorization rules. (#1050)
  • For room versions 8, 9, and 10: clarify which homeserver is required to sign the join event. (#1093)
  • Clarify that room versions 1 through 9 accept stringy power levels, as noted by MSC3667. (#1099)
  • For all room versions: Add m.federate to the authorization rules, as originally intended. (#1103)
  • For room versions 2 through 10: More explicitly define the mainline of a power event and the mainline ordering of other events. (#1107)
  • For room versions 7, 8, 9, and 10: fix join membership authorization rules when join_rule is knock. (#3737)

Appendices

No significant changes.