Fix event schemas for /sync

This commit clarifies the required keys for each type of event that appears in sync, fixes the core event schema not declaring 'content' as required, and includes a mention that events may not have a room_id when appearing in /sync.

Fixes https://github.com/matrix-org/matrix-doc/issues/595
Fixes https://github.com/matrix-org/matrix-doc/issues/909

api/client-server/definitions/event_batch.yaml

@@ -1,4 +1,5 @@
 # Copyright 2016 OpenMarket Ltd
+# Copyright 2018 New Vector Ltd
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -13,10 +14,10 @@
 # limitations under the License.
 properties:
   events:
-    description: List of events
+    description: List of events.
     items:
       allOf:
-      - $ref: event.yaml
+      - $ref: event-schemas/schema/core-event-schema/event.yaml
       type: object
     type: array
 type: object

api/client-server/definitions/room_event_batch.yaml

@@ -0,0 +1,27 @@
+# Copyright 2018 New Vector Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+properties:
+  events:
+    description: List of events.
+    items:
+      allOf:
+      - $ref: event-schemas/schema/core-event-schema/sync_room_event.yaml
+      type: object
+      required:
+      - event_id
+      #- room_id - Not in /sync
+      - sender
+      - origin_server_ts
+    type: array
+type: object

api/client-server/definitions/state_event_batch.yaml

@@ -0,0 +1,28 @@
+# Copyright 2018 New Vector Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+properties:
+  events:
+    description: List of events.
+    items:
+      allOf:
+      - $ref: event-schemas/schema/core-event-schema/sync_state_event.yaml
+      type: object
+      required:
+      - event_id
+      #- room_id - Not in /sync
+      - sender
+      - origin_server_ts
+      - state_key
+    type: array
+type: object

api/client-server/definitions/timeline_batch.yaml

@@ -1,4 +1,5 @@
 # Copyright 2016 OpenMarket Ltd
+# Copyright 2018 New Vector Ltd
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -12,14 +13,14 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 allOf:
-- $ref: event_batch.yaml
+- $ref: room_event_batch.yaml
 properties:
   limited:
     description: True if the number of events returned was limited by the ``limit``
-      on the filter
+      on the filter.
     type: boolean
   prev_batch:
     description: A token that can be supplied to the ``from`` parameter of the
-      rooms/{roomId}/messages endpoint
+      rooms/{roomId}/messages endpoint.
     type: string
 type: object

api/client-server/sync.yaml

@@ -134,7 +134,7 @@ paths:
                             ``timeline``, if ``since`` is not given, or
                             ``full_state`` is true).
                           allOf:
-                            - $ref: "definitions/event_batch.yaml"
+                            - $ref: "definitions/state_event_batch.yaml"
                         timeline:
                           title: Timeline
                           type: object
@@ -202,7 +202,7 @@ paths:
                             delta against the archived ``state`` not the
                             ``invite_state``.
                           allOf:
-                            - $ref: "definitions/event_batch.yaml"
+                            - $ref: "definitions/state_event_batch.yaml"
                   leave:
                     title: Left rooms
                     type: object
@@ -218,7 +218,7 @@ paths:
                           description: |-
                             The state updates for the room up to the start of the timeline.
                           allOf:
-                            - $ref: "definitions/event_batch.yaml"
+                            - $ref: "definitions/state_event_batch.yaml"
                         timeline:
                           title: Timeline
                           type: object
@@ -261,6 +261,8 @@ paths:
                 description: |-
                   Information on end-to-end encryption keys, as specified
                   in |device_lists_sync|_.
