s2s/query: clarify profile behaviour and API responses by famfo · Pull Request #2326 · matrix-org/matrix-spec

famfo · 2026-03-02T00:42:34Z

Since the existing specification of the behavior is relatively fuzzy, I have chosen the stricter interpretations from multiple places saying something similar.

Pull Request Checklist

Pull request includes a changelog file
Pull request includes a sign off
Pull request is classified as 'other changes'

Preview: https://pr2326--matrix-spec-previews.netlify.app

data/api/server-server/query.yaml

zecakeh · 2026-03-04T08:57:43Z

data/api/server-server/query.yaml

While we are touching this endpoint, I believe that we should remove this enum definition, because it shows as:

One of: [displayname, avatar_url].

But with extended profile fields, more values are possible.

data/api/server-server/query.yaml

richvdh · 2026-03-10T18:07:15Z

data/api/server-server/query.yaml

+                      The display name of the user. MUST either be omitted or set to `null` if
+                      the user does not have a display name set.


Aside: I was a bit surprised by this, but then I found d914c40, and this seems to be just a clarification of that changes.

richvdh

LGTM

turt2live · 2026-03-17T01:21:50Z

@richvdh it's not clear to me if this is ready to merge or not

richvdh · 2026-03-17T10:08:34Z

sorry, I thought it was, but then I saw the requests from @zecakeh for further changes

more changes needed

Signed-off-by: famfo <famfo@famfo.xyz>

richvdh · 2026-03-31T21:35:19Z

@famfo please don't force-push between rounds of review: it makes it very hard to see what has changed since the previous round.

changelogs/server_server/newsfragments/2326.clarification

richvdh · 2026-03-31T21:50:04Z

data/api/server-server/query.yaml

+          - allow users to set arbitrary key/value pairs in their profile in addition to the
+            specified pairs
+          - deny profile look-up over federation by responding with 403 and an error code of
+            `M_FORBIDDEN`
+          - omit certain key/value pairs in the response


Per https://github.com/matrix-org/matrix-spec/blob/main/meta/documentation_style.rst#general:

Suggested change

- allow users to set arbitrary key/value pairs in their profile in addition to the

specified pairs

- deny profile look-up over federation by responding with 403 and an error code of

`M_FORBIDDEN`

- omit certain key/value pairs in the response

- Allow users to set arbitrary key/value pairs in their profile in addition to the

specified pairs.

- Deny profile look-up over federation by responding with 403 and an error code of

`M_FORBIDDEN`.

- Omit certain key/value pairs in the response.

Why is this endpoint talking about setting data? Shouldn't that only be the CS docs?

To set expectations for requesting servers. A server doesn't have to implement the c2s API.

@clokep leaving this thread open for you to assess if you're satisfied with the answer. I agree it's not terribly clear as written here but I think it's an improvement over the current spec and I don't have any immediate suggestions for improvements.

richvdh · 2026-03-31T22:05:56Z

data/api/server-server/query.yaml

