Merge 113315248d into 9c014a9045

changelogs/client_server/newsfragments/2348.clarification

@@ -1 +0,0 @@
-Fix ordering of common error codes.

changelogs/server_server/newsfragments/2326.clarification

@@ -1 +1 @@
-Clarify the behaviour and response format of `GET /_matrix/federation/v1/query/profile`.
+Clarify the s2s profile query behaviour and responses.

content/client-server-api/_index.md

@@ -126,25 +126,6 @@ state (e.g.: sending messages, account data, etc) and not routes which
 only read state (e.g.: [`/sync`](#get_matrixclientv3sync),
 [`/user/{userId}/account_data/{type}`](#get_matrixclientv3useruseridaccount_datatype), etc).
 
-`M_UNKNOWN`
-: An unknown error has occurred.
-
-`M_UNKNOWN_DEVICE`
-: {{% added-in v="1.17" %}} The device ID supplied by the application service does
-not belong to the user ID during [identity assertion](/application-service-api/#identity-assertion).
-
-`M_UNKNOWN_TOKEN`
-: The access or refresh token specified was not recognised.
-
-: An additional response parameter, `soft_logout`, might be present on the
-response for 401 HTTP status codes. See [the soft logout
-section](#soft-logout) for more information.
-
-`M_UNRECOGNIZED`
-: The server did not understand the request. This is expected to be returned with
-a 404 HTTP status code if the endpoint is not implemented or a 405 HTTP status
-code if the endpoint is implemented, but the incorrect HTTP method is used.
-
 `M_USER_LIMIT_EXCEEDED`
 : {{% added-in v="1.18" %}} The request cannot be completed because the user has
 exceeded (or the request would cause them to exceed) a limit associated with
@@ -176,6 +157,25 @@ limit is a hard limit that cannot be increased.
   }
   ```
 
+`M_UNKNOWN`
+: An unknown error has occurred.
+
+`M_UNKNOWN_DEVICE`
+: {{% added-in v="1.17" %}} The device ID supplied by the application service does
+not belong to the user ID during [identity assertion](/application-service-api/#identity-assertion).
+
+`M_UNKNOWN_TOKEN`
+: The access or refresh token specified was not recognised.
+
+: An additional response parameter, `soft_logout`, might be present on the
+response for 401 HTTP status codes. See [the soft logout
+section](#soft-logout) for more information.
+
+`M_UNRECOGNIZED`
+: The server did not understand the request. This is expected to be returned with
+a 404 HTTP status code if the endpoint is not implemented or a 405 HTTP status
+code if the endpoint is implemented, but the incorrect HTTP method is used.
+
 `M_USER_LOCKED`
 : The account has been [locked](#account-locking) and cannot be used at this time.
 

data/api/server-server/query.yaml

@@ -115,12 +115,12 @@ paths:
         to the target server (identified by the [server name](/appendices/#server-name)
         in the user ID).
 
-        Responding servers MAY:
+        Responding servers MAY
-          - Allow users to set arbitrary key/value pairs in their profile in addition to the
+          - allow users to set arbitrary key/value pairs in their profile in addition to the
-            specified pairs.
+            specified pairs
-          - Deny profile look-up over federation by responding with 403 and an error code of
+          - deny profile look-up over federation by responding with 403 and an error code of
-            `M_FORBIDDEN`.
+            `M_FORBIDDEN`
-          - Omit certain key/value pairs in the response.
+          - omit certain key/value pairs in the response
 
         Requesting servers MAY wish to cache the response to this query to avoid requesting the
         information too often.
@@ -149,12 +149,10 @@ paths:
       responses:
         "200":
           description: |-
-            The profile for the user. If a `field` is specified in the request, the response
+            The profile for the user. If a `field` is specified in the request, only the
-            MUST only included the specified `field`. If no `field` was specified, the response
+            matching field MUST included in the response. If no `field` was specified,
-            SHOULD include all of the fields of the user's profile, which can be made public.
+            the response MUST include the fields of the user's profile that can be made
-
+            public, such as the display name and avatar.
-            If a field in the user's profile can't be made public over the federation, the
-            responding server MAY choose to exclude it in the response.
 
             If the user does not have a particular field set on their profile, the server
             MUST either exclude it from the response body or give it the value `null`.
@@ -177,10 +175,8 @@ paths:
                     example: mxc://example.org/MyC00lAvatar
                   m.tz:
                     type: string
-                    description: The name of the user's time zone. The name SHOULD be registered in
+                    description: The name of the user's time zone. The name MUST be registered in
-                      the [IANA Time Zone Database](https://www.iana.org/time-zones), requesting
+                      the [IANA Time Zone Database](https://www.iana.org/time-zones).
-                      servers MUST tolerate invalid or unknown values.
-                    x-addedInMatrixVersion: "1.16"
                 additionalProperties:
                   description: Additional profile fields.
               examples: