mirror of
https://github.com/matrix-org/matrix-spec
synced 2026-05-03 15:44:09 +02:00
Compare commits
1 commit
056b61ab84
...
1db317cc75
| Author | SHA1 | Date | |
|---|---|---|---|
|
1db317cc75 |
|
|
@ -1 +1 @@
|
|||
Update user profile endpoints to handle custom fields, and add a new `m.profile_fields` capability, as per [MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133).
|
||||
Update user profile endpoints to handle custom fields, and add a new `m.profile_fields` capability,as per [MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133).
|
||||
|
|
|
|||
|
|
@ -1 +0,0 @@
|
|||
Clarify wording around the `world_readable` history visibility setting. Contributed by @HarHarLinks.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Add a profile field for a user's time zone, per [MSC4175](https://github.com/matrix-org/matrix-spec-proposals/pull/4175).
|
||||
|
|
@ -1 +0,0 @@
|
|||
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 +0,0 @@
|
|||
Fix a grammatical typo on the Matrix Spec Process documentation page.
|
||||
|
|
@ -1 +0,0 @@
|
|||
`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).
|
||||
|
|
@ -2818,14 +2818,6 @@ should be represented as stripped state events when possible:
|
|||
* [`m.room.canonical_alias`](#mroomcanonical_alias)
|
||||
* [`m.room.encryption`](#mroomencryption)
|
||||
|
||||
{{% changed-in v="1.16" %}} The `m.room.create` event is now **required** in
|
||||
the following places:
|
||||
* [`invite_state`](#get_matrixclientv3sync_response-200_invited-room) and
|
||||
[`knock_state`](#get_matrixclientv3sync_response-200_knocked-room) on
|
||||
[`/sync`](#get_matrixclientv3sync) responses.
|
||||
* On [`m.room.member`](#mroommember) events, the `invite_room_state`
|
||||
and `knock_room_state` under `unsigned` on the event.
|
||||
|
||||
{{% boxes/note %}}
|
||||
Clients should inspect the list of stripped state events and not assume any
|
||||
particular event is present. The server might include events not described
|
||||
|
|
@ -2856,12 +2848,6 @@ events are not signed and could theoretically be modified, or outdated due to
|
|||
updates not being sent.
|
||||
{{% /boxes/warning %}}
|
||||
|
||||
{{% boxes/warning %}}
|
||||
{{% added-in v="1.16" %}} Servers cannot pass through what they receive over
|
||||
federation to clients as stripped state. Servers are expected to prune the events
|
||||
into the stripped state schema below before passing the details onto clients.
|
||||
{{% /boxes/warning %}}
|
||||
|
||||
{{% event-fields event_type="stripped_state" %}}
|
||||
|
||||
### Size limits
|
||||
|
|
|
|||
|
|
@ -16,8 +16,8 @@ The four options for the `m.room.history_visibility` event are:
|
|||
|
||||
- `world_readable` - All events while this is the
|
||||
`m.room.history_visibility` value may be shared by any participating
|
||||
homeserver with any authenticated user, regardless of whether they have
|
||||
ever joined the room. This includes [guest users](#guest-access).
|
||||
homeserver with anyone, regardless of whether they have ever joined
|
||||
the room.
|
||||
- `shared` - Previous events are always accessible to newly joined
|
||||
members. All events in the room are accessible, even those sent when
|
||||
the member was not a part of the room.
|
||||
|
|
@ -44,7 +44,7 @@ setting at that time was more restrictive.
|
|||
#### Client behaviour
|
||||
|
||||
Clients may want to display a notice that events may be read by
|
||||
non-joined users if the history visibility is set to `world_readable`.
|
||||
non-joined people if the history visibility is set to `world_readable`.
|
||||
|
||||
#### Server behaviour
|
||||
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@ It is sometimes desirable to offer a preview of a room, where a user can
|
|||
This can be particularly effective when combined with [Guest Access](#guest-access).
|
||||
|
||||
Previews are implemented via the `world_readable` [Room History
|
||||
Visibility](#room-history-visibility) setting, along with a special version of the [GET
|
||||
Visibility](#room-history-visibility). setting, along with a special version of the [GET
|
||||
/events](#get_matrixclientv3events) endpoint.
|
||||
|
||||
#### Client behaviour
|
||||
|
|
|
|||
|
|
@ -555,7 +555,7 @@ resolve to the desired MSC, whether it started as an issue or a PR.
|
|||
Other metadata:
|
||||
|
||||
- The MSC number is taken from the GitHub Pull Request ID. This is
|
||||
carried for the lifetime of the proposal. These IDs do not necessarily
|
||||
carried for the lifetime of the proposal. These IDs do not necessary
|
||||
represent a chronological order.
|
||||
- The GitHub PR title will act as the MSC's title.
|
||||
- Please link to the spec PR (if any) by adding a "PRs: \#1234" line
|
||||
|
|
|
|||
|
|
@ -945,18 +945,6 @@ 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" %}}
|
||||
|
|
|
|||
|
|
@ -43,7 +43,7 @@ properties:
|
|||
example: "All things general"
|
||||
world_readable:
|
||||
type: boolean
|
||||
description: Whether the room may be viewed by users without joining.
|
||||
description: Whether the room may be viewed by guest users without joining.
|
||||
example: false
|
||||
guest_can_join:
|
||||
type: boolean
|
||||
|
|
|
|||
|
|
@ -19,7 +19,7 @@ paths:
|
|||
"/profile/{userId}/{keyName}":
|
||||
put:
|
||||
x-changedInMatrixVersion:
|
||||
"1.16": This endpoint now accepts a variable `keyName` parameter and `m.tz` was added as a defined key. Previously only `displayname` and `avatar_url` were accepted.
|
||||
"1.16": This endpoint now accepts a variable `keyName` parameter. Previously only `displayname` and `avatar_url` were accepted.
|
||||
summary: Set a profile field for a user.
|
||||
description: |-
|
||||
Set or update a profile field for a user. Must be authenticated with an
|
||||
|
|
@ -44,13 +44,13 @@ paths:
|
|||
- in: path
|
||||
name: keyName
|
||||
description: The name of the profile field to set. This MUST be either
|
||||
`avatar_url`, `displayname`, `m.tz`, or a custom field following the
|
||||
`avatar_url`, `displayname`, or a custom field following the
|
||||
[Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
|
||||
required: true
|
||||
example: "displayname"
|
||||
schema:
|
||||
type: string
|
||||
pattern: '^(avatar_url|displayname|m\.tz|[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+)$'
|
||||
pattern: '^(avatar_url|displayname|[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+)$'
|
||||
requestBody:
|
||||
description: A JSON object containing the property whose name matches
|
||||
the `keyName` specified in the URL. See `additionalProperties` for
|
||||
|
|
@ -69,10 +69,6 @@ paths:
|
|||
|
||||
For `displayname`, the value MUST be a string.
|
||||
|
||||
For `m.tz`, the value MUST be a valid identifier from the [IANA Time Zone Database](https://www.iana.org/time-zones).
|
||||
Servers MAY choose to validate the value. Clients MUST expect unknown or invalid
|
||||
values.
|
||||
|
||||
For custom keys, any JSON type is allowed. Servers MAY not validate
|
||||
these values, but clients SHOULD follow the format defined for that key.
|
||||
additionalProperties: true
|
||||
|
|
@ -141,7 +137,7 @@ paths:
|
|||
- User data
|
||||
get:
|
||||
x-changedInMatrixVersion:
|
||||
"1.16": This endpoint now accepts a variable `keyName` parameter and `m.tz` was added as a defined key. Previously only `displayname` and `avatar_url` were accepted.
|
||||
"1.16": This endpoint now accepts a variable `keyName` parameter. Previously only `displayname` and `avatar_url` were accepted.
|
||||
summary: Get a profile field for a user.
|
||||
description: Get the value of a profile field for a user.
|
||||
operationId: getProfileField
|
||||
|
|
@ -160,7 +156,7 @@ paths:
|
|||
example: "displayname"
|
||||
schema:
|
||||
type: string
|
||||
pattern: '^(avatar_url|displayname|m\.tz|[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+)$'
|
||||
pattern: '^(avatar_url|displayname|[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+)$'
|
||||
responses:
|
||||
"200":
|
||||
description: The profile field value was retrieved.
|
||||
|
|
@ -218,7 +214,7 @@ paths:
|
|||
example: "displayname"
|
||||
schema:
|
||||
type: string
|
||||
pattern: '^(avatar_url|displayname|m\.tz|[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+)$'
|
||||
pattern: '^(avatar_url|displayname|[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+)$'
|
||||
responses:
|
||||
"200":
|
||||
description: The profile field was deleted or it doesn't exist.
|
||||
|
|
@ -297,10 +293,6 @@ paths:
|
|||
type: string
|
||||
description: The user's display name if they have set one, otherwise not
|
||||
present.
|
||||
m.tz:
|
||||
x-addedInMatrixVersion: "1.16"
|
||||
type: string
|
||||
description: The user's time zone.
|
||||
additionalProperties:
|
||||
x-addedInMatrixVersion: "1.16"
|
||||
description: Additional profile fields.
|
||||
|
|
@ -310,7 +302,6 @@ paths:
|
|||
{
|
||||
"avatar_url": "mxc://matrix.org/SDGdghriugerRg",
|
||||
"displayname": "Alice Margatroid",
|
||||
"m.tz": "Europe/London",
|
||||
"m.example_field": "custom_value",
|
||||
}
|
||||
"403":
|
||||
|
|
|
|||
|
|
@ -1,9 +0,0 @@
|
|||
[
|
||||
{"$ref": "./minimal_pdu.json"},
|
||||
{
|
||||
"type": "m.room.create",
|
||||
"content": {
|
||||
"see_room_version_spec": "The event format changes depending on the room version."
|
||||
}
|
||||
}
|
||||
]
|
||||
|
|
@ -71,32 +71,13 @@ paths:
|
|||
properties:
|
||||
invite_room_state:
|
||||
type: array
|
||||
x-changedInMatrixVersion:
|
||||
"1.16": |
|
||||
`m.room.create` and format requirements were added.
|
||||
description: |-
|
||||
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.
|
||||
An optional list of [stripped state events](/client-server-api/#stripped-state)
|
||||
to help the receiver of the invite identify the room.
|
||||
items:
|
||||
type: object
|
||||
title: PDU
|
||||
properties: {}
|
||||
description: |-
|
||||
Note that events have a different format depending on the room
|
||||
version - check the [room version specification](/rooms) for
|
||||
precise event formats.
|
||||
$ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml
|
||||
example:
|
||||
$ref: ../../event-schemas/examples/invite_room_state.json
|
||||
type: object
|
||||
required: true
|
||||
responses:
|
||||
|
|
@ -137,7 +118,24 @@ paths:
|
|||
"origin_server_ts": 1549041175876,
|
||||
"sender": "@someone:example.org",
|
||||
"unsigned": {
|
||||
"invite_room_state": {"$ref": "./examples/invite_or_knock_state.json"}
|
||||
"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"
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
"content": {
|
||||
"membership": "invite"
|
||||
|
|
@ -170,35 +168,6 @@ 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:
|
||||
|
|
|
|||
|
|
@ -72,32 +72,13 @@ paths:
|
|||
$ref: definitions/invite_event.yaml
|
||||
invite_room_state:
|
||||
type: array
|
||||
x-changedInMatrixVersion:
|
||||
"1.16": |
|
||||
`m.room.create` and format requirements were added.
|
||||
description: |-
|
||||
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.
|
||||
An optional list of [stripped state events](/client-server-api/#stripped-state)
|
||||
to help the receiver of the invite identify the room.
|
||||
items:
|
||||
type: object
|
||||
title: PDU
|
||||
properties: {}
|
||||
description: |-
|
||||
Note that events have a different format depending on the room
|
||||
version - check the [room version specification](/rooms) for
|
||||
precise event formats.
|
||||
$ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml
|
||||
example:
|
||||
$ref: ../../event-schemas/examples/invite_room_state.json
|
||||
required:
|
||||
- room_version
|
||||
- event
|
||||
|
|
@ -130,7 +111,24 @@ paths:
|
|||
"origin_server_ts": 1549041175876,
|
||||
"sender": "@someone:example.org",
|
||||
"unsigned": {
|
||||
"invite_room_state": {"$ref": "./examples/invite_or_knock_state.json"}
|
||||
"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"
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
"content": {
|
||||
"membership": "invite"
|
||||
|
|
@ -153,24 +151,6 @@ 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:
|
||||
|
|
|
|||
|
|
@ -293,41 +293,19 @@ paths:
|
|||
knock_room_state:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
title: PDU
|
||||
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.
|
||||
$ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml
|
||||
description: |-
|
||||
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.
|
||||
A list of [stripped state events](/client-server-api/#stripped-state)
|
||||
to help the initiator of the knock identify the room.
|
||||
example:
|
||||
"$ref": "./examples/invite_or_knock_state.json"
|
||||
$ref: ../../event-schemas/examples/knock_room_state.json
|
||||
required:
|
||||
- knock_room_state
|
||||
examples:
|
||||
response:
|
||||
value: {
|
||||
"knock_room_state": {
|
||||
"$ref": "./examples/invite_or_knock_state.json"
|
||||
"$ref": "../../event-schemas/examples/knock_room_state.json"
|
||||
}
|
||||
}
|
||||
"403":
|
||||
|
|
|
|||
|
|
@ -137,9 +137,6 @@ 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
|
||||
|
|
@ -148,21 +145,16 @@ 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. 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.
|
||||
SHOULD be included.
|
||||
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. 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.
|
||||
and `m.room.encryption` SHOULD be included.
|
||||
items:
|
||||
$ref: "core-event-schema/stripped_state.yaml"
|
||||
type: array
|
||||
|
|
|
|||
Loading…
Reference in a new issue