From d60c847314dce2366b6c4ab56cd45cff9f2d46ca Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Thu, 31 Jul 2025 13:53:55 +0200 Subject: [PATCH] Add profile_fields capability and deprecations into text section Signed-off-by: Johannes Marbach --- content/client-server-api/_index.md | 62 +++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index e7de10eb..7de422a0 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -2491,8 +2491,59 @@ using an `unstable` version. When this capability is not listed, clients should use `"1"` as the default and only stable `available` room version. +### `m.profile_fields` capability + +This capability has a flag, `enabled`, and two lists, `allowed` and +`disallowed`, that together denote which fields the user is able to +change via the profile endpoints. + +When `enabled` is `false`, all profile fields are managed by the server +and the client is not permitted to make any changes. + +When `enabled` is `true`, clients are permitted to modify profile fields, +subject to the restrictions implied by the OPTIONAL lists `allowed` and +`disallowed`. If only `allowed` is present, clients can modify all +contained fields but SHOULD assume all other fields to be managed by +the server. Contrarily, if only `disallowed` is present, clients are +unable to modify any contained fields but SHOULD assume all other fields +to be unmanaged. If both `allowed` and `disallowed` are specified, +`allowed` takes precendece. This means clients can modify all fields +in `allowed` but none of the fields in `disallowed` unless they also +occur in `allowed`. If neither `allowed` nor `disallowed` is present, +clients can modify all fields without restrictions. + +When not listed, clients SHOULD assume the user is able to change +profile fields without any restrictions, provided the homeserver +advertises a specification version that includes the `m.profile_fields` +capability in the [`/versions`](/client-server-api/#get_matrixclientversions) +response. + +An example of the capability API's response for this capability is: + +```json +{ + "capabilities": { + "m.profile_fields": { + "enabled": true, + "disallowed": ["displayname"] + } + } +} +``` + ### `m.set_displayname` capability +{{% boxes/note %}} +{{% changed-in v="1.16" %}} +This capability is now deprecated. Clients SHOULD use the +[`m.profile_fields`](/client-server-api/#mprofile_fields-capability) +capability instead. + +For backwards compatibility, servers that directly or indirectly include +the `displayname` profile field in the `m.profile_fields` capability +MUST still set this capability accordingly. +{{% /boxes/note %}} + This capability has a single flag, `enabled`, to denote whether the user is able to change their own display name via profile endpoints. Cases for disabling might include users mapped from external identity/directory @@ -2517,6 +2568,17 @@ An example of the capability API's response for this capability is: ### `m.set_avatar_url` capability +{{% boxes/note %}} +{{% changed-in v="1.16" %}} +This capability is now deprecated. Clients SHOULD use the +[`m.profile_fields`](/client-server-api/#mprofile_fields-capability) +capability instead. + +For backwards compatibility, servers that directly or indirectly include +the `avatar_url` profile field in the `m.profile_fields` capability +MUST still set this capability accordingly. +{{% /boxes/note %}} + This capability has a single flag, `enabled`, to denote whether the user is able to change their own avatar via profile endpoints. Cases for disabling might include users mapped from external identity/directory