e2ee/device verification: clarifications

changelogs/client_server/newsfragments/1830.clarification

@@ -0,0 +1 @@
+Clarify a few things in the Device Verification section and improve links throughout the section.

data/event-schemas/schema/m.key.verification.cancel.yaml

@@ -31,26 +31,30 @@ properties:
           * `m.user`: The user cancelled the verification.
 
           * `m.timeout`: The verification process timed out. Verification processes
-          can define their own timeout parameters.
+            can define their own timeout parameters.
 
           * `m.unknown_transaction`: The device does not know about the given transaction
-          ID.
+            ID.
 
-          * `m.unknown_method`: The device does not know how to handle the requested
-          method. This should be sent for `m.key.verification.start` messages and
-          messages defined by individual verification processes.
+          * `m.unknown_method`: The device does not know how to handle the
+            requested method. This should be sent for
+            [`m.key.verification.start`](#mkeyverificationstart) messages and
+            messages defined by individual verification processes.
 
-          * `m.unexpected_message`: The device received an unexpected message. Typically
-          raised when one of the parties is handling the verification out of order.
+          * `m.unexpected_message`: The device received an unexpected message.
+            Typically raised when one of the parties is handling the
+            verification out of order.
 
           * `m.key_mismatch`: The key was not verified.
 
           * `m.user_mismatch`: The expected user did not match the user verified.
 
           * `m.invalid_message`: The message received was invalid.
 
-          * `m.accepted`: A `m.key.verification.request` was accepted by a different
-            device. The device receiving this error can ignore the verification request.
+          * `m.accepted`: A
+            [`m.key.verification.request`](#mkeyverificationrequest) was
+            accepted by a different device. The device receiving this error can
+            ignore the verification request.
 
           Clients should be careful to avoid error loops. For example, if a device sends
           an incorrect message and the client returns `m.invalid_message` to which it

data/event-schemas/schema/m.key.verification.m.relates_to.yaml

@@ -1,9 +1,9 @@
 ---
 description: |-
   Required when sent as an in-room message. Indicates the
-  `m.key.verification.request` that this message is related to. Note that for
-  encrypted messages, this property should be in the unencrypted portion of the
-  event.
+  [`m.key.verification.request`](#mkeyverificationrequest) that this message is
+  related to. Note that for encrypted messages, this property should be in the
+  unencrypted portion of the event.
 properties:
   rel_type:
     type: string
@@ -15,7 +15,8 @@ properties:
   event_id:
     type: string
     description: |-
-      The event ID of the `m.key.verification.request` that this message is
-      related to.
+      The event ID of the
+      [`m.key.verification.request`](#mkeyverificationrequest) that this
+      message is related to.
 type: object
 title: VerificationRelatesTo

data/event-schemas/schema/m.key.verification.ready.yaml

@@ -4,7 +4,7 @@ allOf:
 
 description: |-
   Accepts a key verification request. Sent in response to an
-  `m.key.verification.request` event.
+  [`m.key.verification.request`](#mkeyverificationrequest) event.
 properties:
   content:
     properties:
@@ -16,14 +16,14 @@ properties:
         type: string
         description: |-
           Required when sent as a to-device message. The transaction ID of the
-          verification request, as given in the `m.key.verification.request`
-          message.
+          verification request, as given in the
+          [`m.key.verification.request`](#mkeyverificationrequest) message.
       methods:
         type: array
         description: |-
           The verification methods supported by the sender, corresponding to
           the verification methods indicated in the
-          `m.key.verification.request` message.
+          [`m.key.verification.request`](#mkeyverificationrequest) message.
         items:
           type: string
       m.relates_to:

data/event-schemas/schema/m.key.verification.request.yaml

@@ -4,8 +4,9 @@ allOf:
 
 description: |-
   Requests a key verification using to-device messaging.  When requesting a key
-  verification in a room, a `m.room.message` should be used, with
-  [`m.key.verification.request`](#mroommessagemkeyverificationrequest) as msgtype.
+  verification in a room, a [`m.room.message`](#mroommessage should be used,
+  with [`m.key.verification.request`](#mroommessagemkeyverificationrequest) as
+  msgtype.
 properties:
   content:
     properties:

data/event-schemas/schema/m.key.verification.start.yaml

@@ -3,9 +3,9 @@ allOf:
   - $ref: core-event-schema/event.yaml
 
 description: |-
-  Begins a key verification process. Typically sent as a [to-device](/client-server-api/#send-to-device-messaging) event. The `method`
-  field determines the type of verification. The fields in the event will differ depending
-  on the `method`. This definition includes fields that are in common among all variants.
+  Begins a key verification process. The `method` field determines the type of
+  verification. The fields in the event will differ depending on the `method`.
+  This definition includes fields that are in common among all variants.
 properties:
   content:
     properties:
@@ -16,11 +16,20 @@ properties:
       transaction_id:
         type: string
         description: |-
-          Required when sent as a to-device message. An opaque identifier for
-          the verification process. Must be unique with respect to the devices
-          involved. Must be the same as the `transaction_id` given in the
-          `m.key.verification.request` if this process is originating from a
-          request.
+          Required when sent as a to-device message unless the start event is
+          sent without a corresponding
+          [`m.key.verification.request`](#mkeyverificationrequest).
+
+          An opaque identifier for the verification process. Must be unique
+          with respect to the devices involved.
+
+          Must be the same as the `transaction_id` given in the
+          [`m.key.verification.request`](#mkeyverificationrequest) if this
+          process is originating from a request.
+
+          Note that sending a start event without a request is deprecated, and
+          clients should not send a start event without first sending a request
+          event, but clients should handle other clients doing so.
       method:
         type: string
         description: |-
@@ -32,7 +41,36 @@ properties:
           when the `method` chosen only verifies one user's key. This field will
           never be present if the `method` verifies keys both ways.
       m.relates_to:
-        $ref: m.key.verification.m.relates_to.yaml
+        description: |-
+          Required when sent as an in-room message unless the start event is
+          sent without a corresponding
+          [`m.key.verification.request`](#mkeyverificationrequest).
+
+          Indicates the
+          [`m.key.verification.request`](#mkeyverificationrequest) that this
+          message is related to. Note that for encrypted messages, this
+          property should be in the unencrypted portion of the event.
+
+          Note that sending a start event without a request is deprecated, and
+          clients should not send a start event without first sending a request
+          event, but clients should handle other clients doing so.
+        properties:
+          rel_type:
+            type: string
+            enum:
+              - m.reference
+            description: |-
+              The relationship type. Currently, this can only be an
+              [`m.reference`](/client-server-api/#reference-relations)
+              relationship type.
+          event_id:
+            type: string
+            description: |-
+              The event ID of the
+              [`m.key.verification.request`](#mkeyverificationrequest) that
+              this message is related to.
+        type: object
+        title: VerificationRelatesTo
     required:
       - from_device
       - method