From 5790b2f99036d156a2db4dd007bc5e0bdb811194 Mon Sep 17 00:00:00 2001
From: famfo <famfo@famfo.xyz>
Date: Mon, 2 Mar 2026 01:38:54 +0100
Subject: [PATCH] s2s/query: clarify profile behaviour and API responses

Signed-off-by: famfo <famfo@famfo.xyz>
---
 .../newsfragments/2326.clarification          |  1 +
 data/api/server-server/query.yaml             | 42 ++++++++++++-------
 2 files changed, 28 insertions(+), 15 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..c87aa14a 100644
--- a/data/api/server-server/query.yaml
+++ b/data/api/server-server/query.yaml
@@ -111,11 +111,11 @@ 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
+        Servers MAY wish to cache the response to this query to avoid requesting the
         information too often.
 
         Servers MAY deny profile look-up over federation by responding with 403 and an
@@ -126,7 +126,7 @@ paths:
       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,9 +134,9 @@ 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.
           schema:
             type: string
             enum:
@@ -146,12 +146,12 @@ paths:
         "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 +160,32 @@ 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
               examples:
                 response:
                   value: {
                     "displayname": "John Doe",
-                    "avatar_url": "mxc://matrix.org/MyC00lAvatar"
+                    "avatar_url": "mxc://example.org/MyC00lAvatar"
+                  }
+        "400":
+          description: A given `field` in the query is invalid.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_UNRECOGNIZED",
+                    "error": "Field m.room.name is not in valid subset valid profile fields"
                   }
         "403":
           x-addedInMatrixVersion: "1.12"