From f469ebe50a04ade4cbeb91b46b5d077ea9466f5e Mon Sep 17 00:00:00 2001 From: Tom Black Date: Fri, 7 Jun 2024 15:03:02 +0100 Subject: [PATCH] Field namespaces --- proposals/4133-extended-profiles.md | 77 +++++++++++++++++++---------- 1 file changed, 51 insertions(+), 26 deletions(-) diff --git a/proposals/4133-extended-profiles.md b/proposals/4133-extended-profiles.md index 0502b057cf9..530ca566941 100644 --- a/proposals/4133-extended-profiles.md +++ b/proposals/4133-extended-profiles.md @@ -65,7 +65,10 @@ member events. } ``` -3. **GET `/_matrix/client/v3/profile/{userId}/`**: This endpoint will retrieve all profile fields: +3. **DELETE `/_matrix/client/v3/profile/{userId}/{key_name}`**: This endpoint will remove the key + (and associated value) from the profile, if permitted by the homeserver. + +4. **GET `/_matrix/client/v3/profile/{userId}/`**: This endpoint will retrieve all profile fields: ```json { @@ -76,7 +79,7 @@ member events. } ``` -4. **POST `/_matrix/client/v3/profile/{userId}`**: This endpoint will accept a complete JSON object +5. **POST `/_matrix/client/v3/profile/{userId}`**: This endpoint will accept a complete JSON object to replace the entire profile: ```json @@ -88,25 +91,6 @@ member events. } ``` -### Distinction Between Existing and Custom Fields - -The existing fields, `avatar_url` and `displayname`, will continue to trigger state events in each -room. These fields are replicated per-room via member events. Custom fields, however, will **not** -trigger state events in rooms. They will exist solely at the global level and are intended for -storing metadata about the user that does not need to be replicated in each room. - -- **avatar_url** and **displayname**: Changes to these fields will generate state events in all - rooms the user is a member of. -- **Custom fields**: These are stored in the user's global profile and do not generate state events - in rooms. - -### Size Limit - -To ensure efficient handling and storage of profile data, the entire user profile JSON object -cannot exceed 64KiB. This follows the same size limit as events. Homeservers are allowed to limit -the fields (or content) that their local users can set. However, the only limit they should impose -on remote users is that the entire profile JSON block should not be larger than 64KiB. - ### Server-Server API Changes 1. **GET `/_matrix/federation/v1/query/profile/{userId}/{key_name}`** will mirror the client-server @@ -129,6 +113,45 @@ Example capability object: } ``` +### Distinction Between Existing and Custom Fields + +The existing fields, `avatar_url` and `displayname`, will continue to trigger state events in each +room. These fields are replicated per-room via member events. Custom fields, however, will **not** +trigger state events in rooms. They will exist solely at the global level and are intended for +storing metadata about the user that does not need to be replicated in each room. + +- **avatar_url** and **displayname**: Changes to these fields will generate state events in all + rooms the user is a member of. +- **Custom fields**: These are stored in the user's global profile and do not generate state events + in rooms. + +### Key/Namespace Requirements for Custom Fields + +The namespace for field names is defined as follows: + +- The namespace `m.*` is reserved for fields defined in the Matrix specification. Clients should + ignore any fields in this namespace that they don't understand, as this field may have special + entry/display requirements that are defined in the Matrix specification. +- The namespace `u.*` is reserved for user-defined fields. The portion of the string after the `u.` + is defined the display name of this field. + +For example, if a future MSC were to add a field for user pronouns (not included in this MSC) it +might become `m.pronouns` after entering the spec, but during the unstable process it might be +`org.matrix.msc9876.pronouns`. If the field did not exist in the Matrix spec at all, a user might +add a "My Pronouns" field in their client which would be added to their profile as `u.My Pronouns`. + +### Size Limit + +The name of a field must not exceed 255 bytes. + +To ensure efficient handling and storage of profile data, the entire user profile JSON object +cannot exceed 64KiB. This follows the same size limit as events. Homeservers are allowed to limit +the fields (or content) that their local users can set. However, the only limit they should impose +on remote users is that the entire profile JSON block should not be larger than 64KiB. + +The content of a field can be any valid JSON type, as long as the total size of the user profile +does not exceed 64KiB. + ### Implementation Details - This feature will be implemented as optional but recommended, enabling a smooth transition and @@ -176,19 +199,21 @@ of unintended data persistence. ## Unstable prefix The [current Matrix specification](https://spec.matrix.org/v1.10/#profiles) technically already -allows extra custom fields to be published in a user's profile, however as this field has a special -purpose, an unstable prefix should be used on the object until this proposal has entered the API as -stable: +allows extra custom fields to be published in a user's profile, however as this proposal introduces +additional requirements and allows custom user-defined fields, an unstable prefix should be used on +these fields until this proposal has entered the API as stable: ```json { "avatar_url": "mxc://matrix.org/MyC00lAvatar", "displayname": "John Doe", - "uk.tcpip.msc4133.custom_field1": "field_value", - "uk.tcpip.msc4133.custom_field2": ["one value", "another value"] + "uk.tcpip.msc4133.u.custom_field1": "field_value", + "uk.tcpip.msc4133.u.custom_field2": ["one value", "another value"] } ``` +**Note:** This example includes the `u.*` namespace to identify custom user-defined fields. + The new endpoints would be on the `/_matrix/client/unstable/uk.tcpip.msc4133/profile/{userId}/{key_name}` unstable version, before promoting to `/_matrix/client/v3/profile/{userId}/{key_name}` when this is stable.