From 113315248d8e7072bf2d354bcc2bf32af9f58b85 Mon Sep 17 00:00:00 2001 From: famfo Date: Mon, 2 Mar 2026 01:38:54 +0100 Subject: [PATCH 1/2] s2s/query: clarify profile behaviour and API responses Signed-off-by: famfo --- .../newsfragments/2326.clarification | 1 + data/api/server-server/query.yaml | 54 +++++++++++-------- 2 files changed, 33 insertions(+), 22 deletions(-) create mode 100644 changelogs/server_server/newsfragments/2326.clarification diff --git a/changelogs/server_server/newsfragments/2326.clarification b/changelogs/server_server/newsfragments/2326.clarification new file mode 100644 index 00000000..3aa30e31 --- /dev/null +++ b/changelogs/server_server/newsfragments/2326.clarification @@ -0,0 +1 @@ +Clarify the s2s profile query behaviour and responses. diff --git a/data/api/server-server/query.yaml b/data/api/server-server/query.yaml index cc678208..90feb6f9 100644 --- a/data/api/server-server/query.yaml +++ b/data/api/server-server/query.yaml @@ -111,22 +111,26 @@ paths: summary: Query for profile information about a given user description: |- Performs a query to get profile information, such as a display name or avatar, - for a given user. Homeservers should only query profiles for users that belong + for a given user. Homeservers MUST only query profiles for users that belong to the target server (identified by the [server name](/appendices/#server-name) in the user ID). - Servers may wish to cache the response to this query to avoid requesting the - information too often. + Responding servers MAY + - 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 - Servers MAY deny profile look-up over federation by responding with 403 and an - error code of `M_FORBIDDEN`. + Requesting servers MAY wish to cache the response to this query to avoid requesting the + information too often. operationId: queryProfile security: - signedRequest: [] parameters: - in: query name: user_id - description: The user ID to query. Must be a user local to the receiving homeserver. + description: The user ID to query. MUST be a user local to the receiving homeserver. required: true example: "@someone:example.org" schema: @@ -134,24 +138,24 @@ paths: - in: query name: field description: |- - The field to query. If specified, the server will only return the given field - in the response. If not specified, the server will return the full profile for - the user. + The field of the profile to query. If specified, the server MUST only return the + given field in the response. If not specified, the server MUST return the full, + public, profile for the user. + + Defined values are `displayname`, `avatar_url` and `m.tz`. In addition to these + servers MAY allow users to set additional key/value pairs. schema: type: string - enum: - - displayname - - avatar_url responses: "200": description: |- The profile for the user. If a `field` is specified in the request, only the - matching field should be included in the response. If no `field` was specified, - the response should include the fields of the user's profile that can be made + 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 public, such as the display name and avatar. If the user does not have a particular field set on their profile, the server - should exclude it from the response body or give it the value `null`. + MUST either exclude it from the response body or give it the value `null`. content: application/json: schema: @@ -160,20 +164,26 @@ paths: displayname: type: string description: |- - The display name of the user. May be omitted if the user does not have a - display name set. + The display name of the user. MUST either be omitted or set to `null` if + the user does not have a display name set. example: John Doe avatar_url: type: string description: |- - The avatar URL for the user's avatar. May be omitted if the user does not - have an avatar set. - example: mxc://matrix.org/MyC00lAvatar + The avatar URL for the user's avatar. MUST either be omitted or set to + `null` if the user does not have an avatar set. + example: mxc://example.org/MyC00lAvatar + 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). + additionalProperties: + description: Additional profile fields. examples: response: value: { "displayname": "John Doe", - "avatar_url": "mxc://matrix.org/MyC00lAvatar" + "avatar_url": "mxc://example.org/MyC00lAvatar" } "403": x-addedInMatrixVersion: "1.12" @@ -190,7 +200,7 @@ paths: "error": "Profile lookup over federation is disabled on this homeserver" } "404": - description: The user does not exist or does not have a profile. + description: The user does not exist, does not have a profile or the queried field does not exist. content: application/json: schema: From 8424acd0e14252a336202305dbc3059bbb55a4dc Mon Sep 17 00:00:00 2001 From: famfo Date: Fri, 3 Apr 2026 23:24:39 +0200 Subject: [PATCH 2/2] f --- .../newsfragments/2326.clarification | 2 +- data/api/server-server/query.yaml | 28 +++++++++++-------- 2 files changed, 17 insertions(+), 13 deletions(-) diff --git a/changelogs/server_server/newsfragments/2326.clarification b/changelogs/server_server/newsfragments/2326.clarification index 3aa30e31..c4494772 100644 --- a/changelogs/server_server/newsfragments/2326.clarification +++ b/changelogs/server_server/newsfragments/2326.clarification @@ -1 +1 @@ -Clarify the s2s profile query behaviour and responses. +Clarify the behaviour and response format of `GET /_matrix/federation/v1/query/profile`. diff --git a/data/api/server-server/query.yaml b/data/api/server-server/query.yaml index 90feb6f9..26ab39bf 100644 --- a/data/api/server-server/query.yaml +++ b/data/api/server-server/query.yaml @@ -115,12 +115,12 @@ paths: to the target server (identified by the [server name](/appendices/#server-name) in the user ID). - Responding servers MAY - - 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 + Responding servers MAY: + - 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. Requesting servers MAY wish to cache the response to this query to avoid requesting the information too often. @@ -149,10 +149,12 @@ paths: responses: "200": description: |- - The profile for the user. If a `field` is specified in the request, only the - 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 - 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. + + If a field in the user's profile can't be made public over the federation, the + responding server MAY choose to exclude it in the response. If the user does not have a particular field set on their profile, the server MUST either exclude it from the response body or give it the value `null`. @@ -175,8 +177,10 @@ paths: example: mxc://example.org/MyC00lAvatar 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). + 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 + servers MUST tolerate invalid or unknown values. + x-addedInMatrixVersion: "1.16" additionalProperties: description: Additional profile fields. examples: