matrix-spec-proposals/proposals/4208-user-defined-profile-fields.md

MSC4208: Adding User-Defined Custom Fields to User Global Profiles #4208

This proposal depends on MSC4133: Extending User Profile API. 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, 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, 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.

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:

• 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.
• Request Body:

{
  "key_name": "new_value"
}

Example: Setting the custom field u.bio for user @alice:matrix.org:

PUT /_matrix/client/v3/profile/@alice:matrix.org/u.bio

With body:

{
  "u.bio": "I love Matrix!"
}

Retrieving Custom Profile Fields

To retrieve custom fields from a user's profile, clients use the GET endpoint:

• Endpoint: GET /_matrix/client/v3/profile/{userId}/{key_name}
• Description: Retrieve the value of a specified key_name from a user's profile.
• Response:

{
  "key_name": "field_value"
}

Example: Retrieving the custom field u.bio for user @alice:matrix.org:

GET /_matrix/client/v3/profile/@alice:matrix.org/u.bio

Response:

{
  "u.bio": "I love Matrix!"
}

Deleting a Custom Profile Field

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.

Retrieving All Profile Fields

Clients can retrieve all profile fields for a user, including custom fields:

• Endpoint: GET /_matrix/client/v3/profile/{userId}
• Description: Retrieve all profile fields for a user.
• Response:

{
  "avatar_url": "mxc://matrix.org/MyC00lAvatar",
  "displayname": "Alice",
  "u.bio": "I love Matrix!",
  "u.location": "London"
}

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.

• Capability Structure:

{
  "capabilities": {
    "m.custom_profile_fields": {
      "enabled": true,
      "allowed": ["u.*"],
      "disallowed": []
    }
  }
}

• 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.

Error Handling

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.

{
  "errcode": "M_KEY_NOT_ALLOWED",
  "error": "The profile key 'u.bio' is not allowed to be set."
}

• M_TOO_LARGE: The value provided exceeds the maximum allowed length.

{
  "errcode": "M_TOO_LARGE",
  "error": "The value exceeds the maximum allowed length of 512 bytes."
}

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.

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 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.

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.

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.

Unstable Capability

The capability should be advertised with an unstable prefix:

{
  "capabilities": {
    "uk.tcpip.msc0000.custom_profile_fields": {
      "enabled": true,
      "allowed": ["uk.tcpip.msc0000.u.*"]
    }
  }
}

Dependencies

This proposal depends on MSC4133, 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.