Spec refers to EDUs and account data as "events"

[richvdh]

The C-S spec refers to things like m.receipt and m.typing, and various bits of account data as "events". I think this is confusing - it gives the impression that such objects can appear in a room timeline, which is not the case.

[richvdh]

also: the thing that is supposed to make an event an event is that they have a type and a content - and when m.receipt, m.typing and m.presence are sent over federation, they lack a type. (Instead they have an edu_type, cf matrix-org/matrix-spec-proposals#1143)

[jplatte]

Went to the issues today to report the same thing. I actually don't mind m.receipt and m.typing that much (Ruma calls these ephemeral room events) since they're still attached to rooms and immutable like all the other events, they're just not persistent.

What really doesn't make sense to me is global & room-specific account data being referred to as events, since it's also mutable.

[DMRobertson]

I find this infuriating (though that could be PEBCAK).

In a personal notes document I have resorted to the following formalism/rationalisation, which may be of interest.

---

Assume a standard definition of JSON object and related types (lists, strings, integers, booleans, null). When we speak of “JSON objects”, we do so in the abstract without a particular representation in mind. For example, {“a”: 1, “b”: 2} and {“b”:2,“a”:1} are two different textual representations of the same JSON object. When a particular representation is necessary (e.g. for computing hashes), it should be in Canonical JSON form.

Abstract events

The Matrix spec speaks of “events” without ever really defining them. Here is our attempt to clarify the situation.

Definition. An abstract event is triple of three pieces of data:

• its type, a string;
• its content, a JSON object; and
• its metadata, a JSON object.

An event’s type determines the semantics and structure of its content and metadata.

The spec speaks of at least three kinds of abstract events:

• Ephemeral Data Units (EDUs).
  • One-off, non-persistent communication between homeservers.
  • Defined in the Server-Server API spec.
  • No metadata?
  • Represented in JSON as { “edu_type”: TYPE, “content”: CONTENT }
• Account data events. Data scoped to one user, either global or scoped to a room.
  • Defined in the Client-Server API spec.
  • No metadata?
  • Represented in JSON as { “type”: TYPE, “content”: CONTENT }
• Persistent Data Units (PDUs). Persistent communication within a room, stored for the whole of the room’s lifetime.
  • The Client-Server spec seems to call these room events.
  • Defined in a particular room version. The last change was room version 3.
  • Metadata fields are specified by the room’s version. Many are mandatory.
  • Represented in JSON as { “type”: TYPE, “content”: CONTENT, **METADATA }

[jplatte]

Re. EDUs, what events count as that actually? Some or all of these should be:

• Presence, metadata: sender
• Ephemeral room events (m.receipt, m.typing)
• To-device events, metadata: sender

Also, room account data events and ephemeral room events have the room_id as metadata, conceptually? It's just that they're only ever received through /sync where they are grouped by room ID so it can be omitted.

[richvdh]

EDUs are exactly those you list: presence, receipts, typing, to-device. They are listed in https://spec.matrix.org/v1.4/server-server-api, though not in a way that makes them very easy to find.

(Generally I am not a fan of the whole EDU concept: it gives the false impression that there is something in common between those four mechanisms other than the fact they all appear in the edus property in a federation /send request. In reality, each has its own special rules for how servers should handle them. So why don't they just have their own properties in /send?)

EDIT December 2024: There is a fifth EDU type, m.device_list_update

[richvdh]

related: #1241

[turt2live]

So why don't they just have their own properties in /send?

fwiw, crypto appears to do this in places like /sync, and it feels messier than it actually is. Developer perception for them being all the same schema I think would help, but only if they are actually the same sort of thing (beyond an arbitrary heading).