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 +0,0 @@
-../../../event-schemas/schema/v1/core-event-schema

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."
+        }
+      }
+    }
+  }
+}

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" }]
       }
     }
   }

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"
     }
   }
 }

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"]}
                           }

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: