From 3f0262081c7a900cd1e5bcd7ca9a2991facb6ef9 Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <richard@matrix.org>
Date: Wed, 11 Nov 2015 19:22:38 +0000
Subject: [PATCH 1/9] Update sync API defn to reflect SPEC-254 changes

State now corresponds to the start of the timeline, not the end.
---
 api/client-server/v2_alpha/sync.yaml | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/api/client-server/v2_alpha/sync.yaml b/api/client-server/v2_alpha/sync.yaml
index a2d5a2b8..9e921610 100644
--- a/api/client-server/v2_alpha/sync.yaml
+++ b/api/client-server/v2_alpha/sync.yaml
@@ -119,7 +119,11 @@ paths:
                           title: State
                           type: object
                           description: |-
-                            The state updates for the room.
+                            Updates to the state, between the time indicated by
+                            the ``since`` parameter, and the start of the
+                            ``timeline`` (or all state up to the start of the
+                            ``timeline``, if ``since`` is not given, or
+                            ``full_state`` is true).
                           allOf:
                             - $ref: "definitions/room_event_batch.json"
                         timeline:
@@ -193,8 +197,7 @@ paths:
                           title: State
                           type: object
                           description: |-
-                            The state updates for the room up to the point when
-                            the user left.
+                            The state updates for the room up to the start of the timeline.
                           allOf:
                             - $ref: "definitions/room_event_batch.json"
                         timeline:
@@ -260,7 +263,6 @@ paths:
                       "state": {
                         "events": [
                           "$66697273743031:example.com",
-                          "$7365636s6r6432:example.com"
                         ]
                       },
                       "timeline": {

From 57995a815a83ec7496283eae5511ebd89ddeb747 Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <richard@matrix.org>
Date: Sun, 15 Nov 2015 23:30:29 +0000
Subject: [PATCH 2/9] Fix a number of untruths in the documentation about
 /sync.

Attempts to make the /sync documentation better represent fact as it currently
stands - in particular document the structure of the returned events.
---
 api/client-server/v2_alpha/core-event-schema  |  1 -
 .../v2_alpha/definitions/event.json           | 53 +++++++++++++++++++
 .../v2_alpha/definitions/event_batch.json     |  4 +-
 .../v2_alpha/definitions/timeline_batch.json  |  4 +-
 api/client-server/v2_alpha/sync.yaml          | 16 +++---
 specification/events.rst                      |  5 +-
 6 files changed, 68 insertions(+), 15 deletions(-)
 delete mode 120000 api/client-server/v2_alpha/core-event-schema
 create mode 100644 api/client-server/v2_alpha/definitions/event.json

diff --git a/api/client-server/v2_alpha/core-event-schema b/api/client-server/v2_alpha/core-event-schema
deleted file mode 120000
index b020e6da..00000000
--- a/api/client-server/v2_alpha/core-event-schema
+++ /dev/null
@@ -1 +0,0 @@
-../../../event-schemas/schema/v1/core-event-schema
\ No newline at end of file
diff --git a/api/client-server/v2_alpha/definitions/event.json b/api/client-server/v2_alpha/definitions/event.json
new file mode 100644
index 00000000..6a01c688
--- /dev/null
+++ b/api/client-server/v2_alpha/definitions/event.json
@@ -0,0 +1,53 @@
+{
+  "type": "object",
+  "title": "Event",
+  "properties": {
+    "content": {
+      "type": "object",
+      "title": "EventContent",
+      "description": "The content of this event. The fields in this object will vary depending on the type of event."
+    },
+    "origin_server_ts": {
+      "type": "integer",
+      "format": "int64",
+      "description": "Timestamp in milliseconds on originating homeserver when this event was sent."
+    },
+    "sender": {
+      "type": "string",
+      "description": "The MXID of the user who sent this event."
+    },
+    "state_key": {
+      "type": "string",
+      "description": "Optional. This key will only be present for state events. A unique key which defines the overwriting semantics for this piece of room state."
+    },
+    "type": {
+      "type": "string",
+      "description": "The type of event."
+    },
+    "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."
+        },
+        "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."
+        }
+      }
+    }
+  }
+}
diff --git a/api/client-server/v2_alpha/definitions/event_batch.json b/api/client-server/v2_alpha/definitions/event_batch.json
index 395aed13..7f489423 100644
--- a/api/client-server/v2_alpha/definitions/event_batch.json
+++ b/api/client-server/v2_alpha/definitions/event_batch.json
@@ -5,8 +5,8 @@
       "type": "array",
       "description": "List of events",
       "items": {
-        "title": "Event",
-        "type": "object"
+        "type": "object",
+        "allOf": [{"$ref": "event.json" }]
       }
     }
   }
