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.
matrix-spec/content/rooms/v3.md

123 lines
4.6 KiB
Markdown

---
title: Room Version 3
type: docs
weight: 30
---
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
<!-- set withVersioning=true so we get all the "new in this version" stuff -->
{{% rver-fragment name="v3-handling-redactions" withVersioning=true %}}
### 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 this=true %}} 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 this=true >}} `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 %}}
<!-- set withVersioning=true so we get all the "new in this version" stuff -->
{{< rver-fragment name="v3-auth-rules" withVersioning=true >}}
## 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" %}}