more clarifications, and move event definitions to yaml

changelogs/client_server/newsfragments/1294.clarification

@@ -0,0 +1 @@
+Clarify parts of the end-to-end encryption sections.

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

@@ -510,6 +510,15 @@ could also send that message. As well, the order of the
             |                 |                                   |               |
 ```
 
+In contrast with the case of using to-devices messages, when using in-room
+messages, Alice only sends one request event (an event with type
+`m.room.message` with `msgtype: m.key.verification.request`, rather than an
+event with type `m.key.verification.request`), to the room. In addition, Alice
+does not send an `m.key.verification.cancel` event to tell Bob's other devices
+that the request as already been accepted; instead, when Bob's other devices
+see his `m.key.verification.ready` event, they will know that the request has
+already been accepted, and that they should ignore the request.
+
 When using in-room messages and the room has encryption enabled, clients should
 ensure that encryption does not hinder the verification. For example, if the
 verification messages are encrypted, clients must ensure that all the

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

@@ -292,49 +292,6 @@ confirm sharing the secret.
 
 ##### Event definitions
 
-###### `m.secret.request`
+{{% event event="m.secret.request" %}}
 
-Sent by a client to request a secret from another device or to cancel a
-previous request. It is sent as an unencrypted to-device event.
-
-| Parameter             | Type   | Description                                                                            |
-|-----------------------|--------|----------------------------------------------------------------------------------------|
-| name                  | string | Required if ``action`` is ``request``. The name of the secret that is being requested. |
-| action                | enum   | **Required.** One of ["request", "request_cancellation"].                              |
-| requesting_device_id  | string | **Required.** The ID of the device requesting the secret.                              |
-| request_id            | string | **Required.** A random string uniquely identifying (with respect to the requester and the target) the target for a secret. If the secret is requested from multiple devices at the same time, the same ID may be used for every target. The same ID is also used in order to cancel a previous request.                                                  |
-
-Example:
-
-```json
-{
-  "name": "org.example.some.secret",
-  "action": "request",
-  "requesting_device_id": "ABCDEFG",
-  "request_id": "randomly_generated_id_9573"
-}
-```
-
-###### `m.secret.send`
-
-Sent by a client to share a secret with another device, in response to an
-`m.secret.request` event. It must be encrypted as an `m.room.encrypted` event
-using [Olm](#molmv1curve25519-aes-sha2), then sent as a to-device event.
-
-The `request_id` must match the ID previously given in an `m.secret.request`
-event, and this event must come from a device that the `m.secret.request` event
-was originally sent to.  
-
-| Parameter   | Type   | Description                                                  |
-|-------------|--------|--------------------------------------------------------------|
-| request_id  | string | **Required.** The ID of the request that this a response to. |
-|  secret     | string | **Required.** The contents of the secret.                    |
-
-Example:
-
-```json
-{
-  "request_id": "randomly_generated_id_9573",
-  "secret": "ThisIsASecretDon'tTellAnyone"
-}
-```
+{{% event event="m.secret.send" %}}

data/event-schemas/examples/m.secret.request.yaml

@@ -0,0 +1,6 @@
+{
+  "name": "org.example.some.secret",
+  "action": "request",
+  "requesting_device_id": "ABCDEFG",
+  "request_id": "randomly_generated_id_9573"
+}

data/event-schemas/examples/m.secret.send.yaml

@@ -0,0 +1,4 @@
+{
+  "request_id": "randomly_generated_id_9573",
+  "secret": "ThisIsASecretDon'tTellAnyone"
+}

data/event-schemas/schema/m.secret.request.yaml

@@ -0,0 +1,40 @@
+---
+allOf:
+  - $ref: core-event-schema/event.yaml
+description: |-
+  Sent by a client to request a secret from another device or to cancel a
+  previous request. It is sent as an unencrypted to-device event.
+properties:
+  content:
+    properties:
+      name:
+        type: string
+        description: |-
+          Required if `action` is `request`. The name of the secret that is
+          being requested.
+      action:
+        type: string
+        enum:
+          - request
+          - request_cancellation
+      requesting_device_id:
+        type: string
+        description: |-
+          The ID of the device requesting the secret.
+      request_id:
+        type: string
+        description: |-
+          A random string uniquely identifying (with respect to the requester
+          and the target) the target for a secret. If the secret is requested
+          from multiple devices at the same time, the same ID may be used for
+          every target. The same ID is also used in order to cancel a previous
+          request.
+    required:
+      - action
+      - requesting_device_id
+      - request_id
+  type:
+    enum:
+      - m.secret.request
+    type: string
+type: object

data/event-schemas/schema/m.secret.send.yaml

@@ -0,0 +1,32 @@
+---
+allOf:
+  - $ref: core-event-schema/event.yaml
+description: |-
+  Sent by a client to share a secret with another device, in response to an
+  `m.secret.request` event. It must be encrypted as an `m.room.encrypted` event
+  using [Olm](#molmv1curve25519-aes-sha2), then sent as a to-device event.
+
+  The `request_id` must match the ID previously given in an `m.secret.request`
+  event. The recipient must ensure that this event comes from a device that the
+  `m.secret.request` event was originally sent to, and that the device is
+  trusted. This should be done by checking the sender key of the Olm session that
+  the event was sent over.
+properties:
+  content:
+    properties:
+      request_id:
+        type: string
+        description: |-
+          The ID of the request that this is a response to.
+      secret:
+        type: string
+        description: |-
+          The contents of the secret
+    required:
+      - request_id
+      - secret
+  type:
+    enum:
+      - m.secret.send
+    type: string
+type: object