Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2026-03-04 10:44:10 +01:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity

Merge 5790b2f990 into c9face5050

Browse source
This commit is contained in:
famfo 2026-03-03 16:20:25 +00:00 committed by GitHub
parent c9face5050 5790b2f990
commit 8e7c62f5e6
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 28 additions and 15 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
changelogs/server_server/newsfragments/2326.clarification Normal file
View file

@ -0,0 +1 @@
Clarify the s2s profile query behaviour and responses.

42
data/api/server-server/query.yaml
View file

@ -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"