archive
/
matrix-spec-proposals
mirror of https://github.com/matrix-org/matrix-spec-proposals
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Tidy content, update MSC references

Browse Source
pull/4208/head
Tom Foster 1 year ago
parent 334882fb2f
commit d996f97a42
1 changed files with 68 additions and 35 deletions
Show Stats Download Patch File Download Diff File

103
proposals/4208-user-defined-profile-fields.md
Unescape Escape View File

@ -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 ## 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 ### 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 ### Client-Server API Changes
#### Setting a Custom Profile Field #### 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}` - **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**: - **Request Body**:
```json ```json
{ {
"key_name": "new_value" "u.key_name": "new_value"
} }
``` ```
@ -75,7 +86,8 @@ Response:
To delete a custom profile field: To delete a custom profile field:
- **Endpoint**: `DELETE /_matrix/client/v3/profile/{userId}/{key_name}` - **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 #### Retrieving All Profile Fields
@ -96,7 +108,9 @@ Clients can retrieve all profile fields for a user, including custom fields:
### Capabilities ### 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**: - **Capability Structure**:
@ -104,22 +118,26 @@ A new capability `m.custom_profile_fields` is introduced to control the ability
{ {
"capabilities": { "capabilities": {
"m.custom_profile_fields": { "m.custom_profile_fields": {
"enabled": true, "enabled": true
"allowed": ["u.*"],
"disallowed": []
} }
} }
} }
``` ```
- **Behaviour**: - **Behaviour**:
- **When capability is missing**: Clients should assume that custom profile fields are not supported and refrain from providing options to set them. - **When capability is missing**: Clients should assume that custom profile fields are not
- **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. supported and refrain from providing options to set them.
- **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 `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 ### 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. - **`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 ### Client Considerations
- Clients SHOULD provide a UI for users to view and edit their own custom fields in the `u.*` namespace. - Clients SHOULD provide a UI for users to view and edit their own custom fields in the `u.*`
- When displaying other users' profiles, clients SHOULD retrieve and display custom fields in the `u.*` namespace. namespace.
- Clients SHOULD be cautious about the amount of data displayed and provide options to limit or filter the display of custom fields.
- 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 ### Server Considerations
- Homeservers MAY impose limits on the size and number of custom fields. - Homeservers MAY impose limits on the number of custom fields, whether for storage reasons or to
- Homeservers SHOULD validate that keys in the `u.*` namespace conform to the required format and enforce size limits on values. 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. - Homeservers MAY restrict certain keys or values based on server policies.
## Potential Issues ## Potential Issues
- **Privacy Concerns**: Users need to be aware that custom profile fields are public and visible to anyone who can access their profile. - **Privacy Concerns**: Users need to be aware that custom profile fields are public and visible to
- **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. anyone who can access their profile.
- **Interoperability**: Until widespread adoption occurs, not all clients may support displaying custom fields, leading to inconsistent user experiences.
- **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 ## Security Considerations
- **Content Moderation**: Homeservers SHOULD provide mechanisms to report and handle abusive content in custom profile fields. - **Content Moderation**: Homeservers SHOULD provide mechanisms to report and handle abusive
- **Data Protection**: Homeservers MUST ensure compliance with data protection regulations, especially regarding user consent and data retention. 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 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: 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 ### Unstable Capability
@ -177,9 +213,9 @@ The capability should be advertised with an unstable prefix:
```json ```json
{ {
"capabilities": { "capabilities": {
"uk.tcpip.msc0000.custom_profile_fields": { "uk.tcpip.msc4208.custom_profile_fields": {
"enabled": true, "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 ## 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. 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.

Write Preview
Loading…
Cancel
Save