Abstract suggestion: Overall data model documentation

Currently, the specification seems to be defined in a very piecemeal-y manner; each part of the API individually specifies what data it expects, what data it returns, and so on.

This makes it somewhat difficult to build well-architected-upfront homeservers and clients, as you'd have to read pretty much the entire specification to build up a comprehensive (mental) model of the different kinds of 'entities' in a Matrix system, and how they relate to each other.

I'd suggest adding some sort of high-level data model documentation, that describes in a relational manner what kind of different data types (users, messages, access tokens, etc.) exist in a Matrix system, and how they relate to other data types. This would still be an abstract model, leaving it up to applications how to implement and persist it exactly.

For example, the kind of model I'm thinking of might be something like this (represented as text):

User

• username: String
• password: String
• devices: [Device]
• joined_rooms: [Room]

Device

• user: User
• access_token: String
• display_name: String

Room

• name: String
• users: [User]
• messages: [Message]

Message

• body: String
• sender: User
• recipient: User | Room
• parents: [Message]

That's just a simple example, of course (and most likely wrong - I haven't actually read the entire spec yet!), but it hopefully illustrates what I mean. It doesn't necessarily need to be a text representation either, if eg. a visual representation could make it easier to understand.

This data model also wouldn't need to cover 'ephemeral' API data (like eg. the inhibit_login parameter in the /register endpoint), only the persistent data that a developer would need to model into their application architecture.

(This wouldn't have to be part of the specification either, it could act as a non-normative guide separate from it.)

Start by reviewing the Matrix specification and its API descriptions to identify the persistent entities and relationships that should be represented. The issue mentions users, devices, rooms, messages, and access tokens, while excluding ephemeral API data such as /register's inhibit_login parameter. Done means a coherent high-level, non-normative data model guide exists for homeserver and client developers.