diff --git a/api/client-server/v2_alpha/definitions/timeline_batch.json b/api/client-server/v2_alpha/definitions/timeline_batch.json
index ddf8d341..15ca1ead 100644
--- a/api/client-server/v2_alpha/definitions/timeline_batch.json
+++ b/api/client-server/v2_alpha/definitions/timeline_batch.json
@@ -4,11 +4,11 @@
   "properties": {
     "limited": {
       "type": "boolean",
-      "description": "Whether there are more events on the server"
+      "description": "True if the number of events returned was limited by the ``limit`` on the filter"
     },
     "prev_batch": {
       "type": "string",
-      "description": "If the batch was limited then this is a token that can be supplied to the server to retrieve more events"
+      "description": "If the batch was limited then this is a token that can be supplied to the server to retrieve earlier events"
     }
   }
 }
diff --git a/api/client-server/v2_alpha/sync.yaml b/api/client-server/v2_alpha/sync.yaml
index 9e921610..06763a08 100644
--- a/api/client-server/v2_alpha/sync.yaml
+++ b/api/client-server/v2_alpha/sync.yaml
@@ -96,8 +96,10 @@ paths:
                   Updates to rooms.
                 properties:
                   joined:
-                    title: Joined
+                    title: Joined Rooms
                     type: object
+                    description: |-
+                      The rooms that the user has joined.
                     additionalProperties:
                       title: Joined Room
                       type: object
@@ -114,7 +116,7 @@ paths:
                             description: An event object.
                             type: object
                             allOf:
-                              - $ref: "core-event-schema/event.json"
+                              - $ref: "definitions/event.json"
                         state:
                           title: State
                           type: object
@@ -144,7 +146,7 @@ paths:
                           allOf:
                             - $ref: "definitions/event_batch.json"
                   invited:
-                    title: Invited
+                    title: Invited Rooms
                     type: object
                     description: |-
                       The rooms that the user has been invited to.
@@ -171,11 +173,10 @@ paths:
                           allOf:
                             - $ref: "definitions/event_batch.json"
                   archived:
-                    title: Archived
+                    title: Archived rooms
                     type: object
                     description: |-
-                      The rooms that the user has left or been banned from. The
-                      entries in the room_map will lack an ``ephemeral`` key.
+                      The rooms that the user has left or been banned from.
                     additionalProperties:
                       title: Archived Room
                       type: object
@@ -192,7 +193,7 @@ paths:
                             description: An event object.
                             type: object
                             allOf:
-                              - $ref: "core-event-schema/event.json"
+                              - $ref: "definitions/event.json"
                         state:
                           title: State
                           type: object
@@ -276,7 +277,6 @@ paths:
                       "ephemeral": {
                         "events": [
                           {
-                            "room_id": "!726s6s6q:example.com",
                             "type": "m.typing",
                             "content": {"user_ids": ["@alice:example.com"]}
                           }
diff --git a/specification/events.rst b/specification/events.rst
index a1aece1c..7bf08012 100644
--- a/specification/events.rst
+++ b/specification/events.rst
@@ -30,12 +30,13 @@ formatted for federation by:
   ``auth_events``, ``prev_events``, ``hashes``, ``signatures``, ``depth``,
   ``origin``, ``prev_state``.
 * Adding an ``age`` to the ``unsigned`` object which gives the time in
-  milliseconds that has ellapsed since the event was sent.
+  milliseconds that has elapsed since the event was sent.
 * Adding a ``prev_content`` to the ``unsigned`` object if the event is
   a ``state event`` which gives previous content 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 ``transaction_id`` if the event was sent by the client requesting it.
+* Adding a ``txn_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:

From b41d771c1586a06e387222030f923ed5fc95ecf0 Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <richard@matrix.org>
Date: Sun, 15 Nov 2015 23:58:04 +0000
Subject: [PATCH 3/9] Fix typos in /sync example response

---
 api/client-server/v2_alpha/sync.yaml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/api/client-server/v2_alpha/sync.yaml b/api/client-server/v2_alpha/sync.yaml
index 06763a08..2290b070 100644
--- a/api/client-server/v2_alpha/sync.yaml
+++ b/api/client-server/v2_alpha/sync.yaml
@@ -253,7 +253,7 @@ paths:
                         "$74686972643033:example.com": {
                           "sender": "@alice:example.com",
                           "type": "m.room.message",
-                          "unsigned": {"age": "124524", "txn_id": "1234"},
+                          "unsigned": {"age": 124524, "txn_id": "1234"},
                           "content": {
                             "body": "I am a fish",
                             "msgtype": "m.text"
@@ -263,7 +263,7 @@ paths:
                       },
                       "state": {
                         "events": [
-                          "$66697273743031:example.com",
+                          "$66697273743031:example.com"
                         ]
                       },
                       "timeline": {

From 29bd4d45ee9155bd80e61ce50ab34745be1fd8a4 Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <richard@matrix.org>
Date: Sun, 15 Nov 2015 23:40:41 +0000
Subject: [PATCH 4/9] Flatten the response to /sync

Now that we don't expect there to be duplication betwen the 'timeline' and
'state' results, there's no point in having the state map. (That does mean the
events themselves need event_id fields though).

Also:

- move the contents of the 'unsigned' dictionary into the events themselves
- replace the state list with two layers of dictionary keyed on type and
  state_key
- rename the children of the 'rooms' dict from "joined/invited/archived" to
  "join/invite/leave" to match the membership states
---
 .../v2_alpha/definitions/event.json           |  45 +++---
 .../definitions/room_event_batch.json         |  12 --
 .../v2_alpha/definitions/timeline_batch.json  |   2 +-
 api/client-server/v2_alpha/sync.yaml          | 134 +++++++-----------
 specification/events.rst                      |  17 +--
 5 files changed, 84 insertions(+), 126 deletions(-)
 delete mode 100644 api/client-server/v2_alpha/definitions/room_event_batch.json

diff --git a/api/client-server/v2_alpha/definitions/event.json b/api/client-server/v2_alpha/definitions/event.json
index 6a01c688..3a15357a 100644
--- a/api/client-server/v2_alpha/definitions/event.json
+++ b/api/client-server/v2_alpha/definitions/event.json
@@ -2,16 +2,34 @@
   "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."
@@ -24,30 +42,9 @@
       "type": "string",
       "description": "The type of event."
     },
-    "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."
-        },
-        "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."
-        }
-      }
+    "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."
     }
   }
 }
