Merge a3dc964679 into fca171427f

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

changelogs/application_service/newsfragments/2131.clarification

@@ -0,0 +1 @@
+Format Application Service schemas.

changelogs/client_server/newsfragments/2083.clarification

@@ -0,0 +1,2 @@
+Clarify the format of third-party invites, including the fact that identity
+server public keys can be encoded using standard or URL-safe base64.

changelogs/identity_service/newsfragments/2083.clarification

@@ -0,0 +1 @@
+Clarify that public keys can be encoded using standard or URL-safe base64.

changelogs/server_server/newsfragments/2083.clarification

@@ -0,0 +1,2 @@
+Clarify the format of third-party invites, including the fact that identity
+server public keys can be encoded using standard or URL-safe base64.

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

@@ -5,8 +5,8 @@ This module adds in support for inviting new members to a room where
 their Matrix user ID is not known, instead addressing them by a third-party
 identifier such as an email address. There are two flows here; one
 if a Matrix user ID is known for the third-party identifier, and one if
-not. Either way, the client calls [`/invite`](#post_matrixclientv3roomsroomidinvite) with the details of the
+not. Either way, the client calls [`/invite`](#thirdparty_post_matrixclientv3roomsroomidinvite)
-third-party identifier.
+with the details of the third-party identifier.
 
 The homeserver asks the identity server whether a Matrix user ID is
 known for that identifier:
@@ -37,10 +37,12 @@ A client asks a server to invite a user by their third-party identifier.
 
 #### Server behaviour
 
-Upon receipt of an [`/invite`](#post_matrixclientv3roomsroomidinvite), the server is expected to look up the
+Upon receipt of an [`/invite`](#thirdparty_post_matrixclientv3roomsroomidinvite),
-third-party identifier with the provided identity server. If the lookup
+the server is expected to look up the third-party identifier with the provided
-yields a result for a Matrix User ID then the normal invite process can
+identity server by making a call to [`/_matrix/identity/v2/lookup`](/identity-service-api/#post_matrixidentityv2lookup).
-be initiated. This process ends up looking like this:
+If the lookup yields a result for a Matrix User ID then the normal [invite
+process](/server-server-api/#inviting-to-a-room) can be initiated. This process
+ends up looking like this:
 
 ```
     +---------+                         +-------------+                                    +-----------------+
@@ -66,10 +68,11 @@ be initiated. This process ends up looking like this:
         |                                     |                                                    |
 ```
 
-However, if the lookup does not yield a bound User ID, the homeserver
+However, if the lookup does not yield a bound User ID, the homeserver must store
-must store the invite on the identity server and emit a valid
+the invite on the identity server with a call to
-`m.room.third_party_invite` event to the room. This process ends up
+[`/_matrix/identity/v2/store-invite`](/identity-service-api/#post_matrixidentityv2store-invite)
-looking like this:
+and emit a valid [`m.room.third_party_invite`](#mroomthird_party_invite) event
+to the room. This process ends up looking like this:
 
 ```
     +---------+                         +-------------+                                               +-----------------+
@@ -101,15 +104,18 @@ looking like this:
         |                                     |                                                               |
 ```
 
-All homeservers MUST verify the signature in the event's
+The third-party user will then need to verify their identity, which results in a
-`content.third_party_invite.signed` object.
+request to [`/_matrix/federation/v1/3pid/onbind`](/server-server-api/#put_matrixfederationv13pidonbind)
+from the identity server to the homeserver that bound the third-party identifier
+to a user. The homeserver then exchanges the `m.room.third_party_invite` event
+in the room for a complete [`m.room.member`](#mroommember) event with
+`content.membership: invite` and a `content.third_party_invite` property for the
+user that has bound the third-party identifier. If the invitee is on a different
+homeserver than the inviting user, the invitee's homeserver makes a request to
+[`/_matrix/federation/v1/exchange_third_party_invite/{roomId}`](/server-server-api/#put_matrixfederationv1exchange_third_party_inviteroomid).
 
-The third-party user will then need to verify their identity, which
+All homeservers MUST verify the signature in the `m.room.member` event's
-results in a call from the identity server to the homeserver that bound
+`content.third_party_invite.signed` object.
-the third-party identifier to a user. The homeserver then exchanges the
-`m.room.third_party_invite` event in the room for a complete
-`m.room.member` event for `membership: invite` for the user that has
-bound the third-party identifier.
 
 If a homeserver is joining a room for the first time because of an
 `m.room.third_party_invite`, the server which is already participating
@@ -193,8 +199,8 @@ at any time - the completion is not shown in the diagram.
 
 H1 MUST verify the request from H3 to ensure the `signed` property is
 correct as well as the `key_validity_url` as still being valid. This is
-done by making a request to the [identity server
+done by making a request to the identity server's
-/isvalid](/identity-service-api/#get_matrixidentityv2pubkeyisvalid)
+[`/pubkey/isvalid`](/identity-service-api/#get_matrixidentityv2pubkeyisvalid)
 endpoint, using the provided URL rather than constructing a new one. The
 query string and response for the provided URL must match the Identity
 Service Specification.

content/server-server-api.md

@@ -970,9 +970,8 @@ the event to other servers in the room.
 ## Third-party invites
 
 {{% boxes/note %}}
-More information about third-party invites is available in the
+More information about third-party invites is available in the Client-Server API
-[Client-Server API](/client-server-api) under
+under the [Third-party invites](/client-server-api/#third-party-invites) module.
-the Third-party Invites module.
 {{% /boxes/note %}}
 
 When a user wants to invite another user in a room but doesn't know the
@@ -985,38 +984,41 @@ API](/identity-service-api).
 
 ### Cases where an association exists for a third-party identifier
 
-If the third-party identifier is already bound to a Matrix ID, a lookup
+If the third-party identifier is already bound to a Matrix ID, a [lookup
-request on the identity server will return it. The invite is then
+request](/identity-service-api/#post_matrixidentityv2lookup) on the identity
-processed by the inviting homeserver as a standard `m.room.member`
+server will return it. The invite is then processed by the inviting homeserver
-invite event. This is the simplest case.
+as a [standard `m.room.member` invite event](#inviting-to-a-room). This is the
+simplest case.
 
 ### Cases where an association doesn't exist for a third-party identifier
 
 If the third-party identifier isn't bound to any Matrix ID, the inviting
-homeserver will request the identity server to store an invite for this
+homeserver will request the identity server to [store an invite](/identity-service-api/#invitation-storage)
-identifier and to deliver it to whoever binds it to its Matrix ID. It
+for this identifier and to deliver it to whoever binds it to its Matrix ID. It
-will also send an `m.room.third_party_invite` event in the room to
+will also send an [`m.room.third_party_invite`](/client-server-api/#mroomthird_party_invite)
-specify a display name, a token and public keys the identity server
+event in the room to specify a display name, a token and public keys the
-provided as a response to the invite storage request.
+identity server provided as a response to the invite storage request.
 
-When a third-party identifier with pending invites gets bound to a
+When a third-party identifier with pending invites gets bound to a Matrix ID,
-Matrix ID, the identity server will send a POST request to the ID's
+the identity server will send a request to the [`/3pid/onbind`](#put_matrixfederationv13pidonbind)
-homeserver as described in the [Invitation
+endpoint of the the ID's homeserver as described in the [Invitation
-Storage](/identity-service-api#invitation-storage)
+Storage](/identity-service-api#invitation-storage) section of the Identity
-section of the Identity Service API.
+Service API.
 
 The following process applies for each invite sent by the identity
 server:
 
-The invited homeserver will create an `m.room.member` invite event
+The invited homeserver will create an [`m.room.member`](/client-server-api/#mroommember)
-containing a special `third_party_invite` section containing the token
+invite event containing a special `third_party_invite` section containing the
-and a signed object, both provided by the identity server.
+token and a `signed` object, both provided by the identity server.
 
 If the invited homeserver is in the room the invite came from, it can
 auth the event and send it.
 
 However, if the invited homeserver isn't in the room the invite came
-from, it will need to request the room's homeserver to auth the event.
+from, it will need to request the inviting homeserver to auth the event
+at the [`/exchange_third_party_invite`](#put_matrixfederationv1exchange_third_party_inviteroomid)
+endpoint.
 
 {{% http-api spec="server-server" api="third_party_invite" %}}
 

data/api/application-service/definitions/location.yaml

@@ -29,4 +29,4 @@ properties:
     }
 required: ['alias', 'protocol', 'fields']
 title: Location
-type: object
+type: object

data/api/application-service/definitions/namespace_list.yaml

@@ -19,10 +19,13 @@ items:
   properties:
     regex:
       type: string
-      description: A POSIX regular expression defining which values this namespace includes.
+      description: >-
+        A POSIX regular expression defining which values this namespace includes.
     exclusive:
       type: boolean
-      description: A true or false value stating whether this application service has exclusive access to events within this namespace.
+      description: >-
+        A true or false value stating whether this application service has
+        exclusive access to events within this namespace.
   required:
     - regex
     - exclusive

data/api/application-service/definitions/protocol.yaml

@@ -16,7 +16,7 @@ allOf:
 - type: object
   properties:
     instances:
-      description: |-
+      description: >-
         A list of objects representing independent instances of configuration.
         For example, multiple networks on IRC if multiple are provided by the
         same application service.

data/api/application-service/definitions/protocol_base.yaml

@@ -15,7 +15,7 @@ title: Protocol
 type: object
 properties:
   user_fields:
-    description: |-
+    description: >-
       Fields which may be used to identify a third-party user. These should be
       ordered to suggest the way that entities may be grouped, where higher
       groupings are ordered first. For example, the name of a network should be
@@ -26,9 +26,9 @@ properties:
       description: Field used to identify a third-party user.
     example: ["network", "nickname"]
   location_fields:
-    description: |-
+    description: >-
-      Fields which may be used to identify a third-party location. These should be
+      Fields which may be used to identify a third-party location. These should
-      ordered to suggest the way that entities may be grouped, where higher
+      be ordered to suggest the way that entities may be grouped, where higher
       groupings are ordered first. For example, the name of a network should be
       searched before the name of a channel.
     type: array
@@ -41,10 +41,11 @@ properties:
     type: string
     example: "mxc://example.org/aBcDeFgH"
   field_types:
-    description: |-
+    description: >-
       The type definitions for the fields defined in `user_fields` and
-      `location_fields`. Each entry in those arrays MUST have an entry here.
+      `location_fields`. Each entry in those arrays MUST have an entry here. The
-      The `string` key for this object is the field name itself.
+      `string` key for this object is the field name itself.
+
 
       May be an empty object if no fields are defined.
     type: object
@@ -54,10 +55,11 @@ properties:
       type: object
       properties:
         regexp:
-          description: |-
+          description: >-
-            A regular expression for validation of a field's value. This may be relatively
+            A regular expression for validation of a field's value. This may be
-            coarse to verify the value as the application service providing this protocol
+            relatively coarse to verify the value as the application service
-            may apply additional validation or filtering.
+            providing this protocol may apply additional validation or
+            filtering.
           type: string
         placeholder:
           description: A placeholder serving as a valid example of the field value.

data/api/application-service/definitions/protocol_instance.yaml

@@ -20,9 +20,9 @@ properties:
     example: "Freenode"
   icon:
     type: string
-    description: |-
+    description: >-
-      An optional content URI representing the protocol. Overrides the one provided
+      An optional content URI representing the protocol. Overrides the one
-      at the higher level Protocol object.
+      provided at the higher level Protocol object.
     example: "mxc://example.org/JkLmNoPq"
   fields:
     type: object

data/api/application-service/definitions/registration.yaml

@@ -17,27 +17,37 @@ title: Registration
 properties:
   id:
     type: string
-    description: A unique, user-defined ID of the application service which will never change.
+    description: >-
+      A unique, user-defined ID of the application service which will never change.
   url:
     type: string
-    description: The URL for the application service. May include a path after the domain name. Optionally set to null if no traffic is required.
+    description: >-
+      The URL for the application service. May include a path after the domain
+      name. Optionally set to null if no traffic is required.
   as_token:
     type: string
-    description: A secret token that the application service will use to authenticate requests to the homeserver.
+    description: >-
+      A secret token that the application service will use to authenticate
+      requests to the homeserver.
   hs_token:
     type: string
-    description: A secret token that the homeserver will use authenticate requests to the application service.
+    description: >-
+      A secret token that the homeserver will use authenticate requests to the
+      application service.
   sender_localpart:
     type: string
-    description: |-
+    description: >-
-      The localpart of the user associated with the application service. Events will be sent to the AS if this user is the target of the event, or
+      The localpart of the user associated with the application service. Events
-      is a joined member of the room where the event occurred.
+      will be sent to the AS if this user is the target of the event, or is a
+      joined member of the room where the event occurred.
   receive_ephemeral:
     type: boolean
     x-addedInMatrixVersion: "1.13"
-    description: |-
+    description: >-
-      Whether the application service wants to [receive ephemeral data](/application-service-api/#pushing-ephemeral-data).
+      Whether the application service wants to [receive ephemeral
-      
+      data](/application-service-api/#pushing-ephemeral-data).
+
+
       Defaults to `false` if not present.
   namespaces:
     type: object
@@ -47,7 +57,7 @@ properties:
       users:
         allOf:
           - $ref: namespace_list.yaml
-          - description: |-
+          - description: >-
               A list of namespaces defining the user IDs that the application
               service is interested in, in addition to its `sender_localpart`.
               Events will be sent to the AS if a local user matching one of the
@@ -56,23 +66,26 @@ properties:
       rooms:
         allOf:
           - $ref: namespace_list.yaml
-          - description: |-
+          - description: >-
               A list of namespaces defining the room IDs that the application
               service is interested in. All events sent in a room with an ID
               which matches one of the namespaces will be sent to the AS.
       aliases:
         allOf:
           - $ref: namespace_list.yaml
-          - description: |-
+          - description: >-
-              A list of namespaces defining the room aliases that the application
+              A list of namespaces defining the room aliases that the
-              service is interested in. All events sent in a room with an alias
+              application service is interested in. All events sent in a room
-              which matches one of the namespaces will be sent to the AS.
+              with an alias which matches one of the namespaces will be sent to
+              the AS.
   rate_limited:
     type: boolean
-    description: Whether requests from masqueraded users are rate-limited. The sender is excluded.
+    description: >-
+      Whether requests from masqueraded users are rate-limited. The sender is excluded.
   protocols:
     type: array
-    description: The external protocols which the application service provides (e.g. IRC).
+    description: >-
+      The external protocols which the application service provides (e.g. IRC).
     items:
       type: string
 required:

data/api/application-service/definitions/security.yaml

@@ -15,4 +15,5 @@
 homeserverAccessToken:
   type: http
   scheme: bearer
-  description: The `Bearer` `hs_token` provided by the application service's registration.
+  description: >-
+    The `Bearer` `hs_token` provided by the application service's registration.

data/api/application-service/definitions/user.yaml

@@ -30,4 +30,4 @@ properties:
     }
 required: ['userid', 'protocol', 'fields']
 title: User
-type: object
+type: object

data/api/application-service/ping.yaml

@@ -20,13 +20,18 @@ paths:
     post:
       x-addedInMatrixVersion: "1.7"
       summary: Ping the application service
-      description: |-
+      description: >-
         This API is called by the homeserver to ensure that the connection works
         and the `hs_token` the homeserver has is correct.
 
+
         Currently this is only called by the homeserver as a direct result of
         the application service calling
-        [`POST /_matrix/client/v1/appservice/{appserviceId}/ping`](#post_matrixclientv1appserviceappserviceidping).
+        [`POST /_matrix/client/v1/appservice/{appserviceId}/ping`].
+
+
+        [`POST /_matrix/client/v1/appservice/{appserviceId}/ping`]:
+          <#post_matrixclientv1appserviceappserviceidping>
       operationId: ping
       security:
         - homeserverAccessToken: []
@@ -41,13 +46,14 @@ paths:
               properties:
                 transaction_id:
                   type: string
-                  description: |-
+                  description: >-
                     A transaction ID for the ping, copied directly from the
                     `POST /_matrix/client/v1/appservice/{appserviceId}/ping` call.
         description: Ping body with optional transaction ID.
       responses:
         "200":
-          description: The provided `hs_token` is valid and the ping request was successful.
+          description: >-
+            The provided `hs_token` is valid and the ping request was successful.
           content:
             application/json:
               schema:

data/api/application-service/protocols.yaml

@@ -20,10 +20,10 @@ paths:
     get:
       summary: Retrieve metadata about a specific protocol that the application
         service supports.
-      description: |-
+      description: >-
         This API is called by the homeserver when it wants to present clients
-        with specific information about the various third-party networks that
+        with specific information about the various third-party networks that an
-        an application service supports.
+        application service supports.
       operationId: getProtocolMetadata
       security:
         - homeserverAccessToken: []
@@ -43,9 +43,10 @@ paths:
               schema:
                 $ref: definitions/protocol.yaml
         "401":
-          description: |-
+          description: >-
-            The homeserver has not supplied credentials to the application service.
+            The homeserver has not supplied credentials to the application
-            Optional error information can be included in the body of this response.
+            service. Optional error information can be included in the body of
+            this response.
           content:
             application/json:
               schema:
@@ -80,10 +81,10 @@ paths:
   "/thirdparty/user/{protocol}":
     get:
       summary: Retrieve the Matrix User ID of a corresponding third-party user.
-      description: |-
+      description: >-
-        This API is called by the homeserver in order to retrieve a Matrix
+        This API is called by the homeserver in order to retrieve a Matrix User
-        User ID linked to a user on the third-party network, given a set of
+        ID linked to a user on the third-party network, given a set of user
-        user parameters.
+        parameters.
       operationId: queryUserByProtocol
       security:
         - homeserverAccessToken: []
@@ -97,9 +98,9 @@ paths:
             type: string
         - in: query
           name: fields
-          description: |-
+          description: >-
-            One or more custom fields that are passed to the application
+            One or more custom fields that are passed to the application service
-            service to help identify the user.
+            to help identify the user.
           schema:
             type: object
             additionalProperties:
@@ -112,9 +113,10 @@ paths:
               schema:
                 $ref: definitions/user_batch.yaml
         "401":
-          description: |-
+          description: >-
-            The homeserver has not supplied credentials to the application service.
+            The homeserver has not supplied credentials to the application
-            Optional error information can be included in the body of this response.
+            service. Optional error information can be included in the body of
+            this response.
           content:
             application/json:
               schema:
@@ -149,7 +151,8 @@ paths:
   "/thirdparty/location/{protocol}":
     get:
       summary: Retrieve Matrix-side portal rooms leading to a third-party location.
-      description: Retrieve a list of Matrix portal rooms that lead to the matched
+      description: >-
+        Retrieve a list of Matrix portal rooms that lead to the matched
         third-party location.
       operationId: queryLocationByProtocol
       security:
@@ -164,9 +167,9 @@ paths:
             type: string
         - in: query
           name: fields
-          description: |-
+          description: >-
-            One or more custom fields that are passed to the application
+            One or more custom fields that are passed to the application service
-            service to help identify the third-party location.
+            to help identify the third-party location.
           schema:
             type: object
             additionalProperties:
@@ -179,9 +182,10 @@ paths:
               schema:
                 $ref: definitions/location_batch.yaml
         "401":
-          description: |-
+          description: >-
-            The homeserver has not supplied credentials to the application service.
+            The homeserver has not supplied credentials to the application
-            Optional error information can be included in the body of this response.
+            service. Optional error information can be included in the body of
+            this response.
           content:
             application/json:
               schema:
@@ -216,9 +220,8 @@ paths:
   /thirdparty/location:
     get:
       summary: Reverse-lookup third-party locations given a Matrix room alias.
-      description: |-
+      description: >-
-        Retrieve an array of third-party network locations from a Matrix room
+        Retrieve an array of third-party network locations from a Matrix room alias.
-        alias.
       operationId: queryLocationByAlias
       security:
         - homeserverAccessToken: []
@@ -236,9 +239,10 @@ paths:
               schema:
                 $ref: definitions/location_batch.yaml
         "401":
-          description: |-
+          description: >-
-            The homeserver has not supplied credentials to the application service.
+            The homeserver has not supplied credentials to the application
-            Optional error information can be included in the body of this response.
+            service. Optional error information can be included in the body of
+            this response.
           content:
             application/json:
               schema:
@@ -291,9 +295,10 @@ paths:
               schema:
                 $ref: definitions/user_batch.yaml
         "401":
-          description: |-
+          description: >-
-            The homeserver has not supplied credentials to the application service.
+            The homeserver has not supplied credentials to the application
-            Optional error information can be included in the body of this response.
+            service. Optional error information can be included in the body of
+            this response.
           content:
             application/json:
               schema:

data/api/application-service/query_room.yaml

@@ -20,12 +20,12 @@ paths:
   "/rooms/{roomAlias}":
     get:
       summary: Query if a room alias should exist on the application service.
-      description: |-
+      description: >-
-        This endpoint is invoked by the homeserver on an application service to query
+        This endpoint is invoked by the homeserver on an application service to
-        the existence of a given room alias. The homeserver will only query room
+        query the existence of a given room alias. The homeserver will only
-        aliases inside the application service's `aliases` namespace. The
+        query room aliases inside the application service's `aliases` namespace.
-        homeserver will send this request when it receives a request to join a
+        The homeserver will send this request when it receives a request to join
-        room alias within the application service's namespace.
+        a room alias within the application service's namespace.
       operationId: queryRoomByAlias
       security:
         - homeserverAccessToken: []
@@ -39,7 +39,7 @@ paths:
             type: string
       responses:
         "200":
-          description: |-
+          description: >-
             The application service indicates that this room alias exists. The
             application service MUST have created a room and associated it with
             the queried room alias using the client-server API. Additional
@@ -53,9 +53,10 @@ paths:
                 response:
                   value: {}
         "401":
-          description: |-
+          description: >-
-            The homeserver has not supplied credentials to the application service.
+            The homeserver has not supplied credentials to the application
-            Optional error information can be included in the body of this response.
+            service. Optional error information can be included in the body of
+            this response.
           content:
             application/json:
               schema:
@@ -77,9 +78,10 @@ paths:
                     "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
                   }
         "404":
-          description: |-
+          description: >-
-            The application service indicates that this room alias does not exist.
+            The application service indicates that this room alias does not
-            Optional error information can be included in the body of this response.
+            exist. Optional error information can be included in the body of
+            this response.
           content:
             application/json:
               schema:

data/api/application-service/query_user.yaml

@@ -20,12 +20,13 @@ paths:
   "/users/{userId}":
     get:
       summary: Query if a user should exist on the application service.
-      description: |-
+      description: >-
-        This endpoint is invoked by the homeserver on an application service to query
+        This endpoint is invoked by the homeserver on an application service to
-        the existence of a given user ID. The homeserver will only query user IDs
+        query the existence of a given user ID. The homeserver will only query
-        inside the application service's `users` namespace. The homeserver will
+        user IDs inside the application service's `users` namespace. The
-        send this request when it receives an event for an unknown user ID in
+        homeserver will send this request when it receives an event for an
-        the application service's namespace, such as a room invite.
+        unknown user ID in the application service's namespace, such as a room
+        invite.
       operationId: queryUserById
       security:
         - homeserverAccessToken: []
@@ -39,9 +40,9 @@ paths:
             type: string
       responses:
         "200":
-          description: |-
+          description: >-
-            The application service indicates that this user exists. The application
+            The application service indicates that this user exists. The
-            service MUST create the user using the client-server API.
+            application service MUST create the user using the client-server API.
           content:
             application/json:
               schema:
@@ -50,9 +51,10 @@ paths:
                 response:
                   value: {}
         "401":
-          description: |-
+          description: >-
-            The homeserver has not supplied credentials to the application service.
+            The homeserver has not supplied credentials to the application
-            Optional error information can be included in the body of this response.
+            service. Optional error information can be included in the body of
+            this response.
           content:
             application/json:
               schema:
@@ -74,9 +76,10 @@ paths:
                     "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
                   }
         "404":
-          description: |-
+          description: >-
             The application service indicates that this user does not exist.
-            Optional error information can be included in the body of this response.
+            Optional error information can be included in the body of this
+            response.
           content:
             application/json:
               schema:

data/api/application-service/transactions.yaml

@@ -20,20 +20,21 @@ paths:
   "/transactions/{txnId}":
     put:
       summary: Send some events to the application service.
-      description: |-
+      description: >-
-        This API is called by the homeserver when it wants to push an event
+        This API is called by the homeserver when it wants to push an event (or
-        (or batch of events) to the application service.
+        batch of events) to the application service.
 
-        Note that the application service should distinguish state events
+
-        from message events via the presence of a `state_key`, rather than
+        Note that the application service should distinguish state events from
-        via the event type.
+        message events via the presence of a `state_key`, rather than via the
+        event type.
       operationId: sendTransaction
       security:
         - homeserverAccessToken: []
       parameters:
         - in: path
           name: txnId
-          description: |-
+          description: >-
             The transaction ID for this set of events. Homeservers generate
             these IDs and they are used to ensure idempotency of requests.
           required: true
@@ -73,15 +74,19 @@ paths:
                 ephemeral:
                   type: array
                   x-addedInMatrixVersion: "1.13"
-                  description: |-
+                  description: >-
-                    A list of ephemeral data, if the `receive_ephemeral` setting was enabled in the
+                    A list of ephemeral data, if the `receive_ephemeral` setting
+                    was enabled in the
                     [registration](/application-service-api/#registration) file.
 
-                    There are only three event types that can currently occur in this list: `m.presence`,
+
-                    `m.typing`, and `m.receipt`. Room-scoped ephemeral data (`m.typing` and
+                    There are only three event types that can currently occur in
-                    `m.receipt`) MUST include a `room_id` property to identify the room that they
+                    this list: `m.presence`, `m.typing`, and `m.receipt`.
+                    Room-scoped ephemeral data (`m.typing` and `m.receipt`) MUST
+                    include a `room_id` property to identify the room that they
                     were sent in.
 
+
                     This property can be omitted if it would be empty.
                   items:
                     $ref: ../../event-schemas/schema/core-event-schema/event.yaml

data/api/client-server/third_party_membership.yaml

@@ -57,9 +57,6 @@ paths:
         - A signature of the token, signed with the identity server's private key
 
         - The matrix user ID who invited them to the room
-
-        If a token is requested from the identity server, the homeserver will
-        append a `m.room.third_party_invite` event to the room.
       operationId: inviteBy3PID
       security:
         - accessTokenQuery: []
@@ -72,6 +69,8 @@ paths:
           example: "!d41d8cd:matrix.org"
           schema:
             type: string
+            format: mx-room-id
+            pattern: "^!"
       requestBody:
         content:
           application/json:
@@ -90,7 +89,9 @@ paths:
                   value: {}
         "403":
           description: |-
-            You do not have permission to invite the user to the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are:
+            You do not have permission to invite the user to the room. A
+            meaningful `errcode` and description error text will be returned.
+            Example reasons for rejections are:
 
             - The invitee has been banned from the room.
             - The invitee is already a member of the room.

data/api/identity/v2_pubkey.yaml

@@ -43,7 +43,8 @@ paths:
                 properties:
                   public_key:
                     type: string
-                    description: Unpadded Base64 encoded public key.
+                    description: |-
+                      [Unpadded Base64](/appendices/#unpadded-base64)-encoded public key.
                 required:
                   - public_key
               examples:
@@ -74,7 +75,8 @@ paths:
         - in: query
           name: public_key
           required: true
-          description: The unpadded base64-encoded public key to check.
+          description: |-
+            The [unpadded Base64](/appendices/#unpadded-base64)-encoded public key to check.
           example: VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c
           schema:
             type: string
@@ -105,7 +107,14 @@ paths:
         - in: query
           name: public_key
           required: true
-          description: The unpadded base64-encoded public key to check.
+          description: |-
+            The [unpadded Base64](/appendices/#unpadded-base64)-encoded public
+            key to check.
+
+            This MUST be the exact same encoded string returned in the response
+            of the [`/store-invite`](/identity-service-api/#post_matrixidentityv2store-invite)
+            endpoint, or found in the corresponding [`m.room.third_party_invite`](/client-server-api/#mroomthird_party_invite)
+            event, so it may use the standard or URL-safe alphabets.
           example: VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c
           schema:
             type: string

data/api/identity/v2_store_invite.yaml

@@ -42,7 +42,7 @@ paths:
         (if present) from the request here.
 
         Also, the generated ephemeral public key will be listed as valid on
-        requests to `/_matrix/identity/v2/pubkey/ephemeral/isvalid`.
+        requests to [`/_matrix/identity/v2/pubkey/ephemeral/isvalid`](/identity-service-api/#get_matrixidentityv2pubkeyephemeralisvalid).
 
         Currently, invites may only be issued for 3pids of the `email` medium.
 
@@ -70,10 +70,14 @@ paths:
                 room_id:
                   type: string
                   description: The Matrix room ID to which the user is invited
+                  format: mx-room-id
+                  pattern: "^!"
                   example: "!something:example.org"
                 sender:
                   type: string
                   description: The Matrix user ID of the inviting user
+                  format: mx-user-id
+                  pattern: "^@"
                   example: "@bob:example.com"
                 room_alias:
                   type: string
@@ -81,12 +85,16 @@ paths:
                     The Matrix room alias for the room to which the user is
                     invited. This should be retrieved from the `m.room.canonical_alias`
                     state event.
+                  format: mx-room-alias
+                  pattern: "^#"
                   example: "#somewhere:example.org"
                 room_avatar_url:
                   type: string
                   description: |-
                     The Content URI for the room to which the user is invited. This should
                     be retrieved from the `m.room.avatar` state event.
+                  format: mx-mxc-uri
+                  pattern: "^mxc:\\/\\/"
                   example: mxc://example.org/s0meM3dia
                 room_join_rules:
                   type: string
@@ -108,6 +116,8 @@ paths:
                   type: string
                   description: The Content URI for the avatar of the user ID initiating the
                     invite.
+                  format: mx-mxc-uri
+                  pattern: "^mxc:\\/\\/"
                   example: mxc://example.org/an0th3rM3dia
                 room_type:
                   type: string
@@ -146,7 +156,7 @@ paths:
                         public_key:
                           type: string
                           description: |
-                            The public key, encoded using [unpadded Base64](/appendices/#unpadded-base64).
+                            The public key, encoded using standard or URL-safe [unpadded Base64](/appendices/#unpadded-base64).
                         key_validity_url:
                           type: string
                           description: |

data/api/server-server/third_party_invite.yaml

@@ -35,6 +35,8 @@ paths:
           example: "!abc123:matrix.org"
           schema:
             type: string
+            format: mx-room-id
+            pattern: "^!"
       requestBody:
         content:
           application/json:
@@ -50,16 +52,22 @@ paths:
                   description: |-
                     The room ID the event is for. Must match the ID given in
                     the path.
+                    format: mx-room-id
+                    pattern: "^!"
                   example: "!abc123:matrix.org"
                 sender:
                   type: string
                   description: |-
                     The user ID of the user who sent the original `m.room.third_party_invite`
                     event.
+                  format: mx-user-id
+                  pattern: "^@"
                   example: "@joe:matrix.org"
                 state_key:
                   type: string
                   description: The user ID of the invited user
+                  format: mx-user-id
+                  pattern: "^@"
                   example: "@someone:example.org"
                 content:
                   type: object
@@ -82,45 +90,7 @@ paths:
                             third-party identifier.
                           example: alice
                         signed:
-                          type: object
+                          $ref: ../../event-schemas/schema/components/signed_third_party_invite.yaml
-                          description: |-
-                            A block of content which has been signed, which servers can use to
-                            verify the event.
-                          title: Invite Signatures
-                          properties:
-                            signatures:
-                              type: object
-                              title: Signatures
-                              additionalProperties:
-                                type: object
-                                additionalProperties:
-                                  type: string
-                              description: |-
-                                The server signatures for this event.
-
-                                The signature is calculated using the process
-                                described at [Signing JSON](/appendices/#signing-json).
-                              example:
-                                magic.forest:
-                                  ed25519:3: fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg
-                            mxid:
-                              type: string
-                              description: The invited matrix user ID
-                              example: "@alice:localhost"
-                            token:
-                              type: string
-                              description: The token used to verify the event
-                              example: abc123
-                          required:
-                            - signatures
-                            - mxid
-                            - token
-                          example:
-                            mxid: "@alice:localhost"
-                            token: abc123
-                            signatures:
-                              magic.forest:
-                                ed25519:3: fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg
                       required:
                         - display_name
                         - signed
@@ -215,6 +185,8 @@ paths:
                 mxid:
                   type: string
                   description: The user that is now bound to the third-party identifier.
+                  format: mx-user-id
+                  pattern: "^@"
                   example: "@alice:matrix.org"
                 invites:
                   type: array
@@ -237,59 +209,23 @@ paths:
                       mxid:
                         type: string
                         description: The now-bound user ID that received the invite.
+                        format: mx-user-id
+                        pattern: "^@"
                         example: "@alice:matrix.org"
                       room_id:
                         type: string
                         description: The room ID the invite is valid for.
+                        format: mx-room-id
+                        pattern: "^!"
                         example: "!somewhere:example.org"
                       sender:
                         type: string
                         description: The user ID that sent the invite.
+                        format: mx-user-id
+                        pattern: "^@"
                         example: "@bob:matrix.org"
-                      # TODO (TravisR): Make this reusable when doing IS spec changes
-                      #   also make sure it isn't lying about anything, like the key version
                       signed:
-                        type: object
+                        $ref: ../../event-schemas/schema/components/signed_third_party_invite.yaml
-                        title: Identity Server Signatures
-                        description: |-
-                          Signature from the identity server using a long-term private
-                          key.
-                        properties:
-                          mxid:
-                            type: string
-                            description: |-
-                              The user ID that has been bound to the third-party
-                              identifier.
-                            example: "@alice:matrix.org"
-                          token:
-                            type: string
-                            # TODO: What is this actually?
-                            description: A token.
-                            example: Hello World
-                          signatures:
-                            type: object
-                            title: Identity Server Signature
-                            description: |-
-                              The signature from the identity server. The `string` key
-                              is the identity server's domain name, such as vector.im
-                            additionalProperties:
-                              type: object
-                              title: Identity Server Domain Signature
-                              description: The signature for the identity server.
-                              properties:
-                                ed25519:0:
-                                  type: string
-                                  description: The signature.
-                                  example: SomeSignatureGoesHere
-                              required:
-                                - ed25519:0
-                            example:
-                              vector.im:
-                                ed25519:0: SomeSignatureGoesHere
-                        required:
-                          - mxid
-                          - token
-                          - signatures
                     required:
                       - medium
                       - address

data/event-schemas/schema/components/signed_third_party_invite.yaml

@@ -0,0 +1,45 @@
+title: SignedThirdPartyInvite
+description: |-
+  A block of content which has been signed by the identity server, which
+  homeservers can use to verify the event. Clients should ignore this.
+type: object
+properties:
+  mxid:
+    description: |-
+      The user ID that has been bound to the third-party identifier.
+    type: string
+    format: mx-user-id
+    pattern: "^@"
+    example: "@alice:example.org"
+  signatures:
+    title: IdentityServerSignatures
+    description: |-
+      The identity server signatures for this block. This is a map of identity
+      server name to signing key identifier to base64-encoded signature.
+
+      The signatures are calculated using the process described at
+      [Signing JSON](/appendices/#signing-json).
+    type: object
+    additionalProperties:
+      type: object
+      additionalProperties:
+        type: string
+    example: {
+      "magic.forest": {
+        "ed25519:3": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg"
+      }
+    }
+  token:
+    description: |-
+      The token generated by the identity server at the
+      [`/store_invite`](/identity-service-api/#post_matrixidentityv2store-invite)
+      endpoint.
+
+      It matches the `state_key` of the corresponding [`m.room.third_party_invite`](/client-server-api/#mroomthird_party_invite)
+      event.
+    type: string
+    example: "abc123"
+required:
+  - mxid
+  - signatures
+  - token

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

@@ -2,17 +2,27 @@
 allOf:
   - $ref: core-event-schema/state_event.yaml
 description: |-
-  Adjusts the membership state for a user in a room. It is preferable to use the membership APIs (`/rooms/<room id>/invite` etc) when performing membership actions rather than adjusting the state directly as there are a restricted set of valid transformations. For example, user A cannot force user B to join a room, and trying to force this state change directly will fail.
+  Adjusts the membership state for a user in a room. It is preferable to use the membership APIs
+  (`/rooms/<room id>/invite` etc) when performing membership actions rather than adjusting the
+  state directly as there are a restricted set of valid transformations. For example, user A cannot
+  force user B to join a room, and trying to force this state change directly will fail.
 
   The following membership states are specified:
 
-  - `invite` - The user has been invited to join a room, but has not yet joined it. They may not participate in the room until they join.
+  - `invite` - The user has been invited to join a room, but has not yet joined it. They may not
-  - `join` - The user has joined the room (possibly after accepting an invite), and may participate in it.
+    participate in the room until they join.
-  - `leave` - The user was once joined to the room, but has since left (possibly by choice, or possibly by being kicked).
+  - `join` - The user has joined the room (possibly after accepting an invite), and may participate
-  - `ban` - The user has been banned from the room, and is no longer allowed to join it until they are un-banned from the room (by having their membership state set to a value other than `ban`).
+    in it.
-  - `knock` - The user has knocked on the room, requesting permission to participate. They may not participate in the room until they join.
+  - `leave` - The user was once joined to the room, but has since left (possibly by choice, or
+    possibly by being kicked).
+  - `ban` - The user has been banned from the room, and is no longer allowed to join it until they
+    are un-banned from the room (by having their membership state set to a value other than `ban`).
+  - `knock` - The user has knocked on the room, requesting permission to participate. They may not
+    participate in the room until they join.
 
-  The `third_party_invite` property will be set if this invite is an `invite` event and is the successor of an `m.room.third_party_invite` event, and absent otherwise.
+  The `third_party_invite` property will be set if this invite is an `invite` event and is the
+  successor of an [`m.room.third_party_invite`](/client-server-api/#mroomthird_party_invite) event,
+  and absent otherwise.
 
   This event may also include an `invite_room_state` key inside the event's `unsigned` data.
   If present, this contains an array of [stripped state events](/client-server-api/#stripped-state)
@@ -57,63 +67,54 @@ properties:
           - ban
         type: string
       is_direct:
-        description: Flag indicating if the room containing this event was created with the intention of being a direct chat. See [Direct Messaging](/client-server-api/#direct-messaging).
+        description: |-
+          Flag indicating if the room containing this event was created with the intention of being
+          a direct chat. See [Direct Messaging](/client-server-api/#direct-messaging).
         type: boolean
       join_authorised_via_users_server:
         x-addedInMatrixVersion: "1.2"
         type: string
         description: |-
-          Usually found on `join` events, this field is used to denote which homeserver (through representation of a user with sufficient power level)
+          Usually found on `join` events, this field is used to denote which homeserver (through
-          authorised the user's join. More information about this field can be found in the [Restricted Rooms Specification](/client-server-api/#restricted-rooms).
+          representation of a user with sufficient power level) authorised the user's join. More
+          information about this field can be found in the [Restricted Rooms Specification](/client-server-api/#restricted-rooms).
 
-          Client and server implementations should be aware of the [signing implications](/rooms/v8/#authorization-rules) of including this
+          Client and server implementations should be aware of the [signing implications](/rooms/v8/#authorization-rules)
-          field in further events: in particular, the event must be signed by the server which
+          of including this field in further events: in particular, the event must be signed by the
-          owns the user ID in the field. When copying the membership event's `content`
+          server which owns the user ID in the field. When copying the membership event's `content`
-          (for profile updates and similar) it is therefore encouraged to exclude this
+          (for profile updates and similar) it is therefore encouraged to exclude this field in the
-          field in the copy, as otherwise the event might fail event authorization.
+          copy, as otherwise the event might fail event authorization.
       reason:
         x-addedInMatrixVersion: "1.1"
         type: string
         description: |-
-          Optional user-supplied text for why their membership has changed. For kicks and bans, this is typically the reason for the kick or ban.
+          Optional user-supplied text for why their membership has changed. For kicks and bans,
-          For other membership changes, this is a way for the user to communicate their intent without having to send a message to the room, such
+          this is typically the reason for the kick or ban. For other membership changes, this is a
-          as in a case where Bob rejects an invite from Alice about an upcoming concert, but can't make it that day.
+          way for the user to communicate their intent without having to send a message to the
+          room, such as in a case where Bob rejects an invite from Alice about an upcoming concert,
+          but can't make it that day.
 
-          Clients are not recommended to show this reason to users when receiving an invite due to the potential for spam and abuse. Hiding the
+          Clients are not recommended to show this reason to users when receiving an invite due to
-          reason behind a button or other component is recommended.
+          the potential for spam and abuse. Hiding the reason behind a button or other component is
+          recommended.
       third_party_invite:
+        title: ThirdPartyInvite
+        description: |-
+          A third-party invite, if this `m.room.member` is the successor to an
+          [`m.room.third_party_invite`](/client-server-api/#mroomthird_party_invite)
+          event.
+        type: object
         properties:
           display_name:
-            description: A name which can be displayed to represent the user instead of their third-party identifier
+            description: |-
+              A name which can be displayed to represent the user instead of their
+              third-party identifier
             type: string
           signed:
-            description: 'A block of content which has been signed, which servers can use to verify the event. Clients should ignore this.'
+            $ref: components/signed_third_party_invite.yaml
-            properties:
-              mxid:
-                description: The invited matrix user ID. Must be equal to the user_id property of the event.
-                type: string
-              signatures:
-                description: 'A single signature from the verifying server, in the format specified by the Signing Events section of the server-server API.'
-                title: Signatures
-                type: object
-                additionalProperties:
-                  type: object
-                  additionalProperties:
-                    type: string
-              token:
-                description: The token property of the containing third_party_invite object.
-                type: string
-            required:
-              - mxid
-              - signatures
-              - token
-            title: signed
-            type: object
         required:
           - display_name
           - signed
-        title: Invite
-        type: object
     required:
       - membership
     title: EventContent

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

@@ -1,28 +1,56 @@
 ---
 allOf:
   - $ref: core-event-schema/state_event.yaml
-description: "Acts as an `m.room.member` invite event, where there isn't a target user_id to invite. This event contains a token and a public key whose private key must be used to sign the token. Any user who can present that signature may use this invitation to join the target room."
+description: |-
+  Acts as an `m.room.member` invite event, where there isn't a target user_id to
+  invite. This event contains a token and a public key whose private key must be
+  used to sign the token. Any user who can present that signature may use this
+  invitation to join the target room.
 properties:
   content:
     properties:
       display_name:
-        description: "A user-readable string which represents the user who has been invited. This should not contain the user's third-party ID, as otherwise when the invite is accepted it would leak the association between the matrix ID and the third-party ID."
+        description: |-
+          A user-readable string which represents the user who has been invited.
+          This should not contain the user's third-party ID, as otherwise when
+          the invite is accepted it would leak the association between the
+          matrix ID and the third-party ID.
         type: string
       key_validity_url:
-        description: "A URL which can be fetched, with querystring public_key=public_key, to validate whether the key has been revoked. The URL must return a JSON object containing a boolean property named 'valid'."
+        description: |-
+          A URL which can be fetched, with querystring public_key=public_key, to
+          validate whether the key has been revoked. The URL must return a JSON
+          object containing a boolean property named 'valid'.
         type: string
+        format: uri
       public_key:
-        description: A base64-encoded ed25519 key with which token must be signed (though a signature from any entry in public_keys is also sufficient). This exists for backwards compatibility.
+        description: |-
+          An Ed25519 key with which the token must be signed (though a signature
+          from any entry in `public_keys` is also sufficient).
+
+          The key is encoded using [Unpadded Base64](/appendices/#unpadded-base64),
+          using the standard or URL-safe alphabets.
+
+          This exists for backwards compatibility.
         type: string
       public_keys:
         description: Keys with which the token may be signed.
         items:
           properties:
             key_validity_url:
-              description: "An optional URL which can be fetched, with querystring public_key=public_key, to validate whether the key has been revoked. The URL must return a JSON object containing a boolean property named 'valid'. If this URL is absent, the key must be considered valid indefinitely."
+              description: |-
+                An optional URL which can be fetched, with querystring
+                `public_key=<public_key>`, to validate whether the key has been
+                revoked. The URL must return a JSON object containing a boolean
+                property named `valid`. If this URL is absent, the key must be
+                considered valid indefinitely.
               type: string
             public_key:
-              description: A base-64 encoded ed25519 key with which token may be signed.
+              description: |-
+                An Ed25519 key with which the token may be signed.
+
+                The key is encoded using [Unpadded Base64](/appendices/#unpadded-base64),
+                using the standard or URL-safe alphabets.
               type: string
           required:
             - public_key
@@ -35,11 +63,15 @@ properties:
       - public_key
     type: object
   state_key:
-    description: 'The token, of which a signature must be produced in order to join the room.'
+    description: |-
+      The token, of which a signature must be produced in order to join the
+      room.
     type: string
   type:
     enum:
       - m.room.third_party_invite
     type: string
-title: 'An invitation to a room issued to a third-party identifier, rather than a matrix user ID.'
+title: |-
+  An invitation to a room issued to a third-party identifier, rather than a
+  matrix user ID.
 type: object

data/string-formats.yaml

@@ -51,6 +51,11 @@ mx-room-id:
   url: appendices#room-ids
   # regex: "^!"
 
+mx-room-alias:
+  title: Room Alias
+  url: appendices#room-aliases
+  # regex: "^#"
+
 mx-server-name:
   title: Server Name
   url: appendices#server-name