Tidy content, update MSC references

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,30 +108,36 @@ 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**:
 
 ```json
 {
   "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,34 +159,52 @@ 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
 
 ### Unstable Namespace
 
 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,18 +213,15 @@ 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.*"]
     }
   }
 }
 ```
 
 ## 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.