diff --git a/api/client-server/v2_alpha/definitions/room_event_batch.json b/api/client-server/v2_alpha/definitions/room_event_batch.json
deleted file mode 100644
index fcf148f3..00000000
--- a/api/client-server/v2_alpha/definitions/room_event_batch.json
+++ /dev/null
@@ -1,12 +0,0 @@
-{
-  "type": "object",
-  "properties": {
-    "events": {
-      "type": "array",
-      "description": "List of event ids",
-      "items": {
-        "type": "string"
-      }
-    }
-  }
-}
diff --git a/api/client-server/v2_alpha/definitions/timeline_batch.json b/api/client-server/v2_alpha/definitions/timeline_batch.json
index 15ca1ead..f27a5746 100644
--- a/api/client-server/v2_alpha/definitions/timeline_batch.json
+++ b/api/client-server/v2_alpha/definitions/timeline_batch.json
@@ -1,6 +1,6 @@
 {
   "type": "object",
-  "allOf": [{"$ref":"definitions/room_event_batch.json"}],
+  "allOf": [{"$ref":"definitions/event_batch.json"}],
   "properties": {
     "limited": {
       "type": "boolean",
diff --git a/api/client-server/v2_alpha/sync.yaml b/api/client-server/v2_alpha/sync.yaml
index 2290b070..c63f3432 100644
--- a/api/client-server/v2_alpha/sync.yaml
+++ b/api/client-server/v2_alpha/sync.yaml
@@ -95,7 +95,7 @@ paths:
                 description: |-
                   Updates to rooms.
                 properties:
-                  joined:
+                  join:
                     title: Joined Rooms
                     type: object
                     description: |-
@@ -104,19 +104,6 @@ paths:
                       title: Joined Room
                       type: object
                       properties:
-                        event_map:
-                          title: EventMap
-                          type: object
-                          description: |-
-                            A map from event ID to events for this room. The
-                            events are referenced from the ``timeline`` and
-                            ``state`` keys for this room.
-                          additionalProperties:
-                            title: Event
-                            description: An event object.
-                            type: object
-                            allOf:
-                              - $ref: "definitions/event.json"
                         state:
                           title: State
                           type: object
@@ -127,7 +114,7 @@ paths:
                             ``timeline``, if ``since`` is not given, or
                             ``full_state`` is true).
                           allOf:
-                            - $ref: "definitions/room_event_batch.json"
+                            - $ref: "definitions/state_batch.json"
                         timeline:
                           title: Timeline
                           type: object
@@ -145,7 +132,7 @@ paths:
                             e.g. typing.
                           allOf:
                             - $ref: "definitions/event_batch.json"
-                  invited:
+                  invite:
                     title: Invited Rooms
                     type: object
                     description: |-
@@ -171,36 +158,23 @@ paths:
                             delta against the archived ``state`` not the
                             ``invite_state``.
                           allOf:
-                            - $ref: "definitions/event_batch.json"
-                  archived:
-                    title: Archived rooms
+                            - $ref: "definitions/state_batch.json"
+                  leave:
+                    title: Left rooms
                     type: object
                     description: |-
                       The rooms that the user has left or been banned from.
                     additionalProperties:
-                      title: Archived Room
+                      title: Left Room
                       type: object
                       properties:
-                        event_map:
-                          title: EventMap
-                          type: object
-                          description: |-
-                            A map from event ID to events for this room. The
-                            events are referenced from the ``timeline`` and
-                            ``state`` keys for this room.
-                          additionalProperties:
-                            title: Event
-                            description: An event object.
-                            type: object
-                            allOf:
-                              - $ref: "definitions/event.json"
                         state:
                           title: State
                           type: object
                           description: |-
                             The state updates for the room up to the start of the timeline.
                           allOf:
-                            - $ref: "definitions/room_event_batch.json"
+                            - $ref: "definitions/state_batch.json"
                         timeline:
                           title: Timeline
                           type: object
@@ -230,46 +204,43 @@ paths:
                   ]
                 },
                 "rooms": {
-                  "joined": {
+                  "join": {
                     "!726s6s6q:example.com": {
-                      "event_map": {
-                        "$66697273743031:example.com": {
-                          "sender": "@alice:example.com",
-                          "type": "m.room.member",
-                          "state_key": "@alice:example.com",
-                          "content": {"membership": "join"},
-                          "origin_server_ts": 1417731086795
-                        },
-                        "$7365636s6r6432:example.com": {
-                          "sender": "@bob:example.com",
-                          "type": "m.room.member",
-                          "state_key": "@bob:example.com",
-                          "content": {"membership": "join"},
-                          "unsigned": {
-                            "prev_content": {"membership": "invite"}
-                          },
-                          "origin_server_ts": 1417731086795
-                        },
-                        "$74686972643033:example.com": {
-                          "sender": "@alice:example.com",
-                          "type": "m.room.message",
-                          "unsigned": {"age": 124524, "txn_id": "1234"},
-                          "content": {
-                            "body": "I am a fish",
-                            "msgtype": "m.text"
-                          },
-                          "origin_server_ts": 1417731086797
-                        }
-                      },
                       "state": {
-                        "events": [
-                          "$66697273743031:example.com"
-                        ]
+                        "m.room.member": {
+                          "@alice:example.com": {
+                            "sender": "@alice:example.com",
+                            "type": "m.room.member",
+                            "state_key": "@alice:example.com",
+                            "content": {"membership": "join"},
+                            "origin_server_ts": 1417731086795,
+                            "event_id": "$66697273743031:example.com"
+                          }
+                        }
                       },
                       "timeline": {
                         "events": [
-                          "$7365636s6r6432:example.com",
-                          "$74686972643033:example.com"
+                          {
+                            "sender": "@bob:example.com",
+                            "type": "m.room.member",
+                            "state_key": "@bob:example.com",
+                            "content": {"membership": "join"},
+                            "prev_content": {"membership": "invite"},
+                            "origin_server_ts": 1417731086795,
+                            "event_id": "$7365636s6r6432:example.com":
+                          },
+                          {
+                            "sender": "@alice:example.com",
+                            "type": "m.room.message",
+                            "age": 124524,
+                            "txn_id": "1234",
+                            "content": {
+                              "body": "I am a fish",
+                              "msgtype": "m.text"
+                            },
+                            "origin_server_ts": 1417731086797,
+                            "event_id": "$74686972643033:example.com"
+                          }
                         ],
                         "limited": true,
                         "prev_batch": "t34-23535_0_0"
@@ -277,6 +248,7 @@ paths:
                       "ephemeral": {
                         "events": [
                           {
+                            "room_id": "!726s6s6q:example.com",
                             "type": "m.typing",
                             "content": {"user_ids": ["@alice:example.com"]}
                           }
@@ -284,26 +256,30 @@ paths:
                       }
                     }
                   },
-                  "invited": {
+                  "invite": {
                     "!696r7674:example.com": {
                       "invite_state": {
-                        "events": [
-                          {
+                        "m.room.name": {
+                          "": {
                             "sender": "@alice:example.com",
                             "type": "m.room.name",
                             "state_key": "",
-                            "content": {"name": "My Room Name"}
-                          },
-                          {
+                            "content": {"name": "My Room Name"},
+                            "event_id": "$asdkgjrsfg2314375:example.com",
+
+                          }
+                        },
+                        "m.room.member": {
+                          "@bob:example.com": {
                             "sender": "@alice:example.com",
                             "type": "m.room.member",
                             "state_key": "@bob:example.com",
-                            "content": {"membership": "invite"}
-                          }
-                        ]
+                            "content": {"membership": "invite"},
+                            "event_id": "$257kasjdg315324akhg:example.com",
+                        }
                       }
                     }
                   },
-                  "archived": {}
+                  "leave": {}
                 }
               }
diff --git a/specification/events.rst b/specification/events.rst
index 7bf08012..3d069be8 100644
--- a/specification/events.rst
+++ b/specification/events.rst
@@ -28,22 +28,19 @@ formatted for federation by:
 
 * Removing the following keys:
   ``auth_events``, ``prev_events``, ``hashes``, ``signatures``, ``depth``,
-  ``origin``, ``prev_state``.
-* Adding an ``age`` to the ``unsigned`` object which gives the time in
+  ``origin``, ``prev_state``, ``unsigned``.
+* Adding an ``age`` to the event object which gives the time in
   milliseconds that has elapsed since the event was sent.
-* Adding a ``prev_content`` to the ``unsigned`` object if the event is
-  a ``state event`` which gives previous content of that state key.
-* Adding a ``redacted_because`` to the ``unsigned`` object if the event was
+* 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
   redacted which gives the event that redacted it.
-* Adding a ``txn_id`` to the ``unsigned`` object if the event was sent by the
-  client requesting it.
+* Adding a ``txn_id`` 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.

From e1b12a753ecd96227effef3612f70d9adf48c0a9 Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <richard@matrix.org>
Date: Mon, 16 Nov 2015 00:17:22 +0000
Subject: [PATCH 5/9] Fix typos and missing file

---
 .../v2_alpha/definitions/state_batch.json            | 12 ++++++++++++
 api/client-server/v2_alpha/sync.yaml                 |  8 ++++----
 2 files changed, 16 insertions(+), 4 deletions(-)
 create mode 100644 api/client-server/v2_alpha/definitions/state_batch.json

diff --git a/api/client-server/v2_alpha/definitions/state_batch.json b/api/client-server/v2_alpha/definitions/state_batch.json
new file mode 100644
index 00000000..45728f40
--- /dev/null
+++ b/api/client-server/v2_alpha/definitions/state_batch.json
@@ -0,0 +1,12 @@
+{
+  "type": "object",
+  "additionalProperties": {
+    "type": "object",
+    "x-pattern": "$EVENT_TYPE",
+    "additionalProperties": {
+      "type": "object",
+      "x-pattern": "$STATE_KEY",
+      "allOf": [{"$ref": "event.json" }]
+    }
+  }
+}
diff --git a/api/client-server/v2_alpha/sync.yaml b/api/client-server/v2_alpha/sync.yaml
index c63f3432..198f4833 100644
--- a/api/client-server/v2_alpha/sync.yaml
+++ b/api/client-server/v2_alpha/sync.yaml
@@ -227,7 +227,7 @@ paths:
                             "content": {"membership": "join"},
                             "prev_content": {"membership": "invite"},
                             "origin_server_ts": 1417731086795,
-                            "event_id": "$7365636s6r6432:example.com":
+                            "event_id": "$7365636s6r6432:example.com"
                           },
                           {
                             "sender": "@alice:example.com",
@@ -265,8 +265,7 @@ paths:
                             "type": "m.room.name",
                             "state_key": "",
                             "content": {"name": "My Room Name"},
-                            "event_id": "$asdkgjrsfg2314375:example.com",
-
+                            "event_id": "$asdkgjrsfg2314375:example.com"
                           }
                         },
                         "m.room.member": {
@@ -275,7 +274,8 @@ paths:
                             "type": "m.room.member",
                             "state_key": "@bob:example.com",
                             "content": {"membership": "invite"},
-                            "event_id": "$257kasjdg315324akhg:example.com",
+                            "event_id": "$257kasjdg315324akhg:example.com"
+                          }
                         }
                       }
                     }