+            required:
+              - next_batch
           examples:
             application/json: {
                 "next_batch": "s72595_4483_1934",
@@ -312,7 +314,6 @@ paths:
                           {
                             "sender": "@alice:example.com",
                             "type": "m.room.message",
-                            "age": 124524,
                             "txn_id": "1234",
                             "content": {
                               "body": "I am a fish",

event-schemas/schema/core-event-schema/event.yaml

@@ -10,5 +10,6 @@ properties:
     type: string
 required:
   - type
+  - content
 title: Event
 type: object

event-schemas/schema/core-event-schema/room_event.yaml

@@ -1,45 +1,14 @@
 allOf:
-- $ref: event.yaml
+- $ref: sync_room_event.yaml
 description: In addition to the Event fields, Room Events have the following additional
   fields.
 properties:
-  event_id:
-    description: The globally unique event identifier.
-    type: string
   room_id:
-    description: The ID of the room associated with this event.
+    description: |-
+      The ID of the room associated with this event. Will not be present on events
+      that arrive through ``/sync``, despite being required everywhere else.
     type: string
-  sender:
-    description: Contains the fully-qualified ID of the user who *sent*
-      this event.
-    type: string
-  origin_server_ts:
-    description: Timestamp in milliseconds on originating homeserver
-      when this event was sent.
-    type: number
-  unsigned:
-    description: Contains optional extra information about the event.
-    properties:
-      age:
-        description: The time in milliseconds that has elapsed since the event was
-          sent. This field is generated by the local homeserver, and may be incorrect
-          if the local time on at least one of the two servers is out of sync, which can
-          cause the age to either be negative or greater than it actually is.
-        type: integer
-      redacted_because:
-        description: Optional. The event that redacted this event, if any.
-        title: Event
-        type: object
-      transaction_id:
-        description: The client-supplied transaction ID, if the client being given
-          the event is the same one which sent it.
-        type: string
-    title: UnsignedData
-    type: object
 required:
-- event_id
 - room_id
-- sender
-- origin_server_ts
 title: Room Event
 type: object

event-schemas/schema/core-event-schema/sync_room_event.yaml

@@ -0,0 +1,60 @@
+# Copyright 2018 New Vector Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Note: this is technically not a core event schema, however it is included here
+# to keep things sane. The short story is that /sync doesn't require a room_id to
+# be on events, so we give it a whole event structure as a base for room_event.
+# This base doesn't declare a room_id, which instead appears in the room_event.
+
+allOf:
+- $ref: event.yaml
+description: In addition to the Event fields, Room Events have the following additional
+  fields.
+properties:
+  event_id:
+    description: The globally unique event identifier.
+    type: string
+  sender:
+    description: Contains the fully-qualified ID of the user who *sent*
+      this event.
+    type: string
+  origin_server_ts:
+    description: Timestamp in milliseconds on originating homeserver
+      when this event was sent.
+    type: number
+  unsigned:
+    description: Contains optional extra information about the event.
+    properties:
+      age:
+        description: The time in milliseconds that has elapsed since the event was
+          sent. This field is generated by the local homeserver, and may be incorrect
+          if the local time on at least one of the two servers is out of sync, which can
+          cause the age to either be negative or greater than it actually is.
+        type: integer
+      redacted_because:
+        description: Optional. The event that redacted this event, if any.
+        title: Event
+        type: object
+      transaction_id:
+        description: The client-supplied transaction ID, if the client being given
+          the event is the same one which sent it.
+        type: string
+    title: UnsignedData
+    type: object
+required:
+- event_id
+- sender
+- origin_server_ts
+title: Room Event
+type: object

event-schemas/schema/core-event-schema/sync_state_event.yaml

@@ -0,0 +1,35 @@
+# Copyright 2018 New Vector Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# See sync_room_event.yaml for why this file is here.
+
+allOf:
+- $ref: sync_room_event.yaml
+description: In addition to the Room Event fields, State Events have the following
+  additional fields.
+properties:
+  prev_content:
+    description: Optional. The previous ``content`` for this event. If there is no
+      previous content, this key will be missing.
+    title: EventContent
+    type: object
+  state_key:
+    description: A unique key which defines the overwriting semantics for this piece
+      of room state. This value is often a zero-length string. The presence of this
+      key makes this event a State Event. The key MUST NOT start with '_'.
+    type: string
+required:
+- state_key
+title: State Event
+type: object