Unflatten 'unsigned'

It turns out that flattening 'unsigned' comes with too many downsides. Let's
stick with the status quo.

api/client-server/v2_alpha/definitions/event.json

@@ -2,34 +2,16 @@
   "type": "object",
   "title": "Event",
   "properties": {
-    "age": {
-      "type": "integer",
-      "format": "int64",
-      "description": "Time in milliseconds since the event was sent."
-    },
     "content": {
       "type": "object",
       "title": "EventContent",
       "description": "The content of this event. The fields in this object will vary depending on the type of event."
     },
-    "event_id": {
-      "type": "string",
-      "description": "Globally unique identifier for this event."
-    },
     "origin_server_ts": {
       "type": "integer",
       "format": "int64",
       "description": "Timestamp in milliseconds on originating homeserver when this event was sent."
     },
-    "prev_content": {
-      "title": "EventContent",
-      "type": "object",
-      "description": "Optional. The previous ``content`` for this state. This will be present only for state events appearing in the ``timeline``. If this is not a state event, or there is no previous content, this key will be missing."
-    },
-    "prev_sender": {
-      "type": "string",
-      "description": "Optional. The ``sender`` of the previous event for this state. This will be present only for state events appearing in the ``timeline``. If this is not a state event, or there was no previous event for this state, this key will be missing."
-    },
     "sender": {
       "type": "string",
       "description": "The MXID of the user who sent this event."
@@ -42,9 +24,30 @@
       "type": "string",
       "description": "The type of event."
     },
-    "txn_id": {
-      "type": "string",
-      "description": "Optional. The transaction ID set when this message was sent. This key will only be present for message events sent by the device calling this API."
+    "unsigned": {
+      "type": "object",
+      "title": "Unsigned",
+      "description": "Information about this event which was not sent by the originating homeserver",
+      "properties": {
+        "age": {
+          "type": "integer",
+          "format": "int64",
+          "description": "Time in milliseconds since the event was sent."
+        },
+        "prev_content": {
+          "title": "EventContent",
+          "type": "object",
+          "description": "Optional. The previous ``content`` for this state. This will be present only for state events appearing in the ``timeline``. If this is not a state event, or there is no previous content, this key will be missing."
+        },
+        "replaces_state": {
+          "type": "string",
+          "description": "Optional. The event_id of the previous event for this state. This will be present only for state events appearing in the ``timeline``. If this is not a state event, or there is no previous content, this key will be missing."
+        },
+        "transaction_id": {
+          "type": "string",
+          "description": "Optional. The transaction ID set when this message was sent. This key will only be present for message events sent by the device calling this API."
+        }
+      }
     }
   }
 }

specification/events.rst

@@ -28,20 +28,23 @@ formatted for federation by:
 
 * Removing the following keys:
   ``auth_events``, ``prev_events``, ``hashes``, ``signatures``, ``depth``,
-  ``origin``, ``prev_state``, ``unsigned``.
-* Adding an ``age`` to the event object which gives the time in
+  ``origin``, ``prev_state``.
+* Adding an ``age`` to the ``unsigned`` object which gives the time in
   milliseconds that has elapsed since the event was sent.
-* Adding ``prev_content`` and ``prev_sender`` to the event object if the event
-  is a ``state event``, which give the previous content and previous sender of
-  that state key
-* Adding a ``redacted_because`` to event object if the event was
+* Adding ``prev_content`` and ``prev_sender`` to the ``unsigned`` object if the
+  event is a ``state event``, which give the previous content and previous
+  sender of that state key
+* Adding a ``redacted_because`` to the ``unsigned`` object if the event was
   redacted which gives the event that redacted it.
-* Adding a ``txn_id`` to the event object if the event was sent by the client
-  requesting it.
+* Adding a ``transaction_id`` to the ``unsigned`` object if the event was sent
+  by the client requesting it.
 
 Events in responses for APIs with the /v1 prefix are generated from an event
 formatted for the /v2 prefix by:
 
+* Moving the folling keys from the ``unsigned`` object to the top level event
+  object: ``age``, ``redacted_because``, ``replaces_state``, ``prev_content``.
+* Removing the ``unsigned`` object.
 * Rename the ``sender`` key to ``user_id``.
 * If the event was an ``m.room.member`` with ``membership`` set to ``invite``
   then adding a ``invite_room_state`` key to the top level event object.