From 83168813939ea1dc4c5a778781cb12e1f8eb9d87 Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <richard@matrix.org>
Date: Mon, 16 Nov 2015 16:50:54 +0000
Subject: [PATCH 6/9] txn_id field in events is called transaction_id

---
 api/client-server/v2_alpha/definitions/event.json | 2 +-
 api/client-server/v2_alpha/sync.yaml              | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/api/client-server/v2_alpha/definitions/event.json b/api/client-server/v2_alpha/definitions/event.json
index 6a01c688..5a8f52f6 100644
--- a/api/client-server/v2_alpha/definitions/event.json
+++ b/api/client-server/v2_alpha/definitions/event.json
@@ -43,7 +43,7 @@
           "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."
         },
-        "txn_id": {
+        "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."
         }
diff --git a/api/client-server/v2_alpha/sync.yaml b/api/client-server/v2_alpha/sync.yaml
index 2290b070..d23929df 100644
--- a/api/client-server/v2_alpha/sync.yaml
+++ b/api/client-server/v2_alpha/sync.yaml
@@ -253,7 +253,7 @@ paths:
                         "$74686972643033:example.com": {
                           "sender": "@alice:example.com",
                           "type": "m.room.message",
-                          "unsigned": {"age": 124524, "txn_id": "1234"},
+                          "unsigned": {"age": 124524, "transaction_id": "1234"},
                           "content": {
                             "body": "I am a fish",
                             "msgtype": "m.text"

From 0db055b4ea22f4d29064728eaaaf2c37a2f9d926 Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <richard@matrix.org>
Date: Mon, 16 Nov 2015 16:54:57 +0000
Subject: [PATCH 7/9] Fix another reference to 'txn_id'

---
 specification/events.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/specification/events.rst b/specification/events.rst
index 7bf08012..9d0be55f 100644
--- a/specification/events.rst
+++ b/specification/events.rst
@@ -35,8 +35,8 @@ formatted for federation by:
   a ``state event`` which gives previous content 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 ``unsigned`` 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:

From 6653362f315d1379d1dda248dfd299c8c3c8530d Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <richard@matrix.org>
Date: Wed, 18 Nov 2015 15:15:21 +0000
Subject: [PATCH 8/9] Unflatten 'unsigned'

It turns out that flattening 'unsigned' comes with too many downsides. Let's
stick with the status quo.
---
 .../v2_alpha/definitions/event.json           | 45 ++++++++++---------
 specification/events.rst                      | 19 ++++----
 2 files changed, 35 insertions(+), 29 deletions(-)

diff --git a/api/client-server/v2_alpha/definitions/event.json b/api/client-server/v2_alpha/definitions/event.json
index 3a15357a..5a8f52f6 100644
--- a/api/client-server/v2_alpha/definitions/event.json
+++ b/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."
+        }
+      }
     }
   }
 }
