Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2026-03-18 17:34:09 +01:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

Standardise line-wrapping and update avatar_url format to mx-mxc-uri

Browse source
This commit is contained in:
Tom Foster 2025-02-21 09:28:46 +00:00
parent 37b1362bc1
commit 50eab3501e
1 changed files with 47 additions and 33 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

80
data/api/client-server/profile.yaml
View file

@ -22,12 +22,13 @@ paths:
"1.14": Endpoint now accepts variable `keyName` parameter. "1.14": Endpoint now accepts variable `keyName` parameter.
summary: Set a profile field for a user. summary: Set a profile field for a user.
description: |- description: |-
Set or update a profile field for a user. Set or update a profile field for a user. Must be authenticated with an
Must be authenticated with an access token authorised to make changes. access token authorised to make changes. Servers may impose size limits
Servers may impose size limits on individual fields, and the total profile must be under 64 KiB. on individual fields, and the total profile must be under 64 KiB.
**Note**: Setting a field to `null` keeps the key but with a `null` value, which some servers may reject. **Note**: Setting a field to `null` keeps the key but with a `null` value,
To remove a field completely, use the `DELETE` endpoint instead. which some servers may reject. To remove a field completely, use the
`DELETE` endpoint instead.
operationId: setProfileField operationId: setProfileField
security: security:
- accessTokenQuery: [] - accessTokenQuery: []
@ -42,8 +43,8 @@ paths:
type: string type: string
- in: path - in: path
name: keyName name: keyName
description: The profile field key name to set. description: The profile field key name to set. It must be either
It must be either `avatar_url`, `displayname`, or a custom field following the `avatar_url`, `displayname`, or a custom field following the
[Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar). [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
required: true required: true
example: "displayname" example: "displayname"
@ -51,10 +52,9 @@ paths:
type: string type: string
pattern: '^(avatar_url|displayname|[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+)$' pattern: '^(avatar_url|displayname|[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+)$'
requestBody: requestBody:
description: description: A JSON object containing the property whose name matches
A JSON object that must contain the `keyName` specified in the URL. the `keyName` specified in the URL. See `additionalProperties` for
For custom keys, the value may be any valid JSON type, but if the key is further details.
`avatar_url` or `displayname`, the value MUST be a string.
required: true required: true
content: content:
application/json: application/json:
@ -62,7 +62,10 @@ paths:
type: object type: object
minProperties: 1 minProperties: 1
additionalProperties: additionalProperties:
description: The field value to set; may be any valid JSON type. For `avatar_url` and `displayname`, the value MUST be a string. description: The JSON object must include a property whose key
matches the `keyName` specified in the URL. Its value is the new
profile field value and may be any valid JSON type. However, if the
key is `avatar_url` or `displayname`, the value must be a string.
example: { "displayname": "Alice Wonderland" } example: { "displayname": "Alice Wonderland" }
responses: responses:
"200": "200":
@ -75,8 +78,9 @@ paths:
response: response:
value: {} value: {}
"400": "400":
description: The request is malformed, contains invalid JSON, description: The request is malformed, contains invalid JSON, missing
missing a required parameter, specifies an invalid key, or exceeds allowed size limits. a required parameter, specifies an invalid key, or exceeds allowed
size limits.
content: content:
application/json: application/json:
schema: schema:
@ -95,8 +99,9 @@ paths:
"error": "Invalid profile key.", "error": "Invalid profile key.",
} }
"403": "403":
description: The server is unwilling to perform the operation, description: The server is unwilling to perform the operation, either
either due to insufficient permissions or because profile modifications are disabled. due to insufficient permissions or because profile modifications
are disabled.
content: content:
application/json: application/json:
schema: schema:
@ -120,8 +125,8 @@ paths:
x-changedInMatrixVersion: x-changedInMatrixVersion:
"1.14": Endpoint now accepts variable `keyName` parameter. "1.14": Endpoint now accepts variable `keyName` parameter.
summary: Get a profile field for a user. summary: Get a profile field for a user.
description: |- description: Get the value of a profile field for a user. Any individual
Get the value of a profile field for a user. Any individual field must be within the total profile limit of 64 KiB. field must be within the total profile limit of 64 KiB.
operationId: getProfileField operationId: getProfileField
parameters: parameters:
- in: path - in: path
@ -133,8 +138,8 @@ paths:
type: string type: string
- in: path - in: path
name: keyName name: keyName
description: The profile field key name to retrieve. description: The profile field key name to retrieve. It must be either
It must be either `avatar_url`, `displayname`, or a custom field following the `avatar_url`, `displayname`, or a custom field following the
[Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar). [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
required: true required: true
example: "displayname" example: "displayname"
@ -150,13 +155,18 @@ paths:
type: object type: object
minProperties: 1 minProperties: 1
additionalProperties: additionalProperties:
description: The profile field value; may be any valid JSON type. description: The JSON response must include a property whose
key matches the `keyName` specified in the URL. Its value is
the profile field value and may be any valid JSON type.
However, if the key is `avatar_url` or `displayname`, the
value must be a string.
examples: examples:
response: response:
value: { "displayname": "Alice" } value: { "displayname": "Alice" }
"403": "403":
x-addedInMatrixVersion: "1.12" x-addedInMatrixVersion: "1.12"
description: The server is unwilling to disclose whether the user exists and/or has the specified profile field. description: The server is unwilling to disclose whether the user
exists and/or has the specified profile field.
content: content:
application/json: application/json:
schema: schema:
@ -169,7 +179,8 @@ paths:
"error": "Profile lookup is disabled on this homeserver", "error": "Profile lookup is disabled on this homeserver",
} }
"404": "404":
description: There is no profile field with this key for this user, or the user does not exist. description: There is no profile field with this key for this user, or
the user does not exist.
tags: tags:
- User data - User data
delete: delete:
@ -190,8 +201,8 @@ paths:
type: string type: string
- in: path - in: path
name: keyName name: keyName
description: The profile field key name to delete. description: The profile field key name to delete. It must be either
It must be either `avatar_url`, `displayname`, or a custom field following the `avatar_url`, `displayname`, or a custom field following the
[Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar). [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
required: true required: true
example: "displayname" example: "displayname"
@ -209,7 +220,8 @@ paths:
response: response:
value: {} value: {}
"400": "400":
description: The request is malformed, contains invalid JSON, or specifies an invalid key. description: The request is malformed, contains invalid JSON, or
specifies an invalid key.
content: content:
application/json: application/json:
schema: schema:
@ -249,8 +261,8 @@ paths:
get: get:
summary: Get all profile information for a user. summary: Get all profile information for a user.
description: |- description: |-
Get the complete profile for a user. The response includes `avatar_url` and `displayname` Get the complete profile for a user. The response includes `avatar_url`
(unless set to `null`) plus any custom profile fields. and `displayname` (unless set to `null`) plus any custom profile fields.
**Note**: The complete profile must be under 64 KiB. **Note**: The complete profile must be under 64 KiB.
operationId: getUserProfile operationId: getUserProfile
@ -272,14 +284,14 @@ paths:
properties: properties:
avatar_url: avatar_url:
type: string type: string
format: uri format: mx-mxc-uri
description: "Avatar URL value (MXC URI format)." description: "Avatar URL value (MXC URI format)."
displayname: displayname:
type: string type: string
additionalProperties: additionalProperties:
x-addedInMatrixVersion: "1.14" x-addedInMatrixVersion: "1.14"
description: description: Any additional profile field value; may be any
Any additional profile field value; may be any valid JSON type, with keys following the valid JSON type, with keys following the
[Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar). [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
examples: examples:
response: response:
@ -291,7 +303,8 @@ paths:
} }
"403": "403":
x-addedInMatrixVersion: "1.2" x-addedInMatrixVersion: "1.2"
description: The server is unwilling to disclose whether the user exists and/or has profile information. description: The server is unwilling to disclose whether the user
exists and/or has profile information.
content: content:
application/json: application/json:
schema: schema:
@ -304,7 +317,8 @@ paths:
"error": "Profile lookup is disabled on this homeserver", "error": "Profile lookup is disabled on this homeserver",
} }
"404": "404":
description: There is no profile information for this user or this user does not exist. description: There is no profile information for this user or this
user does not exist.
content: content:
application/json: application/json:
schema: schema: