Merge pull request #1573 from turt2live/travis/c2s/sync-event-fields

Fix event schemas for /sync

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

@@ -135,7 +135,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,8 +202,35 @@ paths:
                             the room then the current state will be given as a
                             delta against the archived ``state`` not the
                             ``invite_state``.
-                          allOf:
-                            - $ref: "definitions/event_batch.yaml"
+                          properties:
+                            events:
+                              description: The StrippedState events that form the invite state.
+                              items:
+                                description: |-
+                                  A stripped down state event, with only the ``type``, ``state_key``,
+                                  ``sender``, and ``content`` keys.
+                                properties:
+                                  content:
+                                    description: The ``content`` for the event.
+                                    title: EventContent
+                                    type: object
+                                  state_key:
+                                    description: The ``state_key`` for the event.
+                                    type: string
+                                  type:
+                                    description: The ``type`` for the event.
+                                    type: string
+                                  sender:
+                                    description: The ``sender`` for the event.
+                                    type: string
+                                required:
+                                  - type
+                                  - state_key
+                                  - content
+                                  - sender
+                                title: StrippedState
+                                type: object
+                              type: array
                   leave:
                     title: Left rooms
                     type: object
@@ -219,7 +246,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
@@ -270,6 +297,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",
@@ -321,7 +350,6 @@ paths:
                           {
                             "sender": "@alice:example.com",
                             "type": "m.room.message",
-                            "age": 124524,
                             "txn_id": "1234",
                             "content": {
                               "body": "I am a fish",

changelogs/client_server/newsfragments/1573.clarification

@@ -0,0 +1 @@
+Clarify the event fields used in the ``/sync`` response.

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,46 +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.
-    type: string
-  sender:
-    description: Contains the fully-qualified ID of the user who *sent*
-      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
-  origin_server_ts:
-    description: Timestamp in milliseconds on originating homeserver
-      when this event was sent.
-    type: integer
-    format: int64
-  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/state_event.yaml

@@ -1,23 +1,7 @@
 allOf:
 - $ref: room_event.yaml
+- $ref: sync_state_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. 
-
-      State keys starting with an ``@`` are reserved for referencing user IDs, such
-      as room members. With the exception of a few events, state events set with a
-      given user's ID as the state key MUST only be set by that user.
-    type: string
-required:
-- state_key
 title: State 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: integer
+    format: int64
+  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,39 @@
+# 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.
+
+      State keys starting with an ``@`` are reserved for referencing user IDs, such
+      as room members. With the exception of a few events, state events set with a
+      given user's ID as the state key MUST only be set by that user.
+    type: string
+required:
+- state_key
+title: State Event
+type: object