v1.13

Client-Server API

New Endpoints

• Add POST /_matrix/client/v3/rooms/{roomId}/report, as per MSC4151. (#1938, #2028)

Backwards Compatible Changes

• Add error codes to requestToken endpoints, as per MSC4178. (#1944)
• Remove reply fallbacks, as per MSC2781. (#1994)
• Clarify the allowed HTTP methods in CORS responses, as per MSC4138. (#1995, #2011)
• Add new M_USER_SUSPENDED error code behaviour, as per MSC3823. (#2014)

Spec Clarifications

• The reason parameter in POST /_matrix/client/v3/rooms/{roomId}/report/{eventId} can be omitted instead of left blank, as per MSC2414. (#1938)
• Correct OpenAPI specification for query parameters to GET /_matrix/client/v3/thirdparty/location/{protocol} endpoint. (#1947)
• Sort VoIP events semantically. (#1967)
• Clarify that servers must forward custom keys in PusherData when sending notifications to the push gateway. (#1973)
• Clarify formats of string types. (#1978, #1979, #1980)
• Clarify that the async upload endpoint will return 404 in some cases. (#1983)
• Remove distinction between StateFilter and RoomEventFilter. (#2015)
• Add hyperlinks throughout the specification. (#2016)
• Use json instead of json5 for syntax highlighting. (#2017)
• Specify order that one-time keys are issued by /keys/claim, as per MSC4225. (#2029)

Server-Server API

Backwards Compatible Changes

• Make ACLs apply to EDUs, as per MSC4163. (#2004)

Spec Clarifications

• Add 403 error response to /_matrix/federation/v1/state_ids/{roomId}. (#1926)

Application Service API

Backwards Compatible Changes

• Allow sending ephemeral data to application services, as per MSC2409. (#2018)

Identity Service API

No significant changes.

Push Gateway API

Spec Clarifications

• Document the schema of PusherData. (#1968)
• The path of HTTP pusher URLs is fixed to /_matrix/push/v1/notify. (#1974)

Room Versions

Spec Clarifications

• Clarify rule 4.3.1 of the auth rules in room version 11 to state which event's sender the state_key needs to match. (#2024)

Appendices

Spec Clarifications

• Remove note about reference implementations. (#1966)

Internal Changes/Tooling

Spec Clarifications

• Add x-weight property for sorting events rendered with the event-group shortcode. (#1967)
• Enforce consistent vertical spacing between paragraphs in endpoint definitions. (#1969, #2005)
• Remove boxes/added-in-paragraph shortcode. (#1970)
• Remove withVersioning parameter of rver-fragment shortcode. (#1971)
• Remove span element from added-in and changed-in shortcodes. (#1972)
• Fix formatting of added-in and changed-in shortcodes by using % delimiter. (#1975)
• Remove CSS workaround for scroll-anchoring. (#1976)
• Rename custom-formats.yaml to string-formats.yaml and update its docs. (#1977)
• Fix relative URLs when serving the specification with a custom baseURL. (#1984, #1997)
• Rename .htmltest.yaml to .htmltest.yml. (#1985)
• Improve the JS script to highlight the current ToC entry. (#1991, #2002)
• Upgrade docsy to 0.11.0 and hugo to 0.139.0. (#1996, #2007)
• Improve the quality of the rendered diagrams (#1999)
• Update the Inter font and allow the browser to render the page before it is loaded (#2000)
• Use a proper Matrix favicon (#2001)
• Clean up unused CSS classes in openapi/render-operation partial. (#2003)
• Fix changed-in partial when used with multiple paragraphs. (#2006)
• Optimize generated CSS by removing unused selectors. (#2008)
• Remove trailing slash on void HTML elements. (#2009)
• Remove type and language attributes of script element. (#2021)
• Change the accessible role of info boxes to note. (#2022)

v1.12

Client-Server API

Deprecations

• Deprecate the server_name query parameter on POST /_matrix/client/v3/join/{roomIdOrAlias} and POST /_matrix/client/v3/knock/{roomIdOrAlias}, as per MSC4156. (#1933)

Removed Endpoints

• Remove references to device-specific push rules. (#1842)
• Remove the deprecated name attribute on HTML anchor elements, as per MSC4159. (#1870)

Backwards Compatible Changes

• Add 403 responses on GET /_matrix/client/v3/profile/{userId}/avatar_url and GET /_matrix/client/v3/profile/{userId}/displayname, as per MSC4170. (#1867)
• Add support for marking rooms as unread, as per MSC2867. (#1895, #1941)
• Add via query parameter on POST /_matrix/client/v3/join/{roomIdOrAlias} and POST /_matrix/client/v3/knock/{roomIdOrAlias}, as per MSC4156. (#1933)
• Add account locking, as per MSC3939. (#1934)
• Guest accounts can now download/thumbnail media from the new authenticated endpoints, as per MSC4189. (#1959)

Spec Clarifications

• Rename and sort the modules in the feature profiles table for easier skimming. (#1855)
• Clarify that room avatars cannot be encrypted. (#1871)
• Document the acronyms and alternate names for the "Secrets" section. (#1875)
• Improve recommendation for how to form transaction IDs. (#1888)
• Clarify that the deprecated dont_notify and coalesce push rule actions MUST be ignored, not rejected. (#1890)
• Fix various typos throughout the specification. (#1892)
• Add missing references to m.set_displayname, m.set_avatar_url, and m.3pid_changes in capabilities table. (#1897)
• Clarify that the fallback login page calls window.matrixLogin.onLogin instead of window.onLogin. (#1899)
• Remove confusing description of restricted rooms with no valid conditions. (#1903)
• Clarify that window.matrixLogin.onLogin is called with the response body of POST /_matrix/client/v3/login. (#1905)
• Document the m.get_login_token capability, as per MSC3882. (#1908)
• Clarify that the User identifier object in POST /_matrix/client/v3/login contains additional properties that depend on the identification type. (#1909)
• Don't mention that GET /_matrix/client/v3/profile/{userId} can return additional properties because this is true for almost every endpoint. (#1910)
• Improve wording of the unauthenticated media deprecation box. Contributed by @HarHarLinks. (#1916)
• Additional properties in GET /.well-known/matrix/client don't have to be objects. (#1920)
• Document that the spec uses RFC 2119 keywords. Contributed by @HarHarLinks. (#1928)
• Specify Content-Type and Content-Disposition usage in the media repo, as per MSC2701 and MSC2702. (#1935)
• Additional keys in GET /_matrix/client/v3/capabilities don't have to be objects. (#1945)

Server-Server API

Backwards Compatible Changes

• Add 403 response on GET /_matrix/federation/v1/query/profile, as per MSC4170. (#1867)

Spec Clarifications

• Remove origin field from PDU example because it doesn't exist in the schema anymore. (#1918)
• Document that the spec uses RFC 2119 keywords. Contributed by @HarHarLinks. (#1928)
• Fix required fields in GET /_matrix/key/v2/server response schema. (#1930)
• Use "server name" instead of "DNS name" to avoid confusion with the "DNS name" component of "server names" as defined in the appendices. (#1946)

Application Service API

Spec Clarifications

• Document that the spec uses RFC 2119 keywords. Contributed by @HarHarLinks. (#1928)

Identity Service API

Spec Clarifications

• Document that the spec uses RFC 2119 keywords. Contributed by @HarHarLinks. (#1928)

Push Gateway API

Spec Clarifications

• Document that the spec uses RFC 2119 keywords. Contributed by @HarHarLinks. (#1928)

Room Versions

Spec Clarifications

• Fix a formatting issue in state resolution v2. (#1896)
• Document that the spec uses RFC 2119 keywords. Contributed by @HarHarLinks. (#1928)

Appendices

Spec Clarifications

• Document that the spec uses RFC 2119 keywords. Contributed by @HarHarLinks. (#1928)

Internal Changes/Tooling

Spec Clarifications

• The Matrix.org Foundation no longer requires "real" or "legally identifiable" names in order to contribute to projects. (#1886, #1914)
• Document the removal changelog category. (#1907)
• Use dedicated fonts for better support of mathematical symbols. (#1919)
• Document that the spec uses RFC 2119 keywords. Contributed by @HarHarLinks. (#1928)
• Provide markdown checklists for changelogs under /changelog/$VERSION/checklist.md. (#1937, #1954)
• Add the deprecated field to properties of OpenAPI definitions and JSON Schemas. (#1940)
• Use relative permalink to redirect to latest changelog. (#1956)

v1.11

Client-Server API

Deprecations

• Authentication using a query string is now deprecated, as per MSC4126. The Authorization header should be used instead. (#1808)
• Use of the /_matrix/media/* endpoints is now deprecated. New, authenticated, endpoints are available instead. (#1858)

New Endpoints

• GET /_matrix/client/v1/media/config (#1858)
• GET /_matrix/client/v1/media/download/{serverName}/{mediaId} (#1858)
• GET /_matrix/client/v1/media/download/{serverName}/{mediaId}/{fileName} (#1858)
• GET /_matrix/client/v1/media/preview_url (#1858)
• GET /_matrix/client/v1/media/thumbnail/{serverName}/{mediaId} (#1858)

Backwards Compatible Changes

• Add support for muting in VoIP calls, as per MSC3291. (#1755)
• Add optional animated query string option to GET /thumbnail, as per MSC2705. (#1757)
• Specify terms of services at registration, as per MSC1692. (#1812)
• Add support for mathematical messages, as per MSC2191. (#1816)
• Do not require UIA when first uploading cross-signing keys, as per MSC3967. (#1828)
• Add the new unsigned.membership property to events, as per MSC4115. (#1847)
• Media downloads and thumbnails are now authenticated, as per MSC3916. (#1858)
• Some media endpoints are now consistently under /_matrix/client/{version}/media/* instead of /_matrix/media/*, as per MSC3916. (#1858)

Spec Clarifications

• Add /logout and clarify the endpoints which do not take a JSON request body. (#1644)
• Clarify that the type of the POST /login request must be one of the types returned by the GET /login response. (#1776)
• Link to existing grammar where possible in types. (#1813)
• Rename "recovery key" to "backup decryption key". (#1819)
• Clarify that the device's Ed25519 signing key should be used in QR code verification (as opposed to the device's Curve25519 identity key). (#1829)
• Fix various typos throughout the specification. (#1832, #1841, #1852, #1853)
• Specify the encoding to be used when generating QR codes for device verification. (#1839)
• Clarify that an access token is optional on the POST /account/password and POST /account/deactivate endpoints. (#1843)
• Use RFC 2119 keywords more consistently. (#1846, #1861)
• Move size limits for user, room and event IDs into the appendix and clarify that the length is to be measured in bytes. (#1850)
• Clarify that relations recursion should be capped at a certain depth. (#1854)
• Add missing secrets, third-party invites and room tagging modules to feature profiles table. (#1860)
• Clarify when server name is used and link to the definition. (#1862)
• Clarify where keys reside when checking an m.room.encrypted event. (#1863)
• Clarify that /media/v3/upload/{serverName}/{mediaId} requires authentication. (#1872)

Server-Server API

Deprecations

• Use of the Client-Server API /_matrix/media/* endpoints is now deprecated. New, authenticated, endpoints are available instead. (#1858)

New Endpoints

• GET /_matrix/federation/v1/media/download/{mediaId} (#1858)
• GET /_matrix/federation/v1/media/thumbnail/{mediaId} (#1858)

Backwards Compatible Changes

• Media downloads and thumbnails are now authenticated, as per MSC3916. (#1858, #1869)

Spec Clarifications

• Link to existing grammar where possible in types. (#1813)
• Clarify that whitespace around commas is allowed in the X-Matrix Authorization header value params list. (#1818)
• Clarify that the event field of the /v2/send_join response is only required when the event is signed by the resident server. (#1834, #1840)
• Replace references to RFC 7235 and RFC 7230 that are obsoleted by RFC 9110. (#1844)
• Fix various typos throughout the specification. (#1877)

Application Service API

Spec Clarifications

• Clarify that appservices should be notified of events relating to the sender_localpart user. (#1810)

Identity Service API

Deprecations

• Authentication using a query string is now deprecated, as per MSC4126. The Authorization header should be used instead. (#1808)

Push Gateway API

No significant changes.

Room Versions

Spec Clarifications

• Clarify that redaction events are still subject to all applicable auth rules. (#1824)
• Fix various typos throughout the specification. (#1827, #1848)
• Fix the rendering of the event format for room versions 1 and 2. (#1883)
• Generate the Table of Contents with Hugo rather than JavaScript. (#1884)

Appendices

Deprecations

• Deprecate linking to events in rooms identified by alias, as per MSC4132. (#1823)

Spec Clarifications

• Define 'Opaque Identifier Grammar'. (#1791)
• Define common cryptographic key representation. (#1819)
• Move size limits for user, room and event IDs into the appendix and clarify that the length is to be measured in bytes. (#1850)

Internal Changes/Tooling

Spec Clarifications

• Update the spec release process and related documentation. (#1759)
• Fix npm release script for @matrix-org/spec. (#1765)
• Formatting fixes in CONTRIBUTING.rst. ([#1769](https://github.com/matrix-org/matrix-spec/i...

v1.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)

v1.9

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)

v1.8

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

• Allow + in Matrix IDs, as per MSC4009. (#1583)

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)

v1.7

Client-Server API

New Endpoints

• POST /_matrix/media/v1/create (#1499)
• PUT /_matrix/media/v3/upload/{serverName}/{mediaId} (#1499)
• POST /_matrix/client/v1/login/get_token (#1530)

Backwards Compatible Changes

• Changes to the server-side aggregation of m.replace (edit) events, as per MSC3925. (#1440, #1525)
• Add new push rule conditions event_property_is and event_property_contains, as per MSC3758 and MSC3966. (#1464)
• Add m.annotation relations (reactions), as per MSC2677. (#1475, #1531)
• Support asynchronous media uploads, as per MSC2246. (#1499, #1510)
• Document the m.mentions property; the .m.rule.is_user_mention and .m.rule.is_room_mention push rules; and other notification behaviour, as per MSC3952. (#1508)
• Improve VoIP signaling, as per MSC2746. (#1511, #1540)
• Update the scope of transaction IDs, as per MSC3970. (#1526)
• Add an ability to redirect media downloads, as per MSC3860. (#1529)
• Add an ability to use an existing session to log in another, as per MSC3882. (#1530)

Spec Clarifications

• Clarify the sections of the specification concerning aggregation of child events. (#1424)
• Fix various typos throughout the specification. (#1432, #1442, #1447, #1455, #1465, #1500, #1509)
• Clarify that reply chain fallback for threads might not be present. (#1439)
• Clarify what event property the content-specific push rules match against. (#1441)
• Clarify the semantics that make requests idempotent. (#1449)
• Improve documentation of how clients use push rules. (#1461)
• Clarify that servers should enforce a default limit on a filter if one is not specified. (#1463)
• Disambiguate using property names with dots in them during push rule processing, as per MSC3873 and MSC3980. (#1464)
• Fix phrasing & typography in the registration endpoint description. Contributed by @HarHarLinks. (#1474)
• Remove outdated text saying that state_default is 0 if there is no m.room.power_levels event in a room. (#1479)
• Remove fictitious token parameter on /keys/query endpoint. (#1485)
• Fix rendering of properties with a list of types. (#1487)
• Clarify parts of the cross-signing signature upload request. (#1495)
• Remove the dont_notify and coalesce push rule actions, as per MSC3987. (#1501)
• Clarify m.location scheme by partially reverting f1f32d3. Contributed by @HarHarLinks. (#1507)
• Add missing knock_restricted join rule to the m.room.join_rules schema. (#1535)

Server-Server API

Spec Clarifications

• Fix various typos throughout the specification. (#1431, #1447, #1466, #1518)
• Fix PDU examples by removing invalid OpenAPI reference to examples/minimal_pdu.json. (#1454)
• Remove leftover {key_id} from /_matrix/key/v2/server/. (#1473)
• Remove extraneous age_ts field from the reference hash calculation section. (#1536)

Application Service API

New Endpoints

• POST /_matrix/app/v1/ping (#1516)
• POST /_matrix/client/v1/appservice/{appserviceId}/ping (#1516)

Backwards Compatible Changes

• Add homeserver->appservice ping mechanism, as per MSC2659. Contributed by @tulir at @beeper. (#1516, #1541)

Spec Clarifications

• Fix various typos throughout the specification. (#1447)

Identity Service API

Spec Clarifications

• Corrections to the response format of /_matrix/identity/v2/store-invite. (#1486)

Push Gateway API

No significant changes.

Room Versions

Spec Clarifications

• Clarifications of event ID formats in early room versions (#1484)

Appendices

Spec Clarifications

• Clarify that the term "Canonical JSON" is a specific thing within the Matrix specification. (#1468)
• Remove references to groups. (#1483)
• Clarifications of event ID formats in early room versions. (#1484)

Internal Changes/Tooling

Spec Clarifications

• Update references to Inter font. (#1444)
• Endpoint disclosures now hide everything but the URL. (#1446)
• Wrap $ref in allOf where other attributes are present, to improve OpenAPI compliance. (#1457)
• Minor cleanups to the GitHub Actions workflows (#1476)
• Fix generation of anchors for additional properties. (#1488)
• Fix various typos throughout the specification. (#1534)
• Document more of the spec release timeline/process. (#1538)

v1.6

Client-Server API

Backwards Compatible Changes

• Add information on standard error responses for unknown endpoints/methods, as per MSC3743. (#1347)
• Add /rooms/<roomID>/timestamp_to_event endpoint, as per MSC3030. (#1366)
• Define hkdf-hmac-sha256.v2 MAC method for SAS verification, as per MSC3783. (#1412)

Spec Clarifications

• Clarify the power levels integer range. (#1169, #1355)
• Clarify that /context always returns event even if limit is zero. Contributed by @sumnerevans at @beeper. (#1239)
• Clarify what fields are required when deleting a pusher (#1321)
• Improve the presentation of push rule kinds and actions. (#1348)
• Add missing description to m.call.answer schema. (#1353)
• Fix various typos throughout the specification. (#1363)
• Clarify parts of the end-to-end encryption sections. (#1381)
• Move login API definitions to the right heading. Contributed by @HarHarLinks. (#1382)
• Clarify which events will be included in Stripped State. Contributed by @andybalaam. (#1409)
• Add links to the spec for the definition of 3PID medium. (#1417)
• Correct the order of the default override pushrules in the spec. (#1421)
• Improve distinction between tags and their attributes in the rich text section. Contributed by Nico. (#1433)

Server-Server API

Breaking Changes

• Remove keyId from the server /keys endpoints, as per MSC3938. (#1350)

Backwards Compatible Changes

• Add information on standard error responses for unknown endpoints/methods, as per MSC3743. (#1347)
• Add /timestamp_to_event/<roomID> endpoint, as per MSC3030. (#1366)
• Extend /_matrix/federation/v2/send_join to allow omitting membership events, per MSC3706. (#1393, #1398)
• Note that /_matrix/federation/v2/send_join should include heroes for nameless rooms, even when allowed to omit membership events, per MSC3943. (#1425)

Spec Clarifications

• Include examples inline instead of using a reference for invite endpoint definitions. (#1349)
• Fix POST _matrix/federation/v1/user/keys/claim response schema. (#1351)
• Correct the default invite level definition in the "Checks performed on receipt of a PDU" section. (#1371)
• Clarify that CNAMEs are permissible for server names. (#1376)
• Fix edu_type in EDU examples. (#1383)

Application Service API

Backwards Compatible Changes

• Add information on standard error responses for unknown endpoints/methods, as per MSC3743. (#1347)

Identity Service API

Backwards Compatible Changes

• Add information on standard error responses for unknown endpoints/methods, as per MSC3743. (#1347)

Push Gateway API

Backwards Compatible Changes

• Add information on standard error responses for unknown endpoints/methods, as per MSC3743. (#1347)

Room Versions

Backwards Compatible Changes

• Update the default room version to 10, as per MSC3904. (#1397)

Spec Clarifications

• Clarify the grammar for room versions. (#1422)
• Fix various typos throughout the specification. (#1423)

Appendices

No significant changes.

Internal Changes/Tooling

Spec Clarifications

• Add link to the unstable spec to the README. (#1357)
• Improve safety of the proposals retrieval script in the event of failure. (#1368)
• Rename <content> to content in the OpenAPI files for content uploads. (#1370)
• Stop autogenerating examples where we already have an example. (#1384)
• Improve formatting of definitions in the Push Notifications section. (#1415)

v1.5

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 (matrix-org/docsy@a0032f8). (#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)

v1.4

Client-Server API

Removed Endpoints

• Remove unused policy room sharing mechanism, as per MSC3844. (#1196)

Backwards Compatible Changes

• Add a .m.rule.room.server_acl push rule to match m.room.server_acl events, as per MSC3786. (#1190, #1201)
• Add Cross-Origin-Resource-Policy (CORP) headers to media repository, as per MSC3828. (#1197)
• Copy a room's type when upgrading it, as per MSC3818. (#1198)
• Add room_types filter and room_type response to /publicRooms, as per MSC3827. (#1199)
• Add m.replace relations (event edits), as per MSC2676. (#1211)
• Add m.read.private receipts, as per MSC2285. (#1216)
• Make m.fully_read optional on /read_markers, as per MSC2285. (#1216)
• Allow m.fully_read markers to be set from /receipts, as per MSC2285. (#1216)
• Add threading via m.thread relations, as per MSC3440, MSC3816, MSC3856, and MSC3715. (#1254)
• Add per-thread notifications and read receipts, as per MSC3771 and MSC3773. (#1255)
• Add thread_id to the /receipt endpoint, as per MSC3771. (#1261)

Spec Clarifications

• Mention that the /rooms/{roomId}/invite endpoint will return a 200 response if the user is already invited to the room. (#1084)
• Fix various typos throughout the specification. (#1135, #1161, #1164, #1170, #1180, #1215, #1238, #1243, #1263)
• Describe return codes for account data endpoints, and clarify that per-room data does not inherit from the global data. (#1155)
• Clarify that policy rule globs work like ACL globs. Contributed by Nico. (#1165)
• Clarify the format of some structures in the End-to-end encryption module. (#1166)
• Add HTML anchors for object definitions in the formatted specification. (#1174)
• Tweak the styling of <code> snippets in tables rendered from OpenAPI definitions. (#1179)
• Update "API Standards" section to clarify how JSON is used. (#1185)
• Clarify that the "device_id", "user_id" and "access_token" fields are required in the response body of POST /_matrix/client/v3/login. (#1210)
• Reinforce the relationship of refreshed access tokens to transaction IDs. (#1236)
• Clarify enum values by separating possible values with commas. (#1240)

Server-Server API

Backwards Compatible Changes

• Add per-thread notifications and read receipts, as per MSC3771 and MSC3773. (#1255)

Spec Clarifications

• Add HTML anchors for object definitions in the formatted specification. (#1174)
• Tweak the styling of <code> snippets in tables rendered from OpenAPI definitions. (#1179)
• Update "API Standards" section to clarify how JSON is used. (#1185)

Application Service API

Breaking Changes

• Replace homeserver authorization approach with an Authorization header instead of access_token when talking to the application service, as per MSC2832. (#1200)

Spec Clarifications

• Add HTML anchors for object definitions in the formatted specification. (#1174)

Identity Service API

Spec Clarifications

• Add HTML anchors for object definitions in the formatted specification. (#1174)
• Update "API Standards" section to clarify how JSON is used. (#1185)

Push Gateway API

Spec Clarifications

• Add HTML anchors for object definitions in the formatted specification. (#1174)

Room Versions

Spec Clarifications

• For room versions 1 through 10, clarify that events with rejected auth_events must be rejected. (#1137)
• For room versions 2–10: correct a mistaken clarification to the state resolution algorithm. (#1158)
• For room versions 7 through 10: Clarify that invite->knock is actually a legal transition. (#1175)

Appendices

No significant changes.

Internal Changes/Tooling

Backwards Compatible Changes

• Add internal changes changelog section. (#1194)

Spec Clarifications

• Render HTML anchors for object definition tables. (#1191)
• Give rendered-data sections a background and some padding. (#1195)
• Fix rendering of shortcodes within the client-server API. (#1205)
• Fix the spacing of mapping types generated from the OpenAPI spec. (#1230)