Skip to content

MSC4339: Allow the user directory to return full profiles #4339

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Half-Shot wants to merge 2 commits into
base: main
Choose a base branch
from
Open

MSC4339: Allow the user directory to return full profiles #4339

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
603404a
Add user search proposal
Half-Shot Sep 2, 2025
d314272
update unstable
Half-Shot Sep 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
73 changes: 73 additions & 0 deletions proposals/4339-user-directory-profiles.md
View file
Open in desktop
Copy link
Member

@tulir tulir Sep 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Implementation requirements:

  • Server
  • Client making use of the data?

Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
# MSC4339: Allow the user directory to return full profiles

The user directory endpoint [POST /_matrix/client/v3/user_directory/search](https://spec.matrix.org/v1.10/client-server-api/#post_matrixclientv3user_directorysearch)
currently allows a response including the `displayname` and `avatar_url`, but otherwise doesn't allow
any other fields to be returned. Now that extensible profiles have landed in the Matrix spec, this
limitation could be lifted.

## Proposal

A new field, `profile_fields`, is optionally available on the request body of the endpoint:

```json
{
"limit": 10,
"search_term": "foo",
"m.profile_fields": ["display_name", "avatar_url", "org.example.job_title"]
}
```

A new field is included on the `results` objects from the search endpoint, `m.profile`. This will contain
the user's profile:

```json
{
"limited": false,
"results": [
{
"m.profile": {
"avatar_url": "mxc://bar.com/foo",
"display_name": "Foo",
"org.example.job_title": "Breaker of things"
},
"user_id": "@foo:bar.com"
}
]
}
```

The `profile_fields` field controls which fields SHOULD be in `m.profile`. If no `profile_fields` value is given, the
implementation MAY choose which fields are returned by default. The intention of this field is to reduce the amount of
data needed to be transmitted to render the client's UI for user search, without prescribing the fields that every
client should use.

Because this changes the response format of the endpoint, the new endpoint should use `v4`. The full
endpoint would be `POST /_matrix/client/v4/user_directory/search`.
Comment on lines +44 to +45
Copy link
Member

@clokep clokep Sep 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not really related to this, but was considering given to whether the given profile fields should be used to control which fields are searched?

Copy link
Contributor Author

@Half-Shot Half-Shot Sep 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The spec says:

The search is performed case-insensitively on user IDs and display names preferably using a collation determined based upon the Accept-Language header provided in the request, if present.

I wonder if we should just relax this to "the server searches relevant profile fields" and leaves those fields up to the implementation rather than be overly specific? I'd rather not extend the spec to specifying specific fields to search, but I think the server should be allowed to search any field it wishes

Copy link
Member

@clokep clokep Sep 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that makes sense, but... not sure it would fit all use-cases. I'm OK with it being out of scope, but might require another API rev in the future.


## Potential issues

This will increase the response size of `user_directory`, but since the client has control over the
fields returned this can be carefully managed.


## Alternatives
Copy link
Contributor

@Johennes Johennes Sep 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you reasonably shoehorn other profile fields into the existing User object (thereby not breaking the response format)? The user_id field could cause clashes but it seems fairly unlikely that somebody would have a user_id field in their profile?

Copy link
Contributor Author

@Half-Shot Half-Shot Sep 8, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm a bit skeptical that someone hasn't tried it. But even if, I feel like you might one day put non-profile fields in the response anyway like "mutual_rooms", or some other non-profile criteria ("is_bot"?)

I feel for extensibility purposes it's good to get a clean slate.

But the point is valid, this would be a breaking change. I think that's why it's probably good to have a version bump for this endpoint. If a client tries to use a v3 endpoint then servers just need to do a little wrapper code to return a reduced profile set.


It's possible today for clients to request a `GET /_matrix/client/v3/profile/{user_id}` for each user,
but this is intensive for search results and if the client wishes to further refine the fields returned
then they need to make one request per field.


## Security considerations

Implementations need to be careful not to be prone to DDOS attacks by frequent requests for large profile
fields. Otherwise, this doesn't increase the surface of available information.

## Unstable prefix

While this proposal is not considered stable, implementations should use `/_matrix/client/unstable/org.matrix.msc4339/user_directory/search`
instead. Clients should note the [`M_UNRECOGNIZED` behaviour](https://spec.matrix.org/v1.10/client-server-api/#common-error-codes)
for servers which do not support the (un)stable endpoint.

## Dependencies

No dependencies.