From 4282a1a319362cf8dca6948ef77b1a6b3a464a27 Mon Sep 17 00:00:00 2001
From: Sumner Evans <sumner.evans@automattic.com>
Date: Fri, 7 Jun 2024 11:19:35 -0600
Subject: [PATCH] e2ee/device verification start: clarify required nature of
 transaction_id or m.relates_to

Add notes about the fact that the start event *may* be the first event
sent during a verification process and that clients should handle other
clients doing so, but not themselves send the start event first.

Signed-off-by: Sumner Evans <sumner.evans@automattic.com>
---
 .../schema/m.key.verification.start.yaml      | 50 ++++++++++++++++---
 1 file changed, 44 insertions(+), 6 deletions(-)

diff --git a/data/event-schemas/schema/m.key.verification.start.yaml b/data/event-schemas/schema/m.key.verification.start.yaml
index ef862ffc..70cb86c3 100644
--- a/data/event-schemas/schema/m.key.verification.start.yaml
+++ b/data/event-schemas/schema/m.key.verification.start.yaml
@@ -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