Skip to content

Releases: matrix-org/matrix-spec

v1.12

07 Oct 19:35
Compare
Choose a tag to compare

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

Identity Service API

Spec Clarifications

Push Gateway API

Spec Clarifications

Room Versions

Spec Clarifications

Appendices

Spec Clarifications

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

20 Jun 16:26
Compare
Choose a tag to compare

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

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

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

Read more

v1.10

22 Mar 16:11
Compare
Choose a tag to compare

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

29 Nov 17:09
Compare
Choose a tag to compare

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

23 Aug 15:43
Compare
Choose a tag to compare

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)

v1.7

25 May 16:28
Compare
Choose a tag to compare

Client-Server API

New Endpoints

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

Backwards Compatible Changes

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

14 Feb 15:30
Compare
Choose a tag to compare

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

17 Nov 15:32
Compare
Choose a tag to compare

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

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

29 Sep 13:03
Compare
Choose a tag to compare

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

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)

v1.3

16 Jun 14:33
Compare
Choose a tag to compare

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)
  • [Patch 1] For room versions 2–10: correct a mistaken clarification to the state resolution algorithm. (#1158)

Appendices

No significant changes.