From 62dfa3c7415623c2ea5e49025571fc85325e91c0 Mon Sep 17 00:00:00 2001
From: Kegan Dougal <kegan@matrix.org>
Date: Thu, 28 Aug 2014 15:35:20 +0100
Subject: [PATCH] Flesh out m.room.message msgtypes

---
 docs/specification.rst | 110 +++++++++++++++++++++++++++++++++++++----
 1 file changed, 101 insertions(+), 9 deletions(-)

diff --git a/docs/specification.rst b/docs/specification.rst
index 30e4a7a3fb..fa085bac27 100644
--- a/docs/specification.rst
+++ b/docs/specification.rst
@@ -68,15 +68,108 @@ Non-state messages
 
 What are they, when are they used, what do they contain, how should they be used
 
-m.room.message types
---------------------
-- m.text
-- m.emote
-- m.audio
-- m.image
-- m.video
-- m.location
+m.room.message msgtypes
+-----------------------
+Each ``m.room.message`` MUST have a ``msgtype`` key which identifies the type of
+message being sent. Each type has their own required and optional keys, as outlined
+below:
 
+``m.text``
+  Required keys:
+    - ``body`` : "string" - The body of the message.
+  Optional keys:
+    None.
+  Example:
+    ``{ "msgtype": "m.text", "body": "I am a fish" }``
+
+``m.emote``
+  Required keys:
+    - ``body`` : "string" - The emote action to perform.
+  Optional keys:
+    None.
+  Example:
+    ``{ "msgtype": "m.emote", "body": "tries to come up with a witty explanation" }``
+
+``m.image``
+  Required keys:
+    - ``url`` : "string" - The URL to the image.
+  Optional keys:
+    - ``info`` : "string" - info : JSON object (ImageInfo) - The image info for image 
+      referred to in ``url``.
+    - ``thumbnail_url`` : "string" - The URL to the thumbnail.
+    - ``thumbnail_info`` : JSON object (ImageInfo) - The image info for the image 
+      referred to in ``thumbnail_url``.
+    - ``body`` : "string" - The alt text of the image, or some kind of content 
+      description for accessibility e.g. "image attachment".
+
+ImageInfo: 
+  Information about an image::
+    
+    { 
+      "size" : integer (size of image in bytes),
+      "w" : integer (width of image in pixels),
+      "h" : integer (height of image in pixels),
+      "mimetype" : "string (e.g. image/jpeg)",
+    }
+
+``m.audio``
+  Required keys:
+    - ``url`` : "string" - The URL to the audio.
+  Optional keys:
+    - ``info`` : JSON object (AudioInfo) - The audio info for the audio referred to in 
+      ``url``.
+    - ``body`` : "string" - A description of the audio e.g. "Bee Gees - 
+      Stayin' Alive", or some kind of content description for accessibility e.g. 
+      "audio attachment".
+
+AudioInfo: 
+  Information about a piece of audio::
+
+    {
+      "mimetype" : "string (e.g. audio/aac)",
+      "size" : integer (size of audio in bytes),
+      "duration" : integer (duration of audio in milliseconds),
+    }
+
+``m.video``
+  Required keys:
+    - ``url`` : "string" - The URL to the video.
+  Optional keys:
+    - ``info`` : JSON object (VideoInfo) - The video info for the video referred to in 
+      ``url``.
+    - ``body`` : "string" - A description of the video e.g. "Gangnam style", 
+      or some kind of content description for accessibility e.g. "video attachment".
+
+VideoInfo: 
+  Information about a video::
+
+    {
+      "mimetype" : "string (e.g. video/mp4)",
+      "size" : integer (size of video in bytes),
+      "duration" : integer (duration of video in milliseconds),
+      "w" : integer (width of video in pixels),
+      "h" : integer (height of video in pixels),
+      "thumbnail_url" : "string (URL to image)",
+      "thumbanil_info" : JSON object (ImageInfo)
+    }
+
+``m.location``
+  Required keys:
+    - ``geo_uri`` : "string" - The geo URI representing the location.
+  Optional keys:
+    - ``thumbnail_url`` : "string" - The URL to a thumnail of the location being 
+      represented.
+    - ``thumbnail_info`` : JSON object (ImageInfo) - The image info for the image 
+      referred to in ``thumbnail_url``.
+    - ``body`` : "string" - A description of the location e.g. "Big Ben, 
+      London, UK", or some kind of content description for accessibility e.g. 
+      "location attachment".
+
+The following keys can be attached to any ``m.room.message``:
+
+  Optional keys:
+    - ``sender_ts`` : integer - A timestamp (ms resolution) representing the 
+      wall-clock time when the message was sent from the client.
 
 Presence
 ========
@@ -203,7 +296,6 @@ requests to that home server as a query parameter 'access_token'.
 
 - TODO Kegan : Make registration like login (just omit the "user" key on the 
   initial request?)
-- TODO Kegan : Allow alternative forms of login (>1 route)
 
 If the client has already registered, they need to be able to login to their
 account. The home server may provide many different ways of logging in, such