Skip to content

Specification for MSC4311: Create event availability in stripped state #2207

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 9 commits into from
Sep 12, 2025
Merged

Specification for MSC4311: Create event availability in stripped state #2207

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
a07f2d0
Part 1: Invites
turt2live Sep 8, 2025
1692d22
Part 2: Knocks
turt2live Sep 8, 2025
8ce5903
Use correct schema and examples; Remind readers often about formats
turt2live Sep 8, 2025
c3107d4
changelogs
turt2live Sep 8, 2025
c231d6f
Add schema warning
turt2live Sep 9, 2025
430cbd6
Name the objects
turt2live Sep 9, 2025
a678f0b
Move changed-in and expand upon it
turt2live Sep 12, 2025
86358e7
Rename the example
turt2live Sep 12, 2025
f9e573f
address review feedback
turt2live Sep 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelogs/client_server/newsfragments/2207.feature
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Invites and knocks are now expected to contain the `m.room.create` event in their stripped state entries, as per [MSC4311](https://github.com/matrix-org/matrix-spec-proposals/pull/4311).
1 change: 1 addition & 0 deletions changelogs/server_server/newsfragments/2207.feature
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
`invite_room_state` and `knock_room_state` now have additional requirements and validation depending on the room version, as per [MSC4311](https://github.com/matrix-org/matrix-spec-proposals/pull/4311).
2 changes: 1 addition & 1 deletion content/client-server-api/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2810,7 +2810,7 @@ fresh state can be acquired from a join.
Stripped state should contain some or all of the following state events, which
should be represented as stripped state events when possible:

* [`m.room.create`](#mroomcreate)
* [`m.room.create`](#mroomcreate) ({{% changed-in v="1.16" %}} required on invites and knocks)
* [`m.room.name`](#mroomname)
* [`m.room.avatar`](#mroomavatar)
* [`m.room.topic`](#mroomtopic)
Expand Down
12 changes: 12 additions & 0 deletions content/server-server-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -945,6 +945,18 @@ Note that invites are used to indicate that knocks were accepted. As such,
receiving servers should be prepared to manually link up a previous knock
to an invite if the invite event does not directly reference the knock.

{{% boxes/note %}}
{{% added-in v="1.16" %}} `invite_room_state` MUST now have its entries formatted
according to the room's version (see [room version specification](/rooms)). However,
servers SHOULD consider their local ecosystems before returning the described
`400 M_MISSING_PARAM` error code. While migrating, servers SHOULD warn about
invites which fail the validation rather than error in room versions 1 through 11.
All invites to other room versions which fail validation SHOULD result in an error.

The specification suggests that servers finish their migration no later than
January 2026, though servers may extend this as required to support their users.
{{% /boxes/note %}}

{{% http-api spec="server-server" api="invites-v1" %}}

{{% http-api spec="server-server" api="invites-v2" %}}
Expand Down
9 changes: 9 additions & 0 deletions data/api/server-server/examples/stripped_state.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
[
{"$ref": "./minimal_pdu.json"},
{
"type": "m.room.create",
"content": {
"see_room_version_spec": "The event format changes depending on the room version."
}
}
]
76 changes: 54 additions & 22 deletions data/api/server-server/invites-v1.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -71,13 +71,33 @@ paths:
properties:
invite_room_state:
type: array
x-changedInMatrixVersion:
"1.16": |
`m.room.create` and format requirements were added.
Comment on lines +74 to +76
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(I am belatedly wishing that we had just deprecated /v1/invite and mandated that everyone uses /v2, rather than adding more changes to /v1.)

Do you think it's worth trying to do some $ref trickery to reduce the duplication in the yaml, at least?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've been bitten by $ref not working in weird and unpredictable ways in the past, so I'm incentivized to copy/paste. The endpoints are also slightly different in error responses, which makes it especially annoying.

If given a choice, I'd rather not fight $ref more than I already have to.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that @zecakeh has done a bunch of work to make $ref work better, so it might be worth taking another look.

The endpoints are also slightly different in error responses, which makes it especially annoying.

Ok, but you don't have to duplicate the whole endpoint -- you can just share some parameter type definitions, for example.

I'm really not a big fan of having two copies of all this stuff - it makes it much harder to maintain and review. Doing this review was particularly annoying because I kept getting confused about which bits I'd seen and which I hadn't. Making the job harder for the reviewer to save a bit of authoring time is not a great investment.

I'll not insist on it this time around though.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The concern with the error responses is that it's harder to deduplicate that part is all - the request parameters can be deduplicated, but that's only so helpful.

I'll experiment with $ref separate from this, and open a PR if it works.

description: |-
An optional list of [stripped state events](/client-server-api/#stripped-state)
to help the receiver of the invite identify the room.
A list of state events to help the receiver of the invite identify the room.
Translated as [stripped state events](/client-server-api/#stripped-state)
over the Client-Server API.

MUST contain the `m.room.create` event for the room. All events listed
MUST additionally be formatted according to the room version specification.

Servers might need to apply validation to the `invite_room_state` depending
on room version. See the `400 M_MISSING_PARAM` error definition for more
information.

Note that events have a different format depending on the room
version - check the [room version specification](/rooms) for
precise event formats.
items:
$ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml
type: object
properties: {}
description: |-
Note that events have a different format depending on the room
version - check the [room version specification](/rooms) for
precise event formats.
example:
$ref: ../../event-schemas/examples/invite_room_state.json
$ref: ./examples/stripped_state.json
type: object
required: true
responses:
Expand Down Expand Up @@ -118,24 +138,7 @@ paths:
"origin_server_ts": 1549041175876,
"sender": "@someone:example.org",
"unsigned": {
"invite_room_state": [
{
"type": "m.room.name",
"sender": "@bob:example.org",
"state_key": "",
"content": {
"name": "Example Room"
}
},
{
"type": "m.room.join_rules",
"sender": "@bob:example.org",
"state_key": "",
"content": {
"join_rule": "invite"
}
}
]
"invite_room_state": {"$ref": "./examples/stripped_state.json"}
},
"content": {
"membership": "invite"
Expand Down Expand Up @@ -168,6 +171,35 @@ paths:
"errcode": "M_FORBIDDEN",
"error": "User cannot invite the target user."
}
"400":
description: |-
The `M_MISSING_PARAM` error code is used to indicate one or more of
the following:

* The `m.room.create` event is missing from `invite_room_state`.
* One or more entries in `invite_room_state` are not formatted according
to the room's version.
* One or more events fails a [signature check](/server-server-api/#validating-hashes-and-signatures-on-received-events).
* One or more events does not reside in the same room as the invite.
Note: Some room versions may require calculating the room ID for an
event rather than relying on the presence of `room_id`.

Servers MAY apply the validation above to room versions 1 through 11,
and SHOULD apply the validation above to all other room versions.

If `M_MISSING_PARAM` is returned and the request is associated with a
Client-Server API request, the Client-Server API request SHOULD fail
with a 5xx error rather than being passed through.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_MISSING_PARAM",
"error": "Create event not among invite state entries."
}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
Expand Down
65 changes: 43 additions & 22 deletions data/api/server-server/invites-v2.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,13 +72,33 @@ paths:
$ref: definitions/invite_event.yaml
invite_room_state:
type: array
x-changedInMatrixVersion:
"1.16": |
`m.room.create` and format requirements were added.
description: |-
An optional list of [stripped state events](/client-server-api/#stripped-state)
to help the receiver of the invite identify the room.
A list of state events to help the receiver of the invite identify the room.
Translated as [stripped state events](/client-server-api/#stripped-state)
over the Client-Server API.

MUST contain the `m.room.create` event for the room. All events listed
MUST additionally be formatted according to the room version specification.

Servers might need to apply validation to the `invite_room_state` depending
on room version. See the `400 M_MISSING_PARAM` error definition for more
information.

Note that events have a different format depending on the room
version - check the [room version specification](/rooms) for
precise event formats.
items:
$ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml
type: object
properties: {}
description: |-
Note that events have a different format depending on the room
version - check the [room version specification](/rooms) for
precise event formats.
example:
$ref: ../../event-schemas/examples/invite_room_state.json
$ref: ./examples/stripped_state.json
required:
- room_version
- event
Expand Down Expand Up @@ -111,24 +131,7 @@ paths:
"origin_server_ts": 1549041175876,
"sender": "@someone:example.org",
"unsigned": {
"invite_room_state": [
{
"type": "m.room.name",
"sender": "@bob:example.org",
"state_key": "",
"content": {
"name": "Example Room"
}
},
{
"type": "m.room.join_rules",
"sender": "@bob:example.org",
"state_key": "",
"content": {
"join_rule": "invite"
}
}
]
"invite_room_state": {"$ref": "./examples/stripped_state.json"}
},
"content": {
"membership": "invite"
Expand All @@ -151,6 +154,24 @@ paths:

The error should be passed through to clients so that they
may give better feedback to users.

The `M_MISSING_PARAM` error code is used to indicate one or more of
the following:

* The `m.room.create` event is missing from `invite_room_state`.
* One or more entries in `invite_room_state` are not formatted according
to the room's version.
* One or more events fails a [signature check](/server-server-api/#validating-hashes-and-signatures-on-received-events).
* One or more events does not reside in the same room as the invite.
Note: Some room versions may require calculating the room ID for an
event rather than relying on the presence of `room_id`.

Servers MAY apply the validation above to room versions 1 through 11,
and SHOULD apply the validation above to all other room versions.

If `M_MISSING_PARAM` is returned and the request is associated with a
Client-Server API request, the Client-Server API request SHOULD fail
with a 5xx error rather than being passed through.
content:
application/json:
schema:
Expand Down
31 changes: 26 additions & 5 deletions data/api/server-server/knocks.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -293,19 +293,40 @@ paths:
knock_room_state:
type: array
items:
$ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml
type: object
properties: {}
description: |-
Note that events have a different format depending on the room
version - check the [room version specification](/rooms) for
precise event formats.
x-changedInMatrixVersion:
"1.16": |
`m.room.create` and format requirements were added.
description: |-
A list of [stripped state events](/client-server-api/#stripped-state)
to help the initiator of the knock identify the room.
A list of state events to help the initiator of the knock identify
the room. Translated as [stripped state events](/client-server-api/#stripped-state)
over the Client-Server API.

MUST contain the `m.room.create` event for the room. All events
listed MUST additionally be formatted according to the room
version specification.

Entries which are [improperly signed](/server-server-api/#validating-hashes-and-signatures-on-received-events)
or formatted SHOULD be removed by the server prior to supplying
them over the Client-Server API.

Note that events have a different format depending on the room
version - check the [room version specification](/rooms) for
precise event formats.
example:
$ref: ../../event-schemas/examples/knock_room_state.json
"$ref": "./examples/stripped_state.json"
required:
- knock_room_state
examples:
response:
value: {
"knock_room_state": {
"$ref": "../../event-schemas/examples/knock_room_state.json"
"$ref": "./examples/stripped_state.json"
}
}
"403":
Expand Down
12 changes: 10 additions & 2 deletions data/event-schemas/schema/m.room.member.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -137,6 +137,9 @@ properties:
- type: object
properties:
invite_room_state:
x-changedInMatrixVersion:
"1.16": |
`m.room.create` was made a required event type for stripped state.
description: |-
A subset of the state of the room at the time of the invite, if `membership` is `invite`.
Note that this state is informational, and SHOULD NOT be trusted; once the client has
Expand All @@ -145,16 +148,21 @@ properties:
they SHOULD behave properly (with possibly a degraded but not a broken experience) in
the absence of any particular events here. If they are set on the room, at least the
state for `m.room.avatar`, `m.room.canonical_alias`, `m.room.join_rules`, and `m.room.name`
SHOULD be included.
SHOULD be included. The `m.room.create` event MUST be included, though MAY be missing if
the server hasn't updated to support the Matrix 1.16 specification.
items:
$ref: "core-event-schema/stripped_state.yaml"
type: array
knock_room_state:
x-changedInMatrixVersion:
"1.16": |
`m.room.create` was made a required event type for stripped state.
description: |-
A subset of the state of the room at the time of the knock, if `membership` is `knock`.
This has the same restrictions as `invite_room_state`. If they are set on the room, at least
the state for `m.room.avatar`, `m.room.canonical_alias`, `m.room.join_rules`, `m.room.name`,
and `m.room.encryption` SHOULD be included.
and `m.room.encryption` SHOULD be included. The `m.room.create` event MUST be included,
though MAY be missing if the server hasn't updated to support the Matrix 1.16 specification.
items:
$ref: "core-event-schema/stripped_state.yaml"
type: array
Expand Down