Merge pull request #140 from matrix-org/markjh/v2_sync_prev_content

Document the differences in event formatting between the v1 and v2 event format.

api/client-server/v2_alpha/sync.yaml

@@ -241,6 +241,9 @@ paths:
                           "type": "m.room.member",
                           "state_key": "@bob:example.com",
                           "content": {"membership": "join"},
+                          "unsigned": {
+                            "prev_content": {"membership": "invite"}
+                          },
                           "origin_server_ts": 1417731086795
                         },
                         "$74686972643033:example.com": {

specification/events.rst

@@ -12,6 +12,42 @@ server-server and application-service APIs, and are described below.
 {{common_state_event_fields}}
 
 
+Differences between /v1 and /v2 events
+--------------------------------------
+
+There are a few differences between how events are formatted for sending
+between servers over federation and how they are formatted for sending between
+a server and its clients.
+
+Additionally there are a few differences between the format of events in the
+responses to client APIs with a /v1 prefix and responses APIs with a /v2
+prefix.
+
+Events in responses for APIs with the /v2 prefix are generated from an event
+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
+  milliseconds that has ellapsed 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.
+
+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.
+
+
 Size limits
 -----------