diff --git a/content/_index.md b/content/_index.md index c7d0acda..69d7883c 100644 --- a/content/_index.md +++ b/content/_index.md @@ -19,19 +19,17 @@ To propose a change to the Matrix Spec, see the explanations at The specification consists of the following parts: -* [Client-Server API](client-server-api) -* [Server-Server API](server-server-api) -* [Application Service API](application-service-api) -* [Identity Service API](identity-service-api) -* [Push Gateway API](push-gateway-api) +* [Client-Server API](/client-server-api) +* [Server-Server API](/server-server-api) +* [Application Service API](/application-service-api) +* [Identity Service API](/identity-service-api) +* [Push Gateway API](/push-gateway-api) +* [Room Versions](/rooms) +* [Appendices](/appendices) Additionally, this introduction page contains the key baseline information required to understand the specific APIs, including the -sections on [room versions](#room-versions) and [overall -architecture](#architecture). - -The [Appendices](/appendices) contain supplemental information not -specific to one of the above APIs. +section the [overall architecture](#architecture). The [Matrix Client-Server API Swagger Viewer](https://matrix.org/docs/api/client-server/) is useful for @@ -426,82 +424,6 @@ Unless otherwise stated, timestamps are measured as milliseconds since the Unix epoch. Throughout the specification this may be referred to as POSIX, Unix, or just "time in milliseconds". -## Room Versions - -Rooms are central to how Matrix operates, and have strict rules for what -is allowed to be contained within them. Rooms can also have various -algorithms that handle different tasks, such as what to do when two or -more events collide in the underlying DAG. To allow rooms to be improved -upon through new algorithms or rules, "room versions" are employed to -manage a set of expectations for each room. New room versions are -assigned as needed. - -There is no implicit ordering or hierarchy to room versions, and their -principles are immutable once placed in the specification. Although -there is a recommended set of versions, some rooms may benefit from -features introduced by other versions. Rooms move between different -versions by "upgrading" to the desired version. Due to versions not -being ordered or hierarchical, this means a room can "upgrade" from -version 2 to version 1, if it is so desired. - -### Room version grammar - -Room versions are used to change properties of rooms that may not be -compatible with other servers. For example, changing the rules for event -authorization would cause older servers to potentially end up in a -split-brain situation due to not understanding the new rules. - -A room version is defined as a string of characters which MUST NOT -exceed 32 codepoints in length. Room versions MUST NOT be empty and -SHOULD contain only the characters `a-z`, `0-9`, `.`, and `-`. - -Room versions are not intended to be parsed and should be treated as -opaque identifiers. Room versions consisting only of the characters -`0-9` and `.` are reserved for future versions of the Matrix protocol. - -The complete grammar for a legal room version is: - - room_version = 1*room_version_char - room_version_char = DIGIT - / %x61-7A ; a-z - / "-" / "." - -Examples of valid room versions are: - -- `1` (would be reserved by the Matrix protocol) -- `1.2` (would be reserved by the Matrix protocol) -- `1.2-beta` -- `com.example.version` - -### Complete list of room versions - -Room versions are divided into two distinct groups: stable and unstable. -Stable room versions may be used by rooms safely. Unstable room versions -are everything else which is either not listed in the specification or -flagged as unstable for some other reason. Versions can switch between -stable and unstable periodically for a variety of reasons, including -discovered security vulnerabilities and age. - -Clients should not ask room administrators to upgrade their rooms if the -room is running a stable version. Servers SHOULD use **room version 6** as -the default room version when creating new rooms. - -The available room versions are: - -- [Version 1](/rooms/v1) - **Stable**. The current version of most - rooms. -- [Version 2](/rooms/v2) - **Stable**. Implements State Resolution - Version 2. -- [Version 3](/rooms/v3) - **Stable**. Introduces events whose IDs - are the event's hash. -- [Version 4](/rooms/v4) - **Stable**. Builds on v3 by using - URL-safe base64 for event IDs. -- [Version 5](/rooms/v5) - **Stable**. Introduces enforcement of - signing key validity periods. -- [Version 6](/rooms/v6) - **Stable**. Alters several - authorization rules for events. -- [Version 7](/rooms/v7) - **Stable**. Introduces knocking. - ## Specification Versions Matrix as a whole is released under a single specification number in the diff --git a/content/appendices.md b/content/appendices.md index ad7c31a1..c622c0e9 100644 --- a/content/appendices.md +++ b/content/appendices.md @@ -384,7 +384,7 @@ the following: ## Identifier Grammar Some identifiers are specific to given room versions, please refer to -the [room versions specification](/#room-versions) for more +the [room versions specification](/rooms) for more information. ### Server Name @@ -599,7 +599,7 @@ A room has exactly one room ID. A room ID has the format: !opaque_id:domain An event has exactly one event ID. The format of an event ID depends -upon the [room version specification](/#room-versions). +upon the [room version specification](/rooms). The `domain` of a room ID is the [server name](#server-name) of the homeserver which created the room/event. The domain is used only for @@ -680,7 +680,7 @@ the client if possible. {{% boxes/note %}} Clients should be aware that decoding a matrix.to URI may result in extra slashes appearing due to some [room -versions](/#room-versions). These slashes should normally be +versions](/rooms). These slashes should normally be encoded when producing matrix.to URIs, however. {{% /boxes/note %}} diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 98bf2be0..5b4cb5d8 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -1200,7 +1200,7 @@ An example of the capability API's response for this capability is: ``` This capability mirrors the same restrictions of [room -versions](../index.html#room-versions) to describe which versions are +versions](/rooms) to describe which versions are stable and unstable. Clients should assume that the `default` version is `stable`. Any version not explicitly labelled as `stable` in the `available` versions is to be treated as `unstable`. For example, a @@ -1290,7 +1290,7 @@ any given point in time: {{% boxes/warning %}} The format of events can change depending on room version. Check the -[room version specification](../index.html#room-versions) for specific +[room version specification](/rooms) for specific details on what to expect for event formats. Examples contained within the client-server specification are expected to be compatible with all specified room versions, however some differences may still apply. @@ -1598,7 +1598,7 @@ content from the databases. Servers should include a copy of the when serving the redacted event to clients. The exact algorithm to apply against an event is defined in the [room -version specification](../index.html#room-versions). +version specification](/rooms). When a client receives an `m.room.redaction` event, it should change the affected event in the same way a server does. @@ -1730,7 +1730,7 @@ This room can only be joined if you were invited. `knock` This room can only be joined if you were invited, and allows anyone to request an invite to the room. Note that this join rule is only available -to rooms based upon [room version 7](/rooms/v7). +in room versions [which support knocking](/rooms/#feature-matrix). The allowable state transitions of membership are: diff --git a/content/rooms/_index.md b/content/rooms/_index.md index 80c688a2..04ded252 100644 --- a/content/rooms/_index.md +++ b/content/rooms/_index.md @@ -4,10 +4,96 @@ type: docs weight: 60 --- -* [Room Version 1](v1) -* [Room Version 2](v2) -* [Room Version 3](v3) -* [Room Version 4](v4) -* [Room Version 5](v5) -* [Room Version 6](v6) -* [Room Version 7](v7) +Rooms are central to how Matrix operates, and have strict rules for what +is allowed to be contained within them. Rooms can also have various +algorithms that handle different tasks, such as what to do when two or +more events collide in the underlying DAG. To allow rooms to be improved +upon through new algorithms or rules, "room versions" are employed to +manage a set of expectations for each room. New room versions are +assigned as needed. + +There is no implicit ordering or hierarchy to room versions, and their +principles are immutable once placed in the specification. Although +there is a recommended set of versions, some rooms may benefit from +features introduced by other versions. Rooms move between different +versions by "upgrading" to the desired version. Due to versions not +being ordered or hierarchical, this means a room can "upgrade" from +version 2 to version 1, if it is so desired. + +## Feature matrix + +Some functionality is only available in specific room versions, such +as knocking. The table below shows which versions support which features +from a client's perspective. Server implementation are still welcome +to reference the following table, however the detailed per-version +specifications are more likely to be of interest. + + + +| Feature \ Version | 1 | 2 | 3 | 4 | 5 | 6 | 7 | +|-------------------|---|---|---|---|---|---|---| +| **Knocking** | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✔ | + +## Complete list of room versions + +Room versions are divided into two distinct groups: stable and unstable. +Stable room versions may be used by rooms safely. Unstable room versions +are everything else which is either not listed in the specification or +flagged as unstable for some other reason. Versions can switch between +stable and unstable periodically for a variety of reasons, including +discovered security vulnerabilities and age. + +Clients should not ask room administrators to upgrade their rooms if the +room is running a stable version. Servers SHOULD use **room version 6** as +the default room version when creating new rooms. + +The available room versions are: + +- [Version 1](/rooms/v1) - **Stable**. The current version of most + rooms. +- [Version 2](/rooms/v2) - **Stable**. Implements State Resolution + Version 2. +- [Version 3](/rooms/v3) - **Stable**. Introduces events whose IDs + are the event's hash. +- [Version 4](/rooms/v4) - **Stable**. Builds on v3 by using + URL-safe base64 for event IDs. +- [Version 5](/rooms/v5) - **Stable**. Introduces enforcement of + signing key validity periods. +- [Version 6](/rooms/v6) - **Stable**. Alters several + authorization rules for events. +- [Version 7](/rooms/v7) - **Stable**. Introduces knocking. + +## Room version grammar + +Room versions are used to change properties of rooms that may not be +compatible with other servers. For example, changing the rules for event +authorization would cause older servers to potentially end up in a +split-brain situation due to not understanding the new rules. + +A room version is defined as a string of characters which MUST NOT +exceed 32 codepoints in length. Room versions MUST NOT be empty and +SHOULD contain only the characters `a-z`, `0-9`, `.`, and `-`. + +Room versions are not intended to be parsed and should be treated as +opaque identifiers. Room versions consisting only of the characters +`0-9` and `.` are reserved for future versions of the Matrix protocol. + +The complete grammar for a legal room version is: + + room_version = 1*room_version_char + room_version_char = DIGIT + / %x61-7A ; a-z + / "-" / "." + +Examples of valid room versions are: + +- `1` (would be reserved by the Matrix protocol) +- `1.2` (would be reserved by the Matrix protocol) +- `1.2-beta` +- `com.example.version` \ No newline at end of file diff --git a/content/server-server-api.md b/content/server-server-api.md index 9c6552ab..f916c212 100644 --- a/content/server-server-api.md +++ b/content/server-server-api.md @@ -348,7 +348,7 @@ a child: E4 For a full schema of what a PDU looks like, see the [room version -specification](../index.html#room-versions). +specification](/rooms). ### Checks performed on receipt of a PDU @@ -398,7 +398,7 @@ state. A given event is checked multiple times against different sets of state, as specified above. Each room version can have a different algorithm for how the rules work, and which rules are applied. For more detailed information, please see the [room version -specification](../index.html#room-versions). +specification](/rooms). ##### Auth events selection @@ -609,7 +609,7 @@ the room. What should the name of the room be at E5? The algorithm to be used for state resolution depends on the room version. For a description of each room version's algorithm, please see -the [room version specification](/#room-versions). +the [room version specification](/rooms). ## Backfilling and retrieving missing events @@ -1111,7 +1111,7 @@ the full copy it received. The *reference hash* of an event covers the essential fields of an event, including content hashes. It is used for event identifiers in some room versions. See the [room version -specification](/#room-versions) for more information. It is +specification](/rooms) for more information. It is calculated as follows. 1. The event is put through the redaction algorithm. diff --git a/data/api/server-server/backfill.yaml b/data/api/server-server/backfill.yaml index 42a0e3bd..6adeb26c 100644 --- a/data/api/server-server/backfill.yaml +++ b/data/api/server-server/backfill.yaml @@ -130,7 +130,7 @@ paths: type: array description: |- The missing events. The event format varies depending on the room version - check - the [room version specification](/#room-versions) for precise event formats. + the [room version specification](/rooms) for precise event formats. items: type: object title: PDU diff --git a/data/api/server-server/definitions/invite_event.yaml b/data/api/server-server/definitions/invite_event.yaml index 416eb709..439a6833 100644 --- a/data/api/server-server/definitions/invite_event.yaml +++ b/data/api/server-server/definitions/invite_event.yaml @@ -15,7 +15,7 @@ type: object title: InviteEvent description: |- An invite event. Note that events have a different format depending on the - room version - check the [room version specification](/#room-versions) for precise event formats. + room version - check the [room version specification](/rooms) for precise event formats. allOf: - type: object properties: diff --git a/data/api/server-server/definitions/keys.yaml b/data/api/server-server/definitions/keys.yaml index 3676ae52..135e81ac 100644 --- a/data/api/server-server/definitions/keys.yaml +++ b/data/api/server-server/definitions/keys.yaml @@ -90,7 +90,7 @@ properties: description: |- POSIX timestamp when the list of valid keys should be refreshed. This field MUST be ignored in room versions 1, 2, 3, and 4. Keys used beyond this timestamp MUST - be considered invalid, depending on the [room version specification](/#room-versions). + be considered invalid, depending on the [room version specification](/rooms). Servers MUST use the lesser of this field and 7 days into the future when determining if a key is valid. This is to avoid a situation where an attacker diff --git a/data/api/server-server/definitions/send_join_response.yaml b/data/api/server-server/definitions/send_join_response.yaml index 0aad1758..cfa37910 100644 --- a/data/api/server-server/definitions/send_join_response.yaml +++ b/data/api/server-server/definitions/send_join_response.yaml @@ -25,13 +25,13 @@ properties: The auth chain for the entire current room state prior to the join event. Note that events have a different format depending on the room version - check the - [room version specification](/#room-versions) for precise event formats. + [room version specification](/rooms) for precise event formats. items: type: object title: PDU description: |- The [PDUs](/server-server-api/#pdus) that make up the auth chain. The event format varies depending - on the room version - check the [room version specification](/#room-versions) for precise event formats. + on the room version - check the [room version specification](/rooms) for precise event formats. schema: type: object properties: [] @@ -42,14 +42,14 @@ properties: description: |- The resolved current room state prior to the join event. - The event format varies depending on the room version - check the [room version specification](/#room-versions) + The event format varies depending on the room version - check the [room version specification](/rooms) for precise event formats. items: type: object title: PDU description: |- The [PDUs](/server-server-api/#pdus) for the fully resolved state of the room. The event format varies depending - on the room version - check the [room version specification](/#room-versions) for precise event formats. + on the room version - check the [room version specification](/rooms) for precise event formats. schema: type: object properties: [] diff --git a/data/api/server-server/definitions/single_pdu_transaction.yaml b/data/api/server-server/definitions/single_pdu_transaction.yaml index 3c406e8f..cb6750da 100644 --- a/data/api/server-server/definitions/single_pdu_transaction.yaml +++ b/data/api/server-server/definitions/single_pdu_transaction.yaml @@ -19,13 +19,13 @@ properties: type: array description: |- A single PDU. Note that events have a different format depending on the room - version - check the [room version specification](/#room-versions) for precise event formats. + version - check the [room version specification](/rooms) for precise event formats. items: type: object title: PDU description: |- The [PDUs](/server-server-api/#pdus) contained in the transaction. The event format varies depending - on the room version - check the [room version specification](/#room-versions) for precise event formats. + on the room version - check the [room version specification](/rooms) for precise event formats. properties: [] example: $ref: "../examples/minimal_pdu.json" diff --git a/data/api/server-server/definitions/transaction.yaml b/data/api/server-server/definitions/transaction.yaml index 4d9f3ae4..1e33ef5c 100644 --- a/data/api/server-server/definitions/transaction.yaml +++ b/data/api/server-server/definitions/transaction.yaml @@ -34,13 +34,13 @@ properties: description: |- List of persistent updates to rooms. Must not include more than 50 PDUs. Note that events have a different format depending on the room version - check the - [room version specification](/#room-versions) for precise event formats. + [room version specification](/rooms) for precise event formats. items: type: object title: PDU description: |- The [PDUs](/server-server-api/#pdus) contained in the transaction. The event format varies depending - on the room version - check the [room version specification](/#room-versions) for precise event formats. + on the room version - check the [room version specification](/rooms) for precise event formats. properties: [] example: $ref: "../examples/minimal_pdu.json" diff --git a/data/api/server-server/definitions/unlimited_pdu_transaction.yaml b/data/api/server-server/definitions/unlimited_pdu_transaction.yaml index bfa29609..6e777671 100644 --- a/data/api/server-server/definitions/unlimited_pdu_transaction.yaml +++ b/data/api/server-server/definitions/unlimited_pdu_transaction.yaml @@ -19,14 +19,14 @@ properties: type: array description: |- List of persistent updates to rooms. Note that events have a different format - depending on the room version - check the [room version specification](/#room-versions) for + depending on the room version - check the [room version specification](/rooms) for precise event formats. items: type: object title: PDU description: |- The [PDUs](/server-server-api/#pdus) contained in the transaction. The event format varies depending - on the room version - check the [room version specification](/#room-versions) for precise event formats. + on the room version - check the [room version specification](/rooms) for precise event formats. properties: [] example: $ref: "../examples/minimal_pdu.json" diff --git a/data/api/server-server/event_auth.yaml b/data/api/server-server/event_auth.yaml index 0d9fdec1..26cdd95a 100644 --- a/data/api/server-server/event_auth.yaml +++ b/data/api/server-server/event_auth.yaml @@ -60,13 +60,13 @@ paths: The full set of authorization events that make up the state of the room, and their authorization events, recursively. Note that events have a different format depending on the room version - - check the [room version specification](/#room-versions) for precise event formats. + check the [room version specification](/rooms) for precise event formats. items: type: object title: PDU description: |- The [PDUs](/server-server-api/#pdus) contained in the auth chain. The event format - varies depending on the room version - check the [room version specification](/#room-versions) + varies depending on the room version - check the [room version specification](/rooms) for precise event formats. properties: [] example: diff --git a/data/api/server-server/events.yaml b/data/api/server-server/events.yaml index 51405d1c..823c6da6 100644 --- a/data/api/server-server/events.yaml +++ b/data/api/server-server/events.yaml @@ -61,13 +61,13 @@ paths: The full set of authorization events that make up the state of the room, and their authorization events, recursively. Note that events have a different format depending on the room version - - check the [room version specification](/#room-versions) for precise event formats. + check the [room version specification](/rooms) for precise event formats. items: type: object title: PDU description: |- The [PDUs](/server-server-api/#pdus) contained in the auth chain. The event format - varies depending on the room version - check the [room version specification](/#room-versions) + varies depending on the room version - check the [room version specification](/rooms) for precise event formats. properties: [] example: @@ -77,13 +77,13 @@ paths: description: |- The fully resolved state of the room at the given event. Note that events have a different format depending on the room version - - check the [room version specification](/#room-versions) for precise event formats. + check the [room version specification](/rooms) for precise event formats. items: type: object title: PDU description: |- The [PDUs](/server-server-api/#pdus) for the fully resolved state of the room. The event format - varies depending on the room version - check the [room version specification](/#room-versions) + varies depending on the room version - check the [room version specification](/rooms) for precise event formats. properties: [] example: diff --git a/data/api/server-server/invites-v1.yaml b/data/api/server-server/invites-v1.yaml index 4925221f..14f1665a 100644 --- a/data/api/server-server/invites-v1.yaml +++ b/data/api/server-server/invites-v1.yaml @@ -40,7 +40,7 @@ paths: or `"2"`. Note that events have a different format depending on the room version - check the - [room version specification](/#room-versions) for precise event formats. **The request and response + [room version specification](/rooms) for precise event formats. **The request and response bodies here describe the common event fields in more detail and may be missing other required fields for a PDU.** operationId: sendInviteV1 @@ -106,7 +106,7 @@ paths: description: |- The event with the invited server's signature added. All other fields of the events should remain untouched. Note that events have a different format depending on the - room version - check the [room version specification](/#room-versions) for precise event formats. + room version - check the [room version specification](/rooms) for precise event formats. schema: type: array minItems: 2 diff --git a/data/api/server-server/invites-v2.yaml b/data/api/server-server/invites-v2.yaml index 039a9e65..8296bb8b 100644 --- a/data/api/server-server/invites-v2.yaml +++ b/data/api/server-server/invites-v2.yaml @@ -44,7 +44,7 @@ paths: API as the server may be older, if the room version is "1" or "2". Note that events have a different format depending on the room version - check the - [room version specification](/#room-versions) for precise event formats. **The request and response + [room version specification](/rooms) for precise event formats. **The request and response bodies here describe the common event fields in more detail and may be missing other required fields for a PDU.** operationId: sendInviteV2 @@ -111,7 +111,7 @@ paths: description: |- The event with the invited server's signature added. All other fields of the events should remain untouched. Note that events have a different format depending on the - room version - check the [room version specification](/#room-versions) for precise event formats. + room version - check the [room version specification](/rooms) for precise event formats. schema: type: object description: An object containing the signed invite event. diff --git a/data/api/server-server/joins-v1.yaml b/data/api/server-server/joins-v1.yaml index 696ca533..adf7298b 100644 --- a/data/api/server-server/joins-v1.yaml +++ b/data/api/server-server/joins-v1.yaml @@ -64,7 +64,7 @@ paths: description: |- A template to be used for the rest of the [Joining Rooms](/server-server-api/#joining-rooms) handshake. Note that events have a different format depending on the room version - check the - [room version specification](/#room-versions) for precise event formats. **The response body + [room version specification](/rooms) for precise event formats. **The response body here describes the common event fields in more detail and may be missing other required fields for a PDU.** schema: @@ -79,7 +79,7 @@ paths: event: description: |- An unsigned template event. Note that events have a different format - depending on the room version - check the [room version specification](/#room-versions) + depending on the room version - check the [room version specification](/rooms) for precise event formats. type: object title: Event Template @@ -182,7 +182,7 @@ paths: Submits a signed join event to the resident server for it to accept it into the room's graph. Note that events have a different format depending on the room version - check - the [room version specification](/#room-versions) for precise event formats. + the [room version specification](/rooms) for precise event formats. **The request and response body here describe the common event fields in more detail and may be missing other required fields for a PDU.** diff --git a/data/api/server-server/joins-v2.yaml b/data/api/server-server/joins-v2.yaml index de5c5711..b3ade854 100644 --- a/data/api/server-server/joins-v2.yaml +++ b/data/api/server-server/joins-v2.yaml @@ -45,7 +45,7 @@ paths: Submits a signed join event to the resident server for it to accept it into the room's graph. Note that events have a different format depending on the room version - check - the [room version specification](/#room-versions) for precise event formats. + the [room version specification](/rooms) for precise event formats. **The request and response body here describe the common event fields in more detail and may be missing other required fields for a PDU.** diff --git a/data/api/server-server/knocks.yaml b/data/api/server-server/knocks.yaml index 945362a1..063c3f3b 100644 --- a/data/api/server-server/knocks.yaml +++ b/data/api/server-server/knocks.yaml @@ -63,7 +63,7 @@ paths: description: |- A template to be used for the rest of the [Knocking Rooms](/server-server-api/#knocking-rooms) handshake. Note that events have a different format depending on room version - check the - [room version specification](/#room-versions) for precise event formats. **The response body + [room version specification](/rooms) for precise event formats. **The response body here describes the common event fields in more detail and may be missing other required fields for a PDU.** schema: @@ -77,7 +77,7 @@ paths: event: description: |- An unsigned template event. Note that events have a different format - depending on the room version - check the [room version specification](/#room-versions) + depending on the room version - check the [room version specification](/rooms) for precise event formats. type: object title: Event Template @@ -195,7 +195,7 @@ paths: Submits a signed knock event to the resident server for it to accept into the room's graph. Note that events have a different format depending on the room version - check - the [room version specification](/#room-versions) for precise event formats. + the [room version specification](/rooms) for precise event formats. **The request and response body here describe the common event fields in more detail and may be missing other required fields for a PDU.** diff --git a/data/api/server-server/leaving-v1.yaml b/data/api/server-server/leaving-v1.yaml index ce96ab4a..df314d5a 100644 --- a/data/api/server-server/leaving-v1.yaml +++ b/data/api/server-server/leaving-v1.yaml @@ -55,7 +55,7 @@ paths: description: |- A template to be used to call `/send_leave`. Note that events have a different format depending on the room version - check the - [room version specification](/#room-versions) for precise event formats. **The response body + [room version specification](/rooms) for precise event formats. **The response body here describes the common event fields in more detail and may be missing other required fields for a PDU.** schema: @@ -70,7 +70,7 @@ paths: event: description: |- An unsigned template event. Note that events have a different format - depending on the room version - check the [room version specification](/#room-versions) + depending on the room version - check the [room version specification](/rooms) for precise event formats. type: object title: Event Template @@ -149,7 +149,7 @@ paths: Submits a signed leave event to the resident server for it to accept it into the room's graph. Note that events have a different format depending on the room version - check - the [room version specification](/#room-versions) for precise event formats. + the [room version specification](/rooms) for precise event formats. **The request and response body here describe the common event fields in more detail and may be missing other required fields for a PDU.** diff --git a/data/api/server-server/leaving-v2.yaml b/data/api/server-server/leaving-v2.yaml index 28a41759..e3b8f089 100644 --- a/data/api/server-server/leaving-v2.yaml +++ b/data/api/server-server/leaving-v2.yaml @@ -45,7 +45,7 @@ paths: Submits a signed leave event to the resident server for it to accept it into the room's graph. Note that events have a different format depending on the room version - check - the [room version specification](/#room-versions) for precise event formats. + the [room version specification](/rooms) for precise event formats. **The request and response body here describe the common event fields in more detail and may be missing other required fields for a PDU.** diff --git a/data/api/server-server/transactions.yaml b/data/api/server-server/transactions.yaml index 15b3ee36..46dd17af 100644 --- a/data/api/server-server/transactions.yaml +++ b/data/api/server-server/transactions.yaml @@ -39,7 +39,7 @@ paths: transaction with a different `txnId` to the receiving server. Note that events have a different format depending on the room version - check - the [room version specification](/#room-versions) for precise event formats. + the [room version specification](/rooms) for precise event formats. operationId: sendTransaction security: - signedRequest: [] diff --git a/proposals/2324-when-to-ship.md b/proposals/2324-when-to-ship.md index 1335bfab..47ed5247 100644 --- a/proposals/2324-when-to-ship.md +++ b/proposals/2324-when-to-ship.md @@ -93,7 +93,7 @@ should be followed where possible, if implementations decide to work ahead of sp #### Room versions When a new room version is needed, implementations MUST use vendor-prefixed versions -before using the namespace reserved for Matrix (see https://matrix.org/docs/spec/#room-versions). +before using the namespace reserved for Matrix (see https://spec.matrix.org/unstable/rooms/). A room version is considered released once it is listed as an "available room version" in the spec. Often a new room version is accompanied with a server-server API release, but doesn't have to be. diff --git a/proposals/2801-untrusted-event-data.md b/proposals/2801-untrusted-event-data.md index 2b0d16aa..2c4f3763 100644 --- a/proposals/2801-untrusted-event-data.md +++ b/proposals/2801-untrusted-event-data.md @@ -113,10 +113,9 @@ room state can begin to drift, and the room can eventually become not form part of the room state": we have a risk that some servers will accept the event, and some will not. -One approach to solving this is via [room -versions](https://matrix.org/docs/spec/index#room-versions). By specifying that -a change of rules only applies for a future room version, we can eliminate this -potential disagreement. +One approach to solving this is via [room versions](https://spec.matrix.org/unstable/rooms/). +By specifying that a change of rules only applies for a future room version, +we can eliminate this potential disagreement. The process of changing a room from one version to another is intrusive, not least because it requires that all servers in a room support the new room diff --git a/proposals/2844-global-versioning.md b/proposals/2844-global-versioning.md index b6db20c1..ce4b299d 100644 --- a/proposals/2844-global-versioning.md +++ b/proposals/2844-global-versioning.md @@ -8,7 +8,7 @@ which apply: that the client-server API currently ties the major version of its spec document version to the endpoint, thus making most endpoints under it `/r0/` (currently). 3. Room versions which define a set of behaviour and algorithms on a per-room basis. These are well - defined in the spec and are not covered here: https://matrix.org/docs/spec/#room-versions + defined in the spec and are not covered here: https://spec.matrix.org/unstable/rooms/ 4. An overarching "Matrix" version, largely for marketing purposes. So far we've only cut Matrix 1.0 back when we finalized the initial versions of the spec documents, but have not cut another one since.