+                  m.tz:
+                    type: string
+                    description: The name of the user's time zone. The name MUST be registered in
+                      the [IANA Time Zone Database](https://www.iana.org/time-zones).


It would be good to give this an x-addedInMatrixVersion tag. Since m.tz was added in spec v1.16 (it looks like this change got forgotten in #2206), we should probably set it to "1.16".

should the other fields also get a x-addedInMatrixVersion: "1.16"?

well no, because they haven't been newly added to the spec?

data/api/server-server/query.yaml

clokep · 2026-03-31T22:33:28Z

data/api/server-server/query.yaml

+            matching field MUST included in the response. If no `field` was specified,
+            the response MUST include the fields of the user's profile that can be made


I think there's some missing words:

Suggested change

matching field MUST included in the response. If no `field` was specified,

the response MUST include the fields of the user's profile that can be made

matching field MUST be included in the response. If no `field` was specified,

the response MUST include all of the fields of the user's profile that can be made

I'm still not sure about the fist sentence. I think you're trying to say "the response MUST only include that field", but I can't make that change as a suggestion.

richvdh · 2026-04-07T15:30:00Z

data/api/server-server/query.yaml

+                  m.tz:
+                    type: string
+                    description: The name of the user's time zone. The name SHOULD be registered in
+                      the [IANA Time Zone Database](https://www.iana.org/time-zones), requesting


Comma splice

Suggested change

the [IANA Time Zone Database](https://www.iana.org/time-zones), requesting

the [IANA Time Zone Database](https://www.iana.org/time-zones). Requesting

richvdh · 2026-04-07T15:31:50Z

data/api/server-server/query.yaml

-            the response should include the fields of the user's profile that can be made
-            public, such as the display name and avatar.
+            The profile for the user. If a `field` is specified in the request, the response
+            MUST only included the specified `field`. If no `field` was specified, the response


Suggested change

MUST only included the specified `field`. If no `field` was specified, the response

MUST only include the specified `field`. If no `field` was specified, the response

richvdh · 2026-04-07T15:40:16Z

data/api/server-server/query.yaml

-            public, such as the display name and avatar.
+            The profile for the user. If a `field` is specified in the request, the response
+            MUST only included the specified `field`. If no `field` was specified, the response
+            SHOULD include all of the fields of the user's profile, which can be made public.


This doesn't mean what you want it to mean. In any case, why have you removed the examples of display name and avatar?

Suggested change

SHOULD include all of the fields of the user's profile, which can be made public.

SHOULD include all of the fields of the user's profile that can be made

public, such as the display name and avatar.

famfo requested a review from a team as a code owner March 2, 2026 00:42

famfo force-pushed the s2s-profile branch from a7d41fd to 5790b2f Compare March 2, 2026 00:43

zecakeh reviewed Mar 4, 2026

View reviewed changes

famfo force-pushed the s2s-profile branch from 5790b2f to 0608624 Compare March 4, 2026 14:43

HarHarLinks reviewed Mar 4, 2026

View reviewed changes

data/api/server-server/query.yaml Outdated Show resolved Hide resolved

famfo force-pushed the s2s-profile branch from 0608624 to ca801d1 Compare March 6, 2026 20:10

richvdh reviewed Mar 10, 2026

View reviewed changes

richvdh previously approved these changes Mar 10, 2026

View reviewed changes

richvdh requested review from zecakeh and removed request for zecakeh March 11, 2026 10:26

turt2live requested a review from richvdh March 17, 2026 01:21

richvdh removed request for richvdh and zecakeh March 17, 2026 10:08

s2s/query: clarify profile behaviour and API responses

1133152

Signed-off-by: famfo <famfo@famfo.xyz>

famfo force-pushed the s2s-profile branch from ca801d1 to 1133152 Compare March 22, 2026 11:41

zecakeh approved these changes Mar 28, 2026

View reviewed changes

richvdh requested changes Mar 31, 2026

View reviewed changes

clokep reviewed Mar 31, 2026

View reviewed changes

f

8424acd

richvdh self-requested a review April 7, 2026 10:50

richvdh reviewed Apr 7, 2026

View reviewed changes

richvdh requested changes Apr 7, 2026

View reviewed changes

		The display name of the user. MUST either be omitted or set to `null` if
		the user does not have a display name set.

		matching field MUST included in the response. If no `field` was specified,
		the response MUST include the fields of the user's profile that can be made

	the [IANA Time Zone Database](https://www.iana.org/time-zones), requesting
	the [IANA Time Zone Database](https://www.iana.org/time-zones). Requesting

	MUST only included the specified `field`. If no `field` was specified, the response
	MUST only include the specified `field`. If no `field` was specified, the response

	SHOULD include all of the fields of the user's profile, which can be made public.
	SHOULD include all of the fields of the user's profile that can be made
	public, such as the display name and avatar.

Uh oh!

Conversation

famfo commented Mar 2, 2026 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request Checklist

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

richvdh left a comment

Choose a reason for hiding this comment

Uh oh!

turt2live commented Mar 17, 2026

Uh oh!

richvdh commented Mar 17, 2026

Uh oh!

richvdh commented Mar 31, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

famfo commented Mar 2, 2026 •

edited by github-actions bot

Loading