Comparison of Matrix events before and after “Extensible Events”

[Updated 2022-11-17 based on the new draft of the MSC, notably removing backwards compatibility and the abbreviated forms.]

(Background: Matrix is the awesome open standard for messaging that I get to work on now that I work at Element.)

The Extensible Events (MSC1767) Matrix Spec Change proposal describes a new way of structuring events in matrix that makes it easy to send events that have multiple representations (e.g. something clever like an interactive map, and something simpler like an image of a map).

The change has 2 main purposes:

1. To make it easy for clients that don’t support some amazing new feature to display something that is still useful.
2. To allow re-using the definitions of parts of events in other events.

Since there is an implementation of this change out in the wild (in Element), it seems reasonably likely that this change will be accepted into the Matrix spec.

I really like this change, but I find it hard to understand, so here is a simple example that I have found helpful to think it through.

An old event, and a new event

Here is an old-fashioned event, followed by a new, shiny, extensible version:

{
    "type": "m.room.message",
    "content": {
        "body": "This is the *old* way",
        "format": "org.matrix.custom.html",
        "formatted_body": "This is the <b>old</b> way",
        "msgtype": "m.text"
    },
    ... other properties not relevant to this, e.g. "sender" ...
}

{
    "type": "m.message",
    "content": {
        "m.markup": [
            {"mimetype": "text/plain", "body": "This the *new* way"},
            {"mimetype": "text/html", "body": "This is the <b>new</b> way"}
        ],
    }
    ... other properties not relevant to this, e.g. "sender" ...
}

The point is that as well as normal contents of the message (here, the m.markup “content block”) we can have other representations of the same message, such as an image, location co-ordinates, or something completely different. The client will render using the content blocks it expects if it knows about this event type (and is able to show it), but if not, it can look for other content blocks that it does understand.

For example, in Polls when you send a new poll question, it could look like this:

{
    "type": "m.poll.start",
    "content": {
        "m.poll": {
            ... The actual poll question etc. ...
        },
        "m.markup": [
            ... A text version of the question ...
        ]
    },
    ... other properties not relevant to this, e.g. "sender" ...
}

So clients that don’t know m.poll.start can still display the poll question (if they understand extensible events), instead of completely ignoring event types they don’t know about.

Notice that sometimes content blocks (inside content) can have the same name as the event type, but they don’t have to.