add more clarifications

event-schemas/schema/core-event-schema/msgtype_infos/image_info.yaml

@@ -18,12 +18,14 @@ properties:
     description: Size of the image in bytes.
     type: integer
   thumbnail_url:
-    description: The URL to a thumbnail of the image.
+    description: |-
+      The URL to a thumbnail of the image. Only present if the
+      thumbnail is unencrypted.
     type: string
   thumbnail_file:
     description: |-
       Information on the encrypted thumbnail file, as specified in
-      |encrypted_files|_.
+      |encrypted_files|_. Only present if the thumbnail is encrypted.
     title: EncryptedFile
     type: object
   thumbnail_info:

event-schemas/schema/m.room.message#m.file

@@ -21,12 +21,14 @@ properties:
             description: The size of the file in bytes.
             type: integer
           thumbnail_url:
-            description: The URL to the thumbnail of the file.
+            description: |-
+              The URL to the thumbnail of the file. Only present if the
+              thumbnail is unencrypted.
             type: string
           thumbnail_file:
             description: |-
               Information on the encrypted thumbnail file, as specified in
-              |encrypted_files|_.
+              |encrypted_files|_. Only present if the thumbnail is encrypted.
             title: EncryptedFile
             type: object
           thumbnail_info:

event-schemas/schema/m.room.message#m.location

@@ -19,12 +19,14 @@ properties:
         type: object
         properties:
           thumbnail_url:
-            description: The URL to a thumbnail of the location being represented.
+            description: |-
+              The URL to the thumbnail of the file. Only present if the
+              thumbnail is unencrypted.
             type: string
           thumbnail_file:
             description: |-
               Information on the encrypted thumbnail file, as specified in
-              |encrypted_files|_.
+              |encrypted_files|_. Only present if the thumbnail is encrypted.
             title: EncryptedFile
             type: object
           thumbnail_info:

event-schemas/schema/m.room.message#m.video

@@ -27,12 +27,14 @@ properties:
             description: The size of the video in bytes.
             type: integer
           thumbnail_url:
-            description: The URL to an image thumbnail of the video clip.
+            description: |-
+              The URL to an image thumbnail of the video clip. Only present if the
+              thumbnail is unencrypted.
             type: string
           thumbnail_file:
             description: |-
               Information on the encrypted thumbnail file, as specified in
-              |encrypted_files|_.
+              |encrypted_files|_. Only present if the thumbnail is encrypted.
             title: EncryptedFile
             type: object
           thumbnail_info:

specification/modules/end_to_end_encryption.rst

@@ -262,9 +262,10 @@ extension`_.
 Extensions to ``m.message`` msgtypes
 <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
 
-This module adds ``file`` and ``thumbnail_file`` properties to ``m.message``
+This module adds ``file`` and ``thumbnail_file`` properties, of type
-msgtypes that reference files, such as ``m.file`` and ``m.image``, replacing
+``EncryptedFile``, to ``m.message`` msgtypes that reference files, such as
-the ``url`` and ``thumbnail_url`` properties.
+`m.file`_ and `m.image`_, replacing the ``url`` and ``thumbnail_url``
+properties.
 
 .. todo: generate this from a swagger definition?
 
@@ -273,16 +274,16 @@ the ``url`` and ``thumbnail_url`` properties.
 ========= ================ =====================================================
 Parameter Type             Description
 ========= ================ =====================================================
-url       string           The URL to the file.
+url       string           **Required.** The URL to the file.
-key       JWK              A `JSON Web Key`_ object.
+key       JWK              **Required.** A `JSON Web Key`_ object.
-iv        string           The Initialisation Vector used by AES-CTR, encoded as
+iv        string           **Required.** The Initialisation Vector used by
-                           unpadded base64.
+                           AES-CTR, encoded as unpadded base64.
-hashes    {string: string} A map from an algorithm name to a hash of the
+hashes    {string: string} **Required.** A map from an algorithm name to a hash
-                           ciphertext, encoded as unpadded base64. Clients
+                           of the ciphertext, encoded as unpadded base64. Clients
                            should support the SHA-256 hash, which uses the key
                            ``sha256``.
-v         string           Version of the encrypted attachments protocol. Must
+v         string           **Required.** Version of the encrypted attachments
-                           be ``v2``.
+                           protocol. Must be ``v2``.
 ========= ================ =====================================================
 
 ``JWK``
@@ -290,12 +291,13 @@ v         string           Version of the encrypted attachments protocol. Must
 ========= ========= ============================================================
 Parameter Type      Description
 ========= ========= ============================================================
-key       string    Key type. Must be ``oct``.
+key       string    **Required.** Key type. Must be ``oct``.
-key_opts  [string]  Key operations. Must at least contain ``encrypt`` and
+key_opts  [string]  **Required.** Key operations. Must at least contain
-                    ``decrypt``.
+                    ``encrypt`` and ``decrypt``.
-alg       string    Algorithm. Must be ``A256CTR``.
+alg       string    **Required.** Algorithm. Must be ``A256CTR``.
-k         string    The key, encoded as urlsafe unpadded base64.
+k         string    **Required.** The key, encoded as urlsafe unpadded base64.
-ext       boolean   Extractable. Must be ``true``. This is a `W3C extension`_.
+ext       boolean   **Required.** Extractable. Must be ``true``. This is a
+                    `W3C extension`_.
 ========= ========= ============================================================
 
 Example: