matrix-org / matrix-org/matrix-spec
Move definitions of event and account_data schemas out of the C-S spec
Nobody has claimed this yet.
- Dominant language
- HTML
- Stars
- 330
- Forks
- 150
- Avg merge
- 2h 21m
- Merged PRs (30d)
- 3
Description
The client-server spec contains definitions of many different event types, scattered throughout the document:
* https://spec.matrix.org/unstable/client-server-api/#room-events
* https://spec.matrix.org/unstable/client-server-api/#events-1
* https://spec.matrix.org/unstable/client-server-api/#events-2
* https://spec.matrix.org/unstable/client-server-api/#events-3
* https://spec.matrix.org/unstable/client-server-api/#events-8
* https://spec.matrix.org/unstable/client-server-api/#events-9
* https://spec.matrix.org/unstable/client-server-api/#events-10
* https://spec.matrix.org/unstable/client-server-api/#events-11
* https://spec.matrix.org/unstable/client-server-api/#events-16
* https://spec.matrix.org/unstable/client-server-api/#events-17
* https://spec.matrix.org/unstable/client-server-api/#events-18
* https://spec.matrix.org/unstable/client-server-api/#events-19
* (and probably others)
I think it's confusing that we conflate the mechanism for sending and receiving events (the C-S API) with the events that can be sent. Furthermore:
* In most cases servers don't actually care about the events at all.
* These event definitions are a significant part of the length of the C-S spec, and their inclusion there makes it hard to understand and navigate the C-S spec
* It's also hard to find the definition of a given event type.
* This is less of an argument now than it used to be, thanks to [MSC2844](https://github.com/matrix-org/matrix-doc/pull/2844), but adding new event types shouldn't need changes to the C-S spec.
I think we could also make a similar argument for account data types (https://spec.matrix.org/unstable/client-server-api/#midentity_server, https://spec.matrix.org/unstable/client-server-api/#events-6, https://spec.matrix.org/unstable/client-server-api/#key-storage, https://spec.matrix.org/unstable/client-server-api/#events-14, etc).
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reviewing the client-server API sections linked in the issue, including Room Events, Events 1–3 and 8–19, plus the linked account-data sections and MSC2844. Define a separate location for event and account-data schemas while preserving the C-S API's event transport documentation; done means the definitions are no longer scattered through the C-S spec and remain discoverable.
Written by the indexing model from the issue text.
Assessment
- Domain
- api, documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 35/100