diff --git a/specification/events.rst b/specification/events.rst
index eb48ca17..5a003115 100644
--- a/specification/events.rst
+++ b/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.

From d7d59d78e1dca06407dea20ad875f64569844ad3 Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <richard@matrix.org>
Date: Wed, 18 Nov 2015 16:17:29 +0000
Subject: [PATCH 9/9] /sync: Put state dict back to being a list

Turning the state into a dict-of-dicts caused more pain than it solved. Put it
back to a list.
---
 .../v2_alpha/definitions/state_batch.json     | 12 -------
 api/client-server/v2_alpha/sync.yaml          | 31 ++++++++-----------
 2 files changed, 13 insertions(+), 30 deletions(-)
 delete mode 100644 api/client-server/v2_alpha/definitions/state_batch.json

diff --git a/api/client-server/v2_alpha/definitions/state_batch.json b/api/client-server/v2_alpha/definitions/state_batch.json
deleted file mode 100644
index 45728f40..00000000
--- a/api/client-server/v2_alpha/definitions/state_batch.json
+++ /dev/null
@@ -1,12 +0,0 @@
-{
-  "type": "object",
-  "additionalProperties": {
-    "type": "object",
-    "x-pattern": "$EVENT_TYPE",
-    "additionalProperties": {
-      "type": "object",
-      "x-pattern": "$STATE_KEY",
-      "allOf": [{"$ref": "event.json" }]
-    }
-  }
-}
diff --git a/api/client-server/v2_alpha/sync.yaml b/api/client-server/v2_alpha/sync.yaml
index 198f4833..0c9d6186 100644
--- a/api/client-server/v2_alpha/sync.yaml
+++ b/api/client-server/v2_alpha/sync.yaml
@@ -114,7 +114,7 @@ paths:
                             ``timeline``, if ``since`` is not given, or
                             ``full_state`` is true).
                           allOf:
