Merge 729d50cd4a into 67a2aa4761

Co-authored-by: Johannes Marbach <n0-0ne+github@mailbox.org>

changelogs/internal/newsfragments/2189.clarification

@@ -0,0 +1 @@
+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) guests users may only modify their displayname in their profile
+* [PUT /profile/{userId}/displayname](#put_matrixclientv3profileuseridkeyname). Guest users may only modify their display name; other profile fields may not be changed.
-* [DELETE /profile/{userId}/displayname](#delete_matrixclientv3profileuseridkeyname) guests users may only modify their displayname in their profile
+* {{% added-in v="1.16" %}} [DELETE /profile/{userId}/displayname](#delete_matrixclientv3profileuseridkeyname). Again, guest users may delete their display name but not other profile fields.
 * [GET /devices](#get_matrixclientv3devices)
 * [GET /devices/{deviceId}](#get_matrixclientv3devicesdeviceid)
 * [PUT /devices/{deviceId}](#put_matrixclientv3devicesdeviceid)

data/api/client-server/capabilities.yaml

@@ -112,9 +112,12 @@ paths:
                         properties:
                           allowed:
                             type: array
-                            description: List of allowed additional custom profile field keys. A `*` can be used as a
+                            description: |
-                              wildcard to match any sequence of characters. This list takes precedence over the
+                              If present, a list of profile fields that clients are allowed to create, modify or delete,
-                              disallowed list if both are provided.
+                              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.
                             items:
                               type: string
                             example:
@@ -122,11 +125,12 @@ paths:
                               - "org.example.job_title"
                           disallowed:
                             type: array
-                            description: If `enabled` is `true`, a list of profile fields that clients are _not_ allowed to
+                            description:  |
-                              create, modify or delete. Clients SHOULD assume all fields not in this list to be unmanaged
+                              This property has no meaning if `allowed` is also specified.
-                              and available for their use.
                               
-                              Only one of `allowed` and `disallowed` is permitted at the same time.
+                              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.
                             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.
+        "1.16": This endpoint now accepts a variable `keyName` parameter. Previously only `displayname` and `avatar_url` were accepted.
       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 profile field key name to set. This MUST be either
+          description: The name of the profile field 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,12 +61,16 @@ paths:
             schema:
               type: object
               minProperties: 1
-              description: The JSON object must include a property whose key
+              description: |
-                matches the `keyName` specified in the URL. For `avatar_url`,
+                An object which contains exactly one property. The key
-                the value must be an MXC URI string. For `displayname`, the value
+                of that property MUST match the `keyName` specified in the URL.
-                must be a string. For custom keys, any JSON type is allowed -
+                
-                servers may not validate these values, but clients should follow
+                For `avatar_url`, the value MUST be an MXC URI string. 
-                the format defined for that key.
+                
+                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:
@@ -85,7 +89,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.
@@ -133,7 +137,7 @@ paths:
         - User data
     get:
       x-changedInMatrixVersion:
-        "1.16": This endpoint now accepts a variable `keyName` parameter.
+        "1.16": This endpoint now accepts a variable `keyName` parameter. Previously only `displayname` and `avatar_url` were accepted.
       summary: Get a profile field for a user.
       description: Get the value of a profile field for a user.
       operationId: getProfileField
@@ -147,9 +151,7 @@ paths:
             type: string
         - in: path
           name: keyName
-          description: The profile field key name to retrieve. It must be either
+          description: The name of the profile field to retrieve.
-            `avatar_url`, `displayname`, or a custom field following the
-            [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
           required: true
           example: "displayname"
           schema:
@@ -162,12 +164,9 @@ paths:
             application/json:
               schema:
                 type: object
-                description: If a value is stored for `keyName`, the JSON response
+                description: |
-                  includes a property whose key matches the `keyName` specified
+                  An object with one property, whose key matches the `keyName` specified
-                  in the URL. For `avatar_url`, the value will be an MXC URI string.
+                  in the URL, and whose value is the current setting of that profile field.
-                  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:
@@ -210,9 +209,7 @@ paths:
             type: string
         - in: path
           name: keyName
-          description: The key name of the profile field to delete. It must be either
+          description: The name of the profile field to delete.
-            `avatar_url`, `displayname`, or a custom field following the
-            [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
           required: true
           example: "displayname"
           schema:
@@ -220,7 +217,7 @@ paths:
             pattern: '^(avatar_url|displayname|[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+)$'
       responses:
         "200":
-          description: The profile field was deleted.
+          description: The profile field was deleted or it doesn't exist.
           content:
             application/json:
               schema:
@@ -270,9 +267,7 @@ paths:
     get:
       summary: Get all profile information for a user.
       description: |-
-        Get the complete profile for a user. The response includes `avatar_url`
+        Get the complete profile for a user.
-        and `displayname` (unless set to `null`, as they can only be strings)
-        plus any custom profile fields.
       operationId: getUserProfile
       parameters:
         - in: path
@@ -293,14 +288,14 @@ paths:
                   avatar_url:
                     type: string
                     format: mx-mxc-uri
-                    description: "Avatar URL value (MXC URI format)."
+                    description: The user's avatar URL if they have set one, otherwise not present.
                   displayname:
                     type: string
+                    description: The user's display name if they have set one, otherwise not
+                      present.
                 additionalProperties:
                   x-addedInMatrixVersion: "1.16"
-                  description: Any additional profile field value; may be any
+                  description: Additional profile fields.
-                    valid JSON type, with keys following the
-                    [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
               examples:
                 response:
                   value:

meta/documentation_style.rst

@@ -60,6 +60,11 @@ 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.
@@ -84,12 +89,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.
+* ``{{% added-in v="1.2" %}}`` or ``{{% changed-in v="1.2" %}}`` within Markdown documents.
-* `x-addedInMatrixVersion` and `x-changedInMatrixVersion` within OpenAPI.
+* ``x-addedInMatrixVersion`` and ``x-changedInMatrixVersion`` within OpenAPI.
 
 OpenAPI
 ~~~~~~~
@@ -185,4 +190,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``).