Split the rooms out into a separate top level key.

Divide the rooms into separate groups in preparation for adding tag
support.

Further subdivide the rooms into "joined/invited/archived" based the
membership of the user in the room because that membership affects what
events the user can view from the room. E.g only users that are joined
to a room may see the ephemeral events for the room.

api/client-server/v2_alpha/sync.yaml

@@ -5,7 +5,7 @@ info:
 host: localhost:8008
 schemes:
   - https
-basePath: /_matrix/client/v2_alpha
+basePath: /_matrix/client/api/v2_alpha
 consumes:
   - application/json
 produces:
@@ -73,43 +73,71 @@ paths:
                   ``/sync`` request.
               rooms:
                 type: object
-                properties:
+                description: |-
-                  roomlist:
+                  The updates to rooms, grouped according to the filter. By
-                    type: array
+                  default there is a single ``default`` group.
-                    description: |-
+                additionalProperties:
-                      A list of rooms that the client needs to update.
+                    joined:
-                    items:
+                      type: array
+                      description: |-
+                        A list of room ids that the user is a member of that
+                        have updates.
+                      items:
+                        type: string.
+                    invited:
+                      type: array
+                      description: |-
+                        A list of room ids that the user has been invited to.
+                        The entries in the room_map will have a ``invite`` key
+                        containing the ``m.room.member`` event of the invite.
+                      items:
+                        type: string.
+                    archived:
+                      type: array
+                      description: |-
+                        A list of room ids that the user has left or been
+                        banned from. The entries in the room_map will have a
+                        ``state`` key and a ``timeline`` key. But will lack the
+                        ``emphemeral`` key.
+                      items:
+                        type: string.
+              room_map:
+                description: |-
+                  Map from room id to the updates for that room. The room ids
+                  are referenced from the ``rooms`` key.
+                type: object
+                additionalProperties:
+                  type: object
+                  properties:
+                    room_id:
+                      type: string
+                      description: |-
+                        The ID of the room.
+                    event_map:
                       type: object
-                      properties:
+                      description: |-
-                        room_id:
+                        A map from event ID to events for this room. The events
-                          type: string
+                        are referenced from the ``timeline`` and ``state`` keys
-                          description: |-
+                        for this room.
-                            The ID of the room.
+                      additionalProperties:
-                        event_map:
+                        description: An event object.
-                          type: object
+                        type: object
-                          description: |-
+                    state:
-                            A map from event ID to events for this room. The events
+                      description: |-
-                            are referenced from the ``timeline`` and ``state`` keys
+                        The state updates for the room.
-                            for this room.
+                      allOf:
-                          additionalProperties:
+                        - $ref: "definitions/room_event_batch.json"
-                            description: An event object.
+                    timeline:
-                            type: object
+                      description: |-
-                        state:
+                        The timeline of messages and state changes in the room.
-                          description: |-
+                      allOf:
-                            The state updates for the room.
+                        - $ref: "definitions/timeline_batch.json"
-                          allOf:
+                    ephemeral:
-                            - $ref: "definitions/room_event_batch.json"
+                      description: |-
-                        timeline:
+                        The ephemeral events in the room that aren't recorded
-                          description: |-
+                        in the timeline or state of the room. E.g. typing.
-                            The timeline of messages and state changes in the room.
+                      allOf:
-                          allOf:
+                        - $ref: "definitions/event_batch.json"
-                            - $ref: "definitions/timeline_batch.json"
-                        ephemeral:
-                          description: |-
-                            The ephemeral events in the room that aren't recorded
-                            in the timeline or state of the room. E.g. typing.
-                          allOf:
-                            - $ref: "definitions/event_batch.json"
               presence:
                 description: |-
                   The updates to the presence status of other users.
@@ -129,8 +157,14 @@ paths:
                   ]
                 },
                 "rooms": {
-                  "roomlist": [{
+                  "default": {
-                    "room_id": "!726s6s6q:example.com",
+                    "invited": [],
+                    "archived": [],
+                    "joined": ["!726s6s6q:example.com"]
+                  }
+                },
+                "room_map": {
+                  "!726s6s6q:example.com": {
                     "event_map": {
                       "$66697273743031:example.com": {
                         "sender": "@alice:example.com",
@@ -177,6 +211,6 @@ paths:
                         }
                       ]
                     }
-                  }]
+                  }
                 }
               }