Merge f2c14eee9c into 7d2de48cb4

changelogs/internal/newsfragments/2189.clarification

@@ -1 +0,0 @@
-Specify a correct spelling for "display name".

content/client-server-api/modules/guest_access.md

@@ -63,8 +63,8 @@ for sending events:
 The following API endpoints are allowed to be accessed by guest accounts
 for their own account maintenance:
 
-* [PUT /profile/{userId}/displayname](#put_matrixclientv3profileuseridkeyname). Guest users may only modify their display name; other profile fields may not be changed.
-* {{% added-in v="1.16" %}} [DELETE /profile/{userId}/displayname](#delete_matrixclientv3profileuseridkeyname). Again, guest users may delete their display name but not other profile fields.
+* [PUT /profile/{userId}/displayname](#put_matrixclientv3profileuseridkeyname) guests users may only modify their displayname in their profile
+* [DELETE /profile/{userId}/displayname](#delete_matrixclientv3profileuseridkeyname) guests users may only modify their displayname in their profile
 * [GET /devices](#get_matrixclientv3devices)
 * [GET /devices/{deviceId}](#get_matrixclientv3devicesdeviceid)
 * [PUT /devices/{deviceId}](#put_matrixclientv3devicesdeviceid)

data/api/client-server/capabilities.yaml

@@ -112,12 +112,9 @@ paths:
                         properties:
                           allowed:
                             type: array
-                            description: |
-                              If present, a list of profile fields that clients are allowed to create, modify or delete,
-                              provided `enabled` is `true`; no other profile fields may be changed.
-                              
-                              If absent, clients may set all profile fields except those forbidden by the `disallowed`
-                              list, where present.
+                            description: List of allowed additional custom profile field keys. A `*` can be used as a
+                              wildcard to match any sequence of characters. This list takes precedence over the
+                              disallowed list if both are provided.
                             items:
                               type: string
                             example:
@@ -125,12 +122,11 @@ paths:
                               - "org.example.job_title"
                           disallowed:
                             type: array
-                            description:  |
-                              This property has no meaning if `allowed` is also specified.
+                            description: If `enabled` is `true`, a list of profile fields that clients are _not_ allowed to
+                              create, modify or delete. Clients SHOULD assume all fields not in this list to be unmanaged
+                              and available for their use.
                               
-                              Otherwise, if present, a list of profile fields that clients are _not_ allowed to create, modify or delete.
-                              Provided `enabled` is `true`, clients MAY assume that they can set any profile field which is not
-                              included in this list.
+                              Only one of `allowed` and `disallowed` is permitted at the same time.
                             items:
                               type: string
                             example:

data/api/client-server/profile.yaml

@@ -19,7 +19,7 @@ paths:
   "/profile/{userId}/{keyName}":
     put:
       x-changedInMatrixVersion:
-        "1.16": This endpoint now accepts a variable `keyName` parameter. Previously only `displayname` and `avatar_url` were accepted.
+        "1.16": This endpoint now accepts a variable `keyName` parameter.
       summary: Set a profile field for a user.
       description: |-
         Set or update a profile field for a user. Must be authenticated with an
@@ -43,7 +43,7 @@ paths:
             type: string
         - in: path
           name: keyName
-          description: The name of the profile field to set. This MUST be either
+          description: The profile field key name to set. This MUST be either
             `avatar_url`, `displayname`, or a custom field following the
             [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
           required: true
@@ -61,16 +61,12 @@ paths:
             schema:
               type: object
               minProperties: 1
-              description: |
-                An object which contains exactly one property. The key
-                of that property MUST match the `keyName` specified in the URL.
-                
-                For `avatar_url`, the value MUST be an MXC URI string. 
-                
-                For `displayname`, the value MUST be a string.
-                
-                For custom keys, any JSON type is allowed. Servers MAY not validate
-                these values, but clients SHOULD follow the format defined for that key.
+              description: The JSON object must include a property whose key
+                matches the `keyName` specified in the URL. For `avatar_url`,
+                the value must be an MXC URI string. For `displayname`, the value
+                must be a string. For custom keys, any JSON type is allowed -
+                servers may not validate these values, but clients should follow
+                the format defined for that key.
               additionalProperties: true
               example: { "displayname": "Alice Wonderland" }
       responses:
@@ -89,7 +85,7 @@ paths:
             of the following error codes:
             
             - `M_BAD_JSON`: The provided value is not valid JSON.
-            - `M_MISSING_PARAM`: The required `keyName` property is
+            - `M_MISSING_PARAM`: The required `{keyName}` property is
               missing from the request body.
             - `M_PROFILE_TOO_LARGE`: Storing the supplied value would
               make the profile exceed its maximum allowed size of 64 KiB.
@@ -137,7 +133,7 @@ paths:
         - User data
     get:
       x-changedInMatrixVersion:
-        "1.16": This endpoint now accepts a variable `keyName` parameter. Previously only `displayname` and `avatar_url` were accepted.
+        "1.16": This endpoint now accepts a variable `keyName` parameter.
       summary: Get a profile field for a user.
       description: Get the value of a profile field for a user.
       operationId: getProfileField
@@ -151,7 +147,9 @@ paths:
             type: string
         - in: path
           name: keyName
-          description: The name of the profile field 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
           example: "displayname"
           schema:
@@ -164,9 +162,12 @@ paths:
             application/json:
               schema:
                 type: object
-                description: |
-                  An object with one property, whose key matches the `keyName` specified
-                  in the URL, and whose value is the current setting of that profile field.
+                description: If a value is stored for `keyName`, the JSON response
+                  includes a property whose key matches the `keyName` specified
+                  in the URL. For `avatar_url`, the value will be an MXC URI string.
+                  For `displayname`, the value will be a string. For custom keys, any
+                  JSON type is possible - clients should expect the format defined
+                  for that key.
                 additionalProperties: true
               examples:
                 response:
@@ -209,7 +210,9 @@ paths:
             type: string
         - in: path
           name: keyName
-          description: The name of the profile field to delete.
+          description: The key name of the profile field 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
           example: "displayname"
           schema:
@@ -217,7 +220,7 @@ paths:
             pattern: '^(avatar_url|displayname|[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+)$'
       responses:
         "200":
-          description: The profile field was deleted or it doesn't exist.
+          description: The profile field was deleted.
           content:
             application/json:
               schema:
@@ -267,7 +270,9 @@ paths:
     get:
       summary: Get all profile information for a user.
       description: |-
-        Get the complete profile for a user.
+        Get the complete profile for a user. The response includes `avatar_url`
+        and `displayname` (unless set to `null`, as they can only be strings)
+        plus any custom profile fields.
       operationId: getUserProfile
       parameters:
         - in: path
@@ -288,14 +293,14 @@ paths:
                   avatar_url:
                     type: string
                     format: mx-mxc-uri
-                    description: The user's avatar URL if they have set one, otherwise not present.
+                    description: "Avatar URL value (MXC URI format)."
                   displayname:
                     type: string
-                    description: The user's display name if they have set one, otherwise not
-                      present.
                 additionalProperties:
                   x-addedInMatrixVersion: "1.16"
-                  description: Additional profile fields.
+                  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:
                 response:
                   value:

meta/documentation_style.rst

@@ -60,11 +60,6 @@ General
      you have at home. "identity server" is clear, whereas "identityserver" is
      horrible.
 
-* When talking about a user's "display name", it is spelt as two words. In
-  identifiers such as within the content of an ``m.room.member`` event, it is
-  spelt as a single word, ``displayname``. (There are some historical exceptions
-  to this where the identifier is spelt ``display_name``.)
-
 * Lists should:
 
   * Be introduced with a colon.
@@ -89,12 +84,12 @@ Changes between spec versions
 Sections should reference the Matrix spec version they were added/changed in. This
 is often a guess at what the next version will be - please use the currently released
 version with a minor version bump as the referenced version. For example, if the
-current version is ``v1.1`` then annotate your changes with ``v1.2``.
+current version is `v1.1` then annotate your changes with `v1.2`.
 
 "Added/changed in" tags can be documented as the following:
 
-* ``{{% added-in v="1.2" %}}`` or ``{{% changed-in v="1.2" %}}`` within Markdown documents.
-* ``x-addedInMatrixVersion`` and ``x-changedInMatrixVersion`` within OpenAPI.
+* `{{% added-in v="1.2" %}}` or `{{% changed-in v="1.2" %}}` within Markdown documents.
+* `x-addedInMatrixVersion` and `x-changedInMatrixVersion` within OpenAPI.
 
 OpenAPI
 ~~~~~~~
@@ -190,4 +185,4 @@ Describing grammar
 
 Use  `RFC5234-style ABNF <https://datatracker.ietf.org/doc/html/rfc5234>`_ when describing
 the grammar for something in the spec, such as user IDs or server names. Use lowercase
-and underscore-delimited element names (``user_id``, not ``UserID`` or ``user-id``).
+and underscore-delimited element names (`user_id`, not `UserID` or `user-id`).