From d60c847314dce2366b6c4ab56cd45cff9f2d46ca Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Thu, 31 Jul 2025 13:53:55 +0200 Subject: [PATCH 1/8] 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 From 78ca69093553b552f9d1b1af083e3a1f2bc2c600 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Wed, 6 Aug 2025 13:12:33 +0200 Subject: [PATCH 2/8] Update content/client-server-api/_index.md Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- content/client-server-api/_index.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 7de422a0..e09a47bd 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -2493,6 +2493,8 @@ default and only stable `available` room version. ### `m.profile_fields` capability +{{% added-in v="1.16" %}} + 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. From 08ef01beeca75eb65fb75bddb4647741c55267ce Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Wed, 6 Aug 2025 13:12:56 +0200 Subject: [PATCH 3/8] Update content/client-server-api/_index.md Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- content/client-server-api/_index.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index e09a47bd..0b76a371 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -2495,9 +2495,11 @@ default and only stable `available` room version. {{% added-in v="1.16" %}} -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. +This capability defines which [profile](#profiles) fields the user is +able to change. + +The capability value has a required flag, `enabled`, and two optional lists, `allowed` and +`disallowed`. When `enabled` is `false`, all profile fields are managed by the server and the client is not permitted to make any changes. From a644bcd7a114e69bc4eee3ce0dd9a739a5937574 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Wed, 6 Aug 2025 13:18:13 +0200 Subject: [PATCH 4/8] Update content/client-server-api/_index.md Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- content/client-server-api/_index.md | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 0b76a371..2a7cc5a2 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -2506,15 +2506,18 @@ 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. +`disallowed`. + +If `allowed` is present, clients can modify only the fields +listed. They SHOULD assume all other fields to be managed by +the server. In this case, `disallowed` has no meaning and should be ignored. + +If `disallowed` is present (and `allowed` is not), clients should assume +that the listed fields are managed by the server. Clients may modify any +fields that are *not* listed, provided `enabled` is `true`. + +If neither `allowed` nor `disallowed` is present, clients can modify all fields +without restrictions, provided `enabled` is `true`. When not listed, clients SHOULD assume the user is able to change profile fields without any restrictions, provided the homeserver From cd527f5b58a4c371663dc15c079ff79aaa1c4d46 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Wed, 6 Aug 2025 13:18:26 +0200 Subject: [PATCH 5/8] Update content/client-server-api/_index.md Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- content/client-server-api/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 2a7cc5a2..9110281b 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -2519,7 +2519,7 @@ fields that are *not* listed, provided `enabled` is `true`. If neither `allowed` nor `disallowed` is present, clients can modify all fields without restrictions, provided `enabled` is `true`. -When not listed, clients SHOULD assume the user is able to change +When this capability is 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) From 11cc84829797738a58ba6d58a75758c137750fff Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Wed, 6 Aug 2025 13:23:44 +0200 Subject: [PATCH 6/8] Update content/client-server-api/_index.md --- content/client-server-api/_index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 9110281b..426245fc 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -2581,9 +2581,9 @@ 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. +For backwards compatibility, servers that forbid setting the +`avatar_url` profile field in the `m.profile_fields` capability +MUST still present this capability with `"enabled": false`. {{% /boxes/note %}} This capability has a single flag, `enabled`, to denote whether the user From 681a7618c0b85d5d074514481c55a93508dd8799 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Wed, 6 Aug 2025 13:23:51 +0200 Subject: [PATCH 7/8] Update content/client-server-api/_index.md Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- content/client-server-api/_index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 426245fc..4d23b636 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -2546,9 +2546,9 @@ 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. +For backwards compatibility, servers that forbid setting the +`displayname` profile field in the `m.profile_fields` capability +MUST still present this capability with `"enabled": false`. {{% /boxes/note %}} This capability has a single flag, `enabled`, to denote whether the user From 0d89ec84e2dc908268438ca1cc512f4fdc12f4bb Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Wed, 6 Aug 2025 13:25:29 +0200 Subject: [PATCH 8/8] Update content/client-server-api/_index.md --- content/client-server-api/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 4d23b636..2c48a7b6 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -2512,7 +2512,7 @@ If `allowed` is present, clients can modify only the fields listed. They SHOULD assume all other fields to be managed by the server. In this case, `disallowed` has no meaning and should be ignored. -If `disallowed` is present (and `allowed` is not), clients should assume +If `disallowed` is present (and `allowed` is not), clients SHOULD assume that the listed fields are managed by the server. Clients may modify any fields that are *not* listed, provided `enabled` is `true`.