Merge 6f39b946fd into 2baca03e6b

Co-authored-by: Kévin Commaille <76261501+zecakeh@users.noreply.github.com>

changelogs/client_server/newsfragments/2318.clarification

@@ -0,0 +1 @@
+Fix various typos throughout the specification. Contributed by @HarHarLinks.

changelogs/internal/newsfragments/2318.clarification

@@ -0,0 +1 @@
+Fix various typos throughout the specification. Contributed by @HarHarLinks.

config/_default/hugo.toml

@@ -65,7 +65,7 @@ description = "Home of the Matrix specification for decentralised communication"
 # Everything below this are Site Params
 
 [params]
-copyright = "The Matrix.org Foundation CIC"
+copyright = "The Matrix.org Foundation C.I.C."
 
 [params.version]
 # must be one of "unstable", "current", "historical"

content/client-server-api/_index.md

@@ -523,7 +523,7 @@ endpoint.
 
 With the OAuth 2.0 API, a client can obtain an access token by using one of the
 [grant types](#grant-types) supported by the homeserver and authorizing the
-proper [scope](#scope), as demonstrated in the [login flow](#login-flow). To
+proper [scope](#scope), as demonstrated in the [login flows](#login-flows). To
 invalidate the access token the client must use [token revocation](#token-revocation).
 
 ### Using access tokens
@@ -1720,30 +1720,31 @@ authentication type.
 
 1. [Discover the OAuth 2.0 server metadata](#server-metadata-discovery).
 2. [Register the client with the homeserver](#client-registration).
-3. Obtain an access token by authorizing a [scope](#scope) for the client with
-   one of the supported grant types:
-   - Use the [authorization code grant](#authorization-code-grant) via the
-     [login flow](#login-flow) for clients with access to a web browser.
-   - {{% added-in v="1.18" %}} Use the [device authorization grant](#device-authorization-grant) via the
-     [device authorization flow](#device-authorization-flow) for clients on
-     devices with limited input capabilities (e.g. CLI applications or embedded devices)
-     where the user completes authorization on a separate device.
+3. [Obtain an access token](#login-flows) by authorizing a [scope](#scope) for
+   the client with the [authorization code grant](#authorization-code-grant) or
+   [device authorization grant](#device-authorization-grant).
 4. [Refresh the access token](#token-refresh-flow) with the [refresh token grant](#refresh-token-grant) when it expires.
 5. [Revoke the tokens](#token-revocation) when the users wants to log out of the client.
 
-#### Login flow
+#### Login flows
 
-Logging in with the OAuth 2.0 API should be done with the [authorization code
-grant](#authorization-code-grant) for clients that have access to a web browser.
-For clients on devices with limited input capabilities, the
-[device authorization flow](#device-authorization-flow) can be used instead.
+Logging in and obtaining an access token with the OAuth 2.0 API should be done
+using either the [authorization code grant](#authorization-code-grant) or
+[device authorization grant](#device-authorization-grant). In the context of the
+Matrix specification, this means requesting a [scope](#scope) including full
+client-server API read/write access and allocating a device ID.
 
-In the context of the Matrix specification,
-this means requesting a [scope](#scope) including full client-server API
-read/write access and allocating a device ID.
+##### Authorization code flow
 
-Once the client has retrieved the [server metadata](#server-metadata-discovery),
-it needs to generate the following values:
+This login flow uses the [authorization code grant](#authorization-code-grant)
+and is suitable for clients where the following criteria are met:
+
+- There is a web browser available for the user to complete authentication and
+  authorization.
+- The client can receive the callback via a redirect from the web browser.
+
+Once the client has retrieved the [server metadata](#server-metadata-discovery)
+the client needs to generate the following values:
 
 - `device_id`: a unique identifier for this device; see the
   [`urn:matrix:client:device:<device_id>`](#device-id-allocation) scope token.
@@ -1884,25 +1885,21 @@ Sample response:
 Finally, the client can call the  [`/whoami`](#get_matrixclientv3accountwhoami)
 endpoint to get the user ID that owns the access token.
 
-#### Device authorization flow
+##### Device authorization flow
 
 {{% added-in v="1.18" %}}
 
-The device authorization flow allows clients to obtain an access token without
-needing to directly interact with a web browser. Instead, the user completes
-authorization on a web browser that can be on a separate device. This is useful
-for devices with limited input capabilities (such as CLI applications or
-embedded devices) or where the redirect handling may be unreliable (such as a
-desktop applications).
+This flow uses the [device authorization grant](#device-authorization-grant) to
+allow clients to obtain an access token without needing to directly interact
+with a web browser. Instead, the user completes authorization on a web browser
+that can be a separate device.
 
-This flow uses the [device authorization grant](#device-authorization-grant).
+This is useful for devices with limited input
+capabilities (such as CLI applications or embedded devices) or where the
+redirect handling may be unreliable (such as a desktop applications).
 
-In the context of the Matrix specification, this means requesting a
-[scope](#scope) including full client-server API read/write access and
-allocating a device ID, as with the [login flow](#login-flow).
-
-Once the client has retrieved the [server metadata](#server-metadata-discovery),
-it needs to generate the following value:
+Once the client has retrieved the [server metadata](#server-metadata-discovery)
+the client needs to generate following value:
 
 - `device_id`: a unique identifier for this device; see the
   [`urn:matrix:client:device:<device_id>`](#device-id-allocation) scope token.
@@ -1920,7 +1917,7 @@ the `device_authorization_endpoint` as defined in
 
 Sample device authorization request:
 
-```http
+```
 POST /oauth2/device HTTP/1.1
 Host: account.example.com
 Content-Type: application/x-www-form-urlencoded
@@ -1994,7 +1991,7 @@ parameters, encoded as `application/x-www-form-urlencoded` in the body:
 
 Sample token polling request:
 
-```http
+```
 POST /oauth2/token HTTP/1.1
 Host: account.example.com
 Content-Type: application/x-www-form-urlencoded
@@ -2023,8 +2020,7 @@ The server responds as defined in [RFC 8628 section
 ```
 
 Finally, the client can call the [`/whoami`](#get_matrixclientv3accountwhoami)
-endpoint to get the user ID that owns the access token. Token refreshing and
-revocation proceed as with the [login flow](#login-flow).
+endpoint to get the user ID that owns the access token.
 
 #### Token refresh flow
 
@@ -2381,19 +2377,6 @@ To use this grant, homeservers and clients MUST:
   Encoding Practices](https://openid.net/specs/oauth-v2-multiple-response-types-1_0.html)
   for clients with an HTTPS redirect URI.
 
-###### User registration
-
-Clients can signal to the server that the user desires to register a new account
-by initiating the authorization code grant with the `prompt=create` parameter
-set in the authorization request as defined in [Initiating User Registration via
-OpenID Connect 1.0](https://openid.net/specs/openid-connect-prompt-create-1_0.html).
-
-Whether the homeserver supports this parameter is advertised by the
-`prompt_values_supported` authorization server metadata.
-
-Servers that support this parameter SHOULD show the account registration UI in
-the browser.
-
 ##### Device authorization grant
 
 {{% added-in v="1.18" %}}
@@ -2528,6 +2511,22 @@ The server SHOULD return one of the following responses:
 - For other errors, the server returns a `400 Bad Request` response with error
   details
 
+#### User registration
+
+Clients can signal to the server that the user desires to register a new account
+by initiating the [authorization code grant](#authorization-code-grant) with the `prompt=create` parameter
+set in the authorization request as defined in [Initiating User Registration via
+OpenID Connect 1.0](https://openid.net/specs/openid-connect-prompt-create-1_0.html).
+
+Whether the homeserver supports this parameter is advertised by the
+`prompt_values_supported` authorization server metadata.
+
+Servers that support this parameter SHOULD show the account registration UI in
+the browser.
+
+The `prompt=create` parameter is not supported when using the [device
+authorization grant](#device-authorization-grant).
+
 #### Account management {id="oauth-20-account-management"}
 
 {{% added-in v="1.18" %}}
@@ -3503,7 +3502,7 @@ PUT /rooms/!roomid:domain/state/m.room.bgd.color
 ### Redactions
 
 Since events are extensible it is possible for malicious users and/or
-servers to add keys that are, for example offensive or illegal. Since
+servers to add keys that are, for example, offensive or illegal. Since
 some events cannot be simply deleted, e.g. membership events, we instead
 'redact' events. This involves removing all keys from an event that are
 not required by the protocol. This stripped down event is thereafter
@@ -3601,7 +3600,7 @@ This specification describes the following relationship types:
 * [Event replacements](#event-replacements).
 * [Event annotations](#event-annotations-and-reactions).
 * [Threads](#threading).
-* [References](#reference-relations)
+* [References](#reference-relations).
 
 #### Aggregations of child events
 

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

@@ -107,7 +107,7 @@ flag to `true`.
 ```
 
 {{% boxes/note %}}
-Clients which are acutely aware of threads (they do not render threads, but are otherwise
+Clients which are aware of threads (they do not render threads, but are otherwise
 aware of the feature existing in the spec) can treat rich replies to an event with a `rel_type`
 of `m.thread` as a threaded reply, for conversation continuity on the threaded client's side.
 

data/api/client-server/definitions/event_filter.yaml

@@ -23,14 +23,14 @@ properties:
   not_senders:
     description: A list of sender IDs to exclude. If this list is absent then no senders
       are excluded. A matching sender will be excluded even if it is listed in the
-      `'senders'` filter.
+      `senders` filter.
     items:
       type: string
     type: array
   not_types:
     description: A list of event types to exclude. If this list is absent then no
       event types are excluded. A matching type will be excluded even if it is listed
-      in the `'types'` filter. A '*' can be used as a wildcard to match any sequence
+      in the `types` filter. A `*` can be used as a wildcard to match any sequence
       of characters.
     items:
       type: string
@@ -43,7 +43,7 @@ properties:
     type: array
   types:
     description: A list of event types to include. If this list is absent then all
-      event types are included. A `'*'` can be used as a wildcard to match any sequence
+      event types are included. A `*` can be used as a wildcard to match any sequence
       of characters.
     items:
       type: string

data/api/client-server/definitions/room_event_filter.yaml

@@ -39,7 +39,7 @@ allOf:
         for more information. Defaults to `false`.
     not_rooms:
       description: A list of room IDs to exclude. If this list is absent then no rooms
-        are excluded. A matching room will be excluded even if it is listed in the `'rooms'`
+        are excluded. A matching room will be excluded even if it is listed in the `rooms`
         filter.
       items:
         type: string

data/api/client-server/definitions/sync_filter.yaml

@@ -17,15 +17,15 @@ properties:
   event_fields:
     description: List of event fields to include. If this list is absent then all
       fields are included. The entries are [dot-separated paths for each property](/appendices#dot-separated-property-paths)
-      to include. So ['content.body'] will include the 'body' field of the 'content' object.
+      to include. So `['content.body']` will include the `body` field of the `content` object.
       A server may include more fields than were requested.
     items:
       type: string
     type: array
   event_format:
-    description: The format to use for events. 'client' will return the events in
-      a format suitable for clients. 'federation' will return the raw event as received
-      over federation. The default is 'client'.
+    description: The format to use for events. `client` will return the events in
+      a format suitable for clients. `federation` will return the raw event as received
+      over federation. The default is `client`.
     enum:
     - client
     - federation
@@ -45,7 +45,7 @@ properties:
     properties:
       not_rooms:
         description: A list of room IDs to exclude. If this list is absent then no rooms
-          are excluded. A matching room will be excluded even if it is listed in the `'rooms'`
+          are excluded. A matching room will be excluded even if it is listed in the `rooms`
           filter. This filter is applied before the filters in `ephemeral`,
           `state`, `timeline` or `account_data`
         items:
@@ -65,7 +65,7 @@ properties:
           events that appear in the `ephemeral` property in the `/sync`
           response.
       include_leave:
-        description: Include rooms that the user has left in the sync, default false
+        description: Include rooms that the user has left in the sync. Defaults to `false`.
         type: boolean
       state:
         type: object

data/api/client-server/list_public_rooms.yaml

@@ -226,7 +226,7 @@ paths:
                   type: boolean
                   description: |-
                     Whether or not to include all known networks/protocols from
-                    application services on the homeserver. Defaults to false.
+                    application services on the homeserver. Defaults to `false`.
                   example: false
                 third_party_instance_id:
                   type: string
@@ -277,4 +277,4 @@ components:
     accessTokenQuery:
       $ref: definitions/security.yaml#/accessTokenQuery
     accessTokenBearer:
-      $ref: definitions/security.yaml#/accessTokenBearer
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/login.yaml

@@ -163,7 +163,7 @@ paths:
                     known client device, a new device will be created. The given
                     device ID must not be the same as a
                     [cross-signing](/client-server-api/#cross-signing) key ID.
-                    The server will auto-generate a device_id
+                    The server will auto-generate a `device_id`
                     if this is not specified.
                 initial_device_display_name:
                   type: string

data/api/client-server/oauth_server_metadata.yaml

@@ -67,8 +67,7 @@ paths:
                     type: string
                     format: uri
                     description: |-
-                      URL of the token endpoint, necessary to use the authorization code grant,
-                      device authorization grant and the refresh token grant.
+                      URL of the token endpoint, used by the grants.
                   revocation_endpoint:
                     type: string
                     format: uri

data/api/client-server/password_management.yaml

@@ -57,7 +57,7 @@ paths:
                   type: boolean
                   description: |-
                     Whether the user's other access tokens, and their associated devices, should be
-                    revoked if the request succeeds. Defaults to true.
+                    revoked if the request succeeds. Defaults to `true`.
 
                     When `false`, the server can still take advantage of the [soft logout method](/client-server-api/#soft-logout)
                     for the user's remaining devices.

data/api/client-server/registration.yaml

@@ -126,7 +126,7 @@ paths:
                   description: |-
                     ID of the client device. If this does not correspond to a
                     known client device, a new device will be created. The server
-                    will auto-generate a device_id if this is not specified.
+                    will auto-generate a `device_id` if this is not specified.
                   example: GHTYAJCE
                 initial_device_display_name:
                   type: string
@@ -139,11 +139,11 @@ paths:
                   description: |-
                     If true, an `access_token` and `device_id` should not be
                     returned from this call, therefore preventing an automatic
-                    login. Defaults to false.
+                    login. Defaults to `false`.
                   example: false
                 refresh_token:
                   type: boolean
-                  description: If true, the client supports refresh tokens.
+                  description: If `true`, the client supports refresh tokens.
                   x-addedInMatrixVersion: "1.3"
         required: true
       responses:

data/api/client-server/room_send.yaml

@@ -31,7 +31,7 @@ paths:
 
         The body of the request should be the content object of the event; the
         fields in this object will vary depending on the type of event. See
-        [Room Events](/client-server-api/#room-events) for the m. event specification.
+        [Room Events](/client-server-api/#room-events) for the `m.` event specification.
 
         Homeservers MUST allow clients to send `m.room.redaction` events with this
         endpoint for all room versions. In rooms with a version older than 11 they

data/api/server-server/public_rooms.yaml

@@ -49,7 +49,7 @@ paths:
           name: include_all_networks
           description: |-
             Whether or not to include all networks/protocols defined by application
-            services on the homeserver. Defaults to false.
+            services on the homeserver. Defaults to `false`.
           example: false
           schema:
             type: boolean
@@ -121,7 +121,7 @@ paths:
                   type: boolean
                   description: |-
                     Whether or not to include all known networks/protocols from
-                    application services on the homeserver. Defaults to false.
+                    application services on the homeserver. Defaults to `false`.
                   example: false
                 third_party_instance_id:
                   type: string

data/event-schemas/schema/core-event-schema/event.yaml

@@ -7,8 +7,7 @@ properties:
       When interacting with the REST API, this is the HTTP body.
     type: object
   type:
-    description: The type of event. This SHOULD be namespaced similar to Java package
-      naming conventions e.g. 'com.example.subdomain.event.type'
+    description: The type of event, as defined by [the event type specification](/client-server-api/#types-of-room-events).
     type: string
 required:
   - type

data/event-schemas/schema/m.room.server_acl.yaml

@@ -54,7 +54,7 @@ properties:
         type: boolean
         description: |-
           True to allow server names that are IP address literals. False to
-          deny. Defaults to true if missing or otherwise not a boolean.
+          deny. Defaults to `true` if missing or otherwise not a boolean.
 
           This is strongly recommended to be set to `false` as servers running
           with IP literal names are strongly discouraged in order to require

layouts/_partials/events/render-event.html

@@ -49,7 +49,7 @@
   </tr>
 {{ if $state_key }}
   <tr>
-   <th>State key</th>
+   <th>State key:</th>
    <td>{{ $state_key.description | markdownify }}</td>
  </tr>
 {{ end }}