more clarifications, and move event definitions to yaml

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