Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2026-02-19 04:23:43 +01:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

Attempt to make descriptions look better in HTML rendered spec

Browse source
This commit is contained in:
Tom Foster 2025-02-14 14:53:29 +00:00
parent 79af78022e
commit 1cc93ec951
1 changed files with 47 additions and 67 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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

@ -18,15 +18,14 @@ info:
paths: paths:
"/profile/{userId}/{keyName}": "/profile/{userId}/{keyName}":
put: put:
summary: Set the user's profile field. summary: Set a profile field for a user.
description: |- description: |-
This API sets or updates a specified profile field in a user's profile. You must have the Set or update a profile field for a user.
appropriate permissions (i.e. an access token) to modify the profile field. Must be authenticated with an access token authorised to make changes.
Servers may impose size limits on individual fields, and the total profile must be under 64 KiB.
Setting a `null` value SHOULD NOT delete the field. Instead, it retains the key with a `null` **Note**: Setting a field to `null` keeps the key but with a `null` value, which some servers may reject.
value, unless the server rejects the request due to lack of support for `null` values. To remove a field completely, use the `DELETE` endpoint instead.
To fully remove a profile field, use the `DELETE` endpoint. Servers may impose an upper limit
on value length, and profile data is subject to a total size limit of 64 KiB.
operationId: setProfileField operationId: setProfileField
security: security:
- accessTokenQuery: [] - accessTokenQuery: []
@ -42,21 +41,18 @@ paths:
- 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 `avatar_url`, `displayname`, or a custom field following the
[Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
required: true required: true
example: "displayname" example: "displayname"
schema: schema:
oneOf: type: string
- type: string pattern: '^(avatar_url|displayname|[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+)$'
enum: ["avatar_url", "displayname"]
- type: string
pattern: '^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$'
description: Must follow the
[Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
requestBody: requestBody:
description: > description:
The new profile field value. The JSON object must contain the `keyName` specified in the URL. A JSON object that must contain the `keyName` specified in the URL.
For custom keys, the value may be any valid JSON type. However, if the key is "displayname" For custom keys, the value may be any valid JSON type,
or "avatar_url", the value MUST be a string. but if the key is `avatar_url` or `displayname`, the value MUST be a string.
required: true required: true
content: content:
application/json: application/json:
@ -65,11 +61,11 @@ paths:
properties: properties:
avatar_url: avatar_url:
type: string type: string
description: "Avatar URL value (MXC URI format)." description: Avatar URL value (MXC URI format).
displayname: displayname:
type: string type: string
additionalProperties: additionalProperties:
description: "Any additional profile field value; may be any valid JSON type." description: Any additional profile field value; may be any valid JSON type.
example: { "displayname": "Alice Wonderland" } example: { "displayname": "Alice Wonderland" }
responses: responses:
"200": "200":
@ -82,9 +78,8 @@ paths:
response: response:
value: {} value: {}
"400": "400":
description: > description: The request is malformed, contains invalid JSON,
The request is malformed, missing a required parameter, contains invalid JSON (for the value), missing a required parameter, specifies an invalid key, or exceeds allowed size limits.
or specifies an invalid key, or the profile data exceeds allowed limits.
content: content:
application/json: application/json:
schema: schema:
@ -103,9 +98,8 @@ paths:
"error": "Invalid profile key.", "error": "Invalid profile key.",
} }
"403": "403":
description: > description: The server is unwilling to perform the operation,
The server is unwilling to perform the operation—either due to insufficient permissions either due to insufficient permissions or because profile modifications are disabled.
or because profile modifications are disabled.
content: content:
application/json: application/json:
schema: schema:
@ -126,10 +120,9 @@ paths:
tags: tags:
- User data - User data
get: get:
summary: Get the user's profile field. summary: Get a profile field for a user.
description: |- description: |-
Get the value of a user's profile field. This API retrieves stabilised fields and custom Get the value of a profile field for a user. Any individual field must be within the total profile limit of 64 KiB.
profile fields. Profile data is subject to a total size limit of 64 KiB.
operationId: getProfileField operationId: getProfileField
parameters: parameters:
- in: path - in: path
@ -142,16 +135,13 @@ paths:
- 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 `avatar_url`, `displayname`, or a custom field following the
[Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
required: true required: true
example: "displayname" example: "displayname"
schema: schema:
oneOf: type: string
- type: string pattern: '^(avatar_url|displayname|[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+)$'
enum: ["avatar_url", "displayname"]
- type: string
pattern: '^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$'
description: Must follow the
[Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
responses: responses:
"200": "200":
description: The profile field value was retrieved. description: The profile field value was retrieved.
@ -162,19 +152,17 @@ paths:
properties: properties:
avatar_url: avatar_url:
type: string type: string
description: "Avatar URL value (MXC URI format)." description: Avatar URL value (MXC URI format).
displayname: displayname:
type: string type: string
additionalProperties: additionalProperties:
description: "Any additional profile field value; may be any valid JSON type." description: Any additional profile field value, of any valid JSON type.
examples: examples:
response: response:
value: { "displayname": "Alice" } value: { "displayname": "Alice" }
"403": "403":
x-addedInMatrixVersion: "1.12" x-addedInMatrixVersion: "1.12"
description: description: The server is unwilling to disclose whether the user exists and/or has the specified profile field.
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:
@ -191,10 +179,8 @@ paths:
tags: tags:
- User data - User data
delete: delete:
summary: Delete a profile field. summary: Remove a profile field from a user.
description: |- description: Remove a specific field from a user's profile.
Delete the specified profile field from a user's profile. Note that setting a `null` value with the `PUT`
endpoint retains the key with a null value; use this `DELETE` endpoint to fully remove a profile field.
operationId: deleteProfileField operationId: deleteProfileField
security: security:
- accessTokenQuery: [] - accessTokenQuery: []
@ -210,16 +196,13 @@ paths:
- 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 `avatar_url`, `displayname`, or a custom field following the
[Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
required: true required: true
example: "displayname" example: "displayname"
schema: schema:
oneOf: type: string
- type: string pattern: '^(avatar_url|displayname|[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+)$'
enum: ["avatar_url", "displayname"]
- type: string
pattern: '^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$'
description: Must follow the
[Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
responses: responses:
"200": "200":
description: The profile field was deleted. description: The profile field was deleted.
@ -231,8 +214,7 @@ paths:
response: response:
value: {} value: {}
"400": "400":
description: > description: The request is malformed, contains invalid JSON, or specifies an invalid key.
The request is malformed, contains invalid JSON, or specifies an invalid key.
content: content:
application/json: application/json:
schema: schema:
@ -248,8 +230,7 @@ paths:
"error": "Invalid profile key.", "error": "Invalid profile key.",
} }
"403": "403":
description: > description: The user is not authorised to delete this profile field.
The user is not authorised to delete this profile field.
content: content:
application/json: application/json:
schema: schema:
@ -271,11 +252,12 @@ paths:
- User data - User data
"/profile/{userId}": "/profile/{userId}":
get: get:
summary: Get this user's profile information. summary: Get all profile information for a user.
description: |- description: |-
Retrieve the global profile information for a user. In addition to stabilised fields such as Get the complete profile for a user. The response includes `avatar_url` and `displayname`
"avatar_url" and "displayname", this API may include custom profile fields. (unless set to `null`) plus any custom profile fields.
The overall profile data is limited to a maximum of 64 KiB.
**Note**: The complete profile must be under 64 KiB.
operationId: getUserProfile operationId: getUserProfile
parameters: parameters:
- in: path - in: path
@ -300,7 +282,9 @@ paths:
displayname: displayname:
type: string type: string
additionalProperties: additionalProperties:
description: "Any additional profile field value; may be any valid JSON type." description:
Any additional profile field value; may be any valid JSON type, with keys following the
[Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
examples: examples:
response: response:
value: value:
@ -311,9 +295,7 @@ paths:
} }
"403": "403":
x-addedInMatrixVersion: "1.2" x-addedInMatrixVersion: "1.2"
description: description: The server is unwilling to disclose whether the user exists and/or has profile information.
The server is unwilling to disclose whether the user exists and/or
has profile information.
content: content:
application/json: application/json:
schema: schema:
@ -326,9 +308,7 @@ paths:
"error": "Profile lookup is disabled on this homeserver", "error": "Profile lookup is disabled on this homeserver",
} }
"404": "404":
description: description: There is no profile information for this user or this user does not exist.
There is no profile information for this user or this user does not
exist.
content: content:
application/json: application/json:
schema: schema: