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
+3. [Obtain an access token](#login-flows) by authorizing a [scope](#scope) for
-   one of the supported grant types:
+   the client with the [authorization code grant](#authorization-code-grant) or
-   - Use the [authorization code grant](#authorization-code-grant) via the
+   [device authorization grant](#device-authorization-grant).
-     [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.
 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
+Logging in and obtaining an access token with the OAuth 2.0 API should be done
-grant](#authorization-code-grant) for clients that have access to a web browser.
+using either the [authorization code grant](#authorization-code-grant) or
-For clients on devices with limited input capabilities, the
+[device authorization grant](#device-authorization-grant). In the context of the
-[device authorization flow](#device-authorization-flow) can be used instead.
+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,
+##### Authorization code flow
-this means requesting a [scope](#scope) including full client-server API
-read/write access and allocating a device ID.
 
-Once the client has retrieved the [server metadata](#server-metadata-discovery),
+This login flow uses the [authorization code grant](#authorization-code-grant)
-it needs to generate the following values:
+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
+This flow uses the [device authorization grant](#device-authorization-grant) to
-needing to directly interact with a web browser. Instead, the user completes
+allow clients to obtain an access token without needing to directly interact
-authorization on a web browser that can be on a separate device. This is useful
+with a web browser. Instead, the user completes authorization on a web browser
-for devices with limited input capabilities (such as CLI applications or
+that can be a separate device.
-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).
+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
+Once the client has retrieved the [server metadata](#server-metadata-discovery)
-[scope](#scope) including full client-server API read/write access and
+the client needs to generate following value:
-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:
 
 - `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
+endpoint to get the user ID that owns the access token.
-revocation proceed as with the [login flow](#login-flow).
 
 #### 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
+    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
+      a format suitable for clients. `federation` will return the raw event as received
-      over federation. The default is 'client'.
+      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,
+                      URL of the token endpoint, used by the grants.
-                      device authorization grant and the refresh token grant.
                   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
+    description: The type of event, as defined by [the event type specification](/client-server-api/#types-of-room-events).
-      naming conventions e.g. 'com.example.subdomain.event.type'
     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 }}