matrix-org / matrix-org/matrix-spec

Clarify what state keys are actually *for*

Open
#491 5 comments 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

A-Client-Server clarification
Dominant language
HTML
Stars
330
Forks
150
Avg merge
2h 21m
Merged PRs (30d)
3

Description

The client-server spec says (emphasis mine):

> State Events: These are events which update the metadata state of the room (e.g. room topic, room membership etc). __State is keyed by a tuple of event type and a state_key. State in the room with the same key-tuple will be overwritten.__

And:

> state_key: Required. A unique key which defines the overwriting semantics for this piece of room state. This value is often a zero-length string. The presence of this key makes this event a State Event. State keys starting with an @ are reserved for referencing user IDs, such as room members. With the exception of a few events, state events set with a given user's ID as the state key MUST only be set by that user.

... which doesn't really clarify what the *purpose* of a state key is - why was the concept introduced into the protocol?

The second snippet says "defines the overwriting semantics", but this is really vague - what is meant with "overwriting semantics", what is the overarching format of the state key (if any), and how does that relate to the apparently different semantics options? Shouldn't it then be an enum, rather than a free-form string? What are the implications of a state key changing, or being omitted?

Basically, the high-level explanation of "what are state keys, why do they exist, why should you care about them" is missing.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the client-server specification sections containing the cited definitions of State Events and state_key. Clarify why state keys exist, how they determine overwriting semantics, whether their format is constrained, and the implications of changing or omitting them.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.