diff --git a/proposals/4208-user-defined-profile-fields.md b/proposals/4208-user-defined-profile-fields.md index 7369e38d6ca..e24481e6544 100644 --- a/proposals/4208-user-defined-profile-fields.md +++ b/proposals/4208-user-defined-profile-fields.md @@ -1,30 +1,41 @@ -# MSC4208: Adding User-Defined Custom Fields to User Global Profiles #4208 +# MSC4208: Adding User-Defined Custom Fields to User Global Profiles -*This proposal depends on [MSC4133: Extending User Profile API](https://github.com/matrix-org/matrix-spec-proposals/pull/4133). It introduces user-defined custom fields in the `u.*` namespace for user profiles.* +*This proposal depends on [MSC4133: Extending User Profile API](https://github.com/matrix-org/matrix-spec-proposals/pull/4133). +It introduces user-defined custom fields in the `u.*` namespace for user profiles.* ## Proposal -This proposal aims to enable users to add arbitrary custom key:value pairs to their global user profiles within the Matrix ecosystem. By leveraging the extended profile API introduced in [MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133), users can enrich their profiles with additional public information such as preferred languages, organisational roles, or other relevant details. +This proposal aims to enable users to add arbitrary custom key:value pairs to their global user +profiles within the Matrix ecosystem. By leveraging the extended profile API introduced in +[MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133), users can enrich their +profiles with additional public information such as preferred languages, organisational roles, or +other relevant details. ### Key/Namespace Requirements -As per [MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133), the profile API is extended to allow additional fields beyond `avatar_url` and `displayname`. This MSC defines the use of the `u.*` namespace for user-defined custom fields. +As per [MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133), the profile API is +extended to allow additional fields beyond `avatar_url` and `displayname`. This MSC defines the use +of the `u.*` namespace for user-defined custom fields: -- **Namespace `u.*`**: Reserved for user-defined custom fields. The portion of the key name after the `u.` defines the display name of this field (e.g., `u.bio`). The values in this namespace must always be UTF-8 strings with content not exceeding 512 bytes. +- **Namespace `u.*`**: Reserved for user-defined custom fields. The portion of the key name after + the `u.` defines the display name of this field (e.g., `u.bio`). The values in this namespace + must always be UTF-8 strings with content not exceeding 512 bytes. ### Client-Server API Changes #### Setting a Custom Profile Field -To set or update a custom profile field, clients can use the `PUT` endpoint defined in [MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133): +To set or update a custom profile field, clients can use the `PUT` endpoint defined in +[MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133): - **Endpoint**: `PUT /_matrix/client/v3/profile/{userId}/{key_name}` -- **Description**: Set or update the value of a specified `key_name` in the user's profile, if permitted by the homeserver. +- **Description**: Set or update the value of a specified `key_name` in the user's profile, + if permitted by the homeserver. - **Request Body**: ```json { - "key_name": "new_value" + "u.key_name": "new_value" } ``` @@ -75,7 +86,8 @@ Response: To delete a custom profile field: - **Endpoint**: `DELETE /_matrix/client/v3/profile/{userId}/{key_name}` -- **Description**: Remove a specified `key_name` and its value from the user's profile, if permitted by the homeserver. +- **Description**: Remove a specified `key_name` and its value from the user's profile, + if permitted by the homeserver. #### Retrieving All Profile Fields @@ -96,7 +108,9 @@ Clients can retrieve all profile fields for a user, including custom fields: ### Capabilities -A new capability `m.custom_profile_fields` is introduced to control the ability to set custom profile fields. It is advertised on the `GET /_matrix/client/v3/capabilities` endpoint. Clients should check for this capability before attempting to create or modify custom fields. +A new capability `m.custom_profile_fields` is introduced to control the ability to set custom +profile fields. It is advertised on the `GET /_matrix/client/v3/capabilities` endpoint. Clients +should check for this capability before attempting to create or modify custom fields. - **Capability Structure**: @@ -104,22 +118,26 @@ A new capability `m.custom_profile_fields` is introduced to control the ability { "capabilities": { "m.custom_profile_fields": { - "enabled": true, - "allowed": ["u.*"], - "disallowed": [] + "enabled": true } } } ``` - **Behaviour**: - - **When capability is missing**: Clients should assume that custom profile fields are not supported and refrain from providing options to set them. - - **When `enabled` is `false`**: Clients should not allow users to create or update custom fields. Any attempt to do so should result in a `403 Forbidden` error. - - **When `enabled` is `true`**: Clients should allow users to create or update custom fields in the `u.*` namespace, except those listed in the `disallowed` array. + - **When capability is missing**: Clients should assume that custom profile fields are not + supported and refrain from providing options to set them. + + - **When `enabled` is `false`**: Clients should not allow users to create or update custom + fields. Any attempt to do so should result in a `403 Forbidden` error. + + - **When `enabled` is `true`**: Clients should allow users to create or update custom fields in + the `u.*` namespace, except those listed in the `disallowed` array. ### Error Handling -Consistent error codes and messages ensure clear communication of issues. Homeservers should use the following error codes: +Consistent error codes and messages ensure clear communication of issues. Homeservers should use +the following error codes: - **`M_KEY_NOT_ALLOWED`**: The specified key is not allowed to be set. @@ -141,26 +159,44 @@ Consistent error codes and messages ensure clear communication of issues. Homese ### Client Considerations -- Clients SHOULD provide a UI for users to view and edit their own custom fields in the `u.*` namespace. -- When displaying other users' profiles, clients SHOULD retrieve and display custom fields in the `u.*` namespace. -- Clients SHOULD be cautious about the amount of data displayed and provide options to limit or filter the display of custom fields. +- Clients SHOULD provide a UI for users to view and edit their own custom fields in the `u.*` + namespace. + +- When displaying other users' profiles, clients SHOULD retrieve and display custom fields in the + `u.*` namespace. + +- Clients SHOULD be cautious about the amount of data displayed and provide options to limit or + filter the display of custom fields. ### Server Considerations -- Homeservers MAY impose limits on the size and number of custom fields. -- Homeservers SHOULD validate that keys in the `u.*` namespace conform to the required format and enforce size limits on values. +- Homeservers MAY impose limits on the number of custom fields, whether for storage reasons or to + ensure the total profile size remains under 64KiB as defined in [MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133). + +- Homeservers MAY validate that keys in the `u.*` namespace conform to the required format and + enforce size limits on values. + - Homeservers MAY restrict certain keys or values based on server policies. ## Potential Issues -- **Privacy Concerns**: Users need to be aware that custom profile fields are public and visible to anyone who can access their profile. -- **Abuse Potential**: As with any user-generated content, there is potential for misuse. Servers and clients need to be prepared to handle offensive or inappropriate content. -- **Interoperability**: Until widespread adoption occurs, not all clients may support displaying custom fields, leading to inconsistent user experiences. +- **Privacy Concerns**: Users need to be aware that custom profile fields are public and visible to + anyone who can access their profile. + +- **Abuse Potential**: As with any user-generated content, there is potential for misuse. Servers + and clients need to be prepared to handle offensive or inappropriate content. + +- **Interoperability**: Until widespread adoption occurs, not all clients may support displaying + custom fields, leading to inconsistent user experiences. ## Security Considerations -- **Content Moderation**: Homeservers SHOULD provide mechanisms to report and handle abusive content in custom profile fields. -- **Data Protection**: Homeservers MUST ensure compliance with data protection regulations, especially regarding user consent and data retention. +- **Content Moderation**: Homeservers SHOULD provide mechanisms to report and handle abusive + content in custom profile fields. [MSC4202](https://github.com/matrix-org/matrix-spec-proposals/pull/4202) + provides an example of one such mechanism. + +- **Data Protection**: Homeservers SHOULD ensure compliance with data protection regulations, + especially regarding user consent and data retention. ## Unstable Prefixes @@ -168,7 +204,7 @@ Consistent error codes and messages ensure clear communication of issues. Homese Until this proposal is stabilised, custom fields should use an unstable prefix in their keys: -- **Namespace `uk.tcpip.msc0000.u.*`**: For example, `uk.tcpip.msc0000.u.bio`. +- **Namespace `uk.tcpip.msc4208.u.*`**: For example, `uk.tcpip.msc4208.u.bio`. ### Unstable Capability @@ -177,9 +213,9 @@ The capability should be advertised with an unstable prefix: ```json { "capabilities": { - "uk.tcpip.msc0000.custom_profile_fields": { + "uk.tcpip.msc4208.custom_profile_fields": { "enabled": true, - "allowed": ["uk.tcpip.msc0000.u.*"] + "allowed": ["uk.tcpip.msc4208.u.*"] } } } @@ -187,8 +223,5 @@ The capability should be advertised with an unstable prefix: ## Dependencies -This proposal depends on [MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133), which introduces the extended profile API to allow additional fields in user profiles. - -## Conclusion - -By introducing user-defined custom fields in the `u.*` namespace, this proposal allows users to enrich their profiles with additional information, enhancing interactions within the Matrix ecosystem while maintaining simplicity and compatibility with existing infrastructure. +This proposal depends on [MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133), +which introduces the extended profile API to allow additional fields in user profiles.