-                            - $ref: "definitions/state_batch.json"
+                            - $ref: "definitions/event_batch.json"
                         timeline:
                           title: Timeline
                           type: object
@@ -158,7 +158,7 @@ paths:
                             delta against the archived ``state`` not the
                             ``invite_state``.
                           allOf:
-                            - $ref: "definitions/state_batch.json"
+                            - $ref: "definitions/event_batch.json"
                   leave:
                     title: Left rooms
                     type: object
@@ -174,7 +174,7 @@ paths:
                           description: |-
                             The state updates for the room up to the start of the timeline.
                           allOf:
-                            - $ref: "definitions/state_batch.json"
+                            - $ref: "definitions/event_batch.json"
                         timeline:
                           title: Timeline
                           type: object
@@ -207,8 +207,8 @@ paths:
                   "join": {
                     "!726s6s6q:example.com": {
                       "state": {
-                        "m.room.member": {
-                          "@alice:example.com": {
+                        "events": [
+                          {
                             "sender": "@alice:example.com",
                             "type": "m.room.member",
                             "state_key": "@alice:example.com",
@@ -216,7 +216,7 @@ paths:
                             "origin_server_ts": 1417731086795,
                             "event_id": "$66697273743031:example.com"
                           }
-                        }
+                        ]
                       },
                       "timeline": {
                         "events": [
@@ -248,7 +248,6 @@ paths:
                       "ephemeral": {
                         "events": [
                           {
-                            "room_id": "!726s6s6q:example.com",
                             "type": "m.typing",
                             "content": {"user_ids": ["@alice:example.com"]}
                           }
@@ -259,24 +258,20 @@ paths:
                   "invite": {
                     "!696r7674:example.com": {
                       "invite_state": {
-                        "m.room.name": {
-                          "": {
+                        "events": [
+                          {
                             "sender": "@alice:example.com",
                             "type": "m.room.name",
                             "state_key": "",
-                            "content": {"name": "My Room Name"},
-                            "event_id": "$asdkgjrsfg2314375:example.com"
-                          }
-                        },
-                        "m.room.member": {
-                          "@bob:example.com": {
+                            "content": {"name": "My Room Name"}
+                          },
+                          {
                             "sender": "@alice:example.com",
                             "type": "m.room.member",
                             "state_key": "@bob:example.com",
-                            "content": {"membership": "invite"},
-                            "event_id": "$257kasjdg315324akhg:example.com"
+                            "content": {"membership": "invite"}
                           }
-                        }
+                        ]
                       }
                     }
                   },