You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
122 lines
4.4 KiB
Markdown
122 lines
4.4 KiB
Markdown
---
|
|
title: Room Version 3
|
|
type: docs
|
|
weight: 30
|
|
version: 3
|
|
---
|
|
|
|
This room version builds on [version 2](/rooms/v2) with an improved event
|
|
format.
|
|
|
|
## Client considerations
|
|
|
|
This room version changes the format for event IDs sent to clients.
|
|
Clients should be aware that these event IDs may contain slashes and
|
|
other potentially problematic characters. Clients should be treating
|
|
event IDs as opaque identifiers and should not be attempting to parse
|
|
them into a usable form, just like with other room versions.
|
|
|
|
Clients should expect to see event IDs changed from the format of
|
|
`$randomstring:example.org` to something like
|
|
`$acR1l0raoZnm60CBwAVgqbZqoO/mYU81xysh1u7XcJk` (note the lack of domain
|
|
and the potentially problematic slash).
|
|
|
|
Though unchanged in this room version, clients which implement the
|
|
redaction algorithm locally should refer to the [redactions](#redactions)
|
|
section below for a full overview.
|
|
|
|
## Server implementation components
|
|
|
|
{{% boxes/warning %}}
|
|
The information contained in this section is strictly for server
|
|
implementors. Applications which use the Client-Server API are generally
|
|
unaffected by the intricacies contained here. The section above
|
|
regarding client considerations is the resource that Client-Server API
|
|
use cases should reference.
|
|
{{% /boxes/warning %}}
|
|
|
|
Room version 3 uses the event format described here in addition to
|
|
all the remaining behaviour described by [room version 2](/rooms/v2).
|
|
|
|
### Handling redactions
|
|
|
|
{{% rver-fragment name="v3-handling-redactions" %}}
|
|
|
|
### Event IDs
|
|
|
|
{{% boxes/rationale %}}
|
|
In other room versions (namely version 1 and 2) the event ID is a
|
|
distinct field from the remainder of the event, which must be tracked as
|
|
such. This leads to complications where servers receive multiple events
|
|
with the same ID in either the same or different rooms where the server
|
|
cannot easily keep track of which event it should be using. By removing
|
|
the use of a dedicated event ID, servers are required to track the
|
|
hashes on an event to determine its ID.
|
|
{{% /boxes/rationale %}}
|
|
|
|
{{% added-in v=3 %}} The event ID is the [reference
|
|
hash](/server-server-api#calculating-the-reference-hash-for-an-event) of
|
|
the event encoded using [Unpadded
|
|
Base64](/appendices#unpadded-base64), prefixed with `$`. A
|
|
resulting event ID using this approach should look similar to
|
|
`$CD66HAED5npg6074c6pDtLKalHjVfYb2q4Q3LZgrW6o`.
|
|
|
|
### Event format
|
|
|
|
When events are sent over federation, the `event_id` field is no longer
|
|
included. A server receiving an event should compute the relevant
|
|
event ID for itself.
|
|
|
|
Additionally, the format of the `auth_events` and `prev_events` fields are
|
|
changed: instead of lists of `(event_id, hash)` pairs, they are now plain lists
|
|
of event IDs.
|
|
|
|
These changes to the format of an event mean that servers must be aware of the
|
|
version of the room containing an incoming event, so that the event can be
|
|
correctly parsed and handled. This is facilitated via changes to the
|
|
server-server API (such as the inclusion of `room_version` in the response to
|
|
[`GET /_matrix/federation/v1/make_join/{roomId}/{userId}`](/server-server-api/#get_matrixfederationv1make_joinroomiduserid).)
|
|
|
|
The complete structure of a event in a v3 room is shown below.
|
|
|
|
{{% definition path="api/server-server/definitions/pdu_v3" %}}
|
|
|
|
#### Deprecated event content schemas
|
|
|
|
{{% rver-fragment name="v1-deprecated-formatting-off-spec" %}}
|
|
|
|
{{% rver-fragment name="v1-stringy-power-levels" %}}
|
|
|
|
### Authorization rules
|
|
|
|
{{% boxes/note %}}
|
|
{{< added-in v=3 >}} `m.room.redaction` events are subject to auth rules in
|
|
the same way as any other event. In practice, that means they will normally be allowed
|
|
by the auth rules, unless the `m.room.power_levels` event sets a power level requirement
|
|
for `m.room.redaction`events via the `events` or `events_default` properties. In
|
|
particular, the _redact level_ is **not** considered by the auth rules.
|
|
|
|
The ability to send a redaction event does not mean that the redaction itself should
|
|
be performed. Receiving servers must perform additional checks, as described in
|
|
the [Handling Redactions](#handling-redactions) section.
|
|
{{% /boxes/note %}}
|
|
|
|
{{% rver-fragment name="v3-auth-rules" %}}
|
|
|
|
## Unchanged from v2
|
|
|
|
The following sections have not been modified since v2, but are included for
|
|
completeness.
|
|
|
|
### Redactions
|
|
|
|
{{% rver-fragment name="v1-redactions" %}}
|
|
|
|
### State resolution
|
|
|
|
{{% rver-fragment name="v2-state-res" %}}
|
|
|
|
### Canonical JSON
|
|
|
|
{{% rver-fragment name="v1-canonical-json" %}}
|