diff --git a/api/client-server/definitions/event_batch.yaml b/api/client-server/definitions/event_batch.yaml index 21377a41..d169c355 100644 --- a/api/client-server/definitions/event_batch.yaml +++ b/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 diff --git a/api/client-server/definitions/room_event_batch.yaml b/api/client-server/definitions/room_event_batch.yaml new file mode 100644 index 00000000..7367198f --- /dev/null +++ b/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 diff --git a/api/client-server/definitions/state_event_batch.yaml b/api/client-server/definitions/state_event_batch.yaml new file mode 100644 index 00000000..db01ecb1 --- /dev/null +++ b/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 diff --git a/api/client-server/definitions/timeline_batch.yaml b/api/client-server/definitions/timeline_batch.yaml index ce613ac4..abf93830 100644 --- a/api/client-server/definitions/timeline_batch.yaml +++ b/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 diff --git a/api/client-server/sync.yaml b/api/client-server/sync.yaml index 21af0d1e..bb514bbe 100644 --- a/api/client-server/sync.yaml +++ b/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", diff --git a/changelogs/client_server/newsfragments/1573.clarification b/changelogs/client_server/newsfragments/1573.clarification new file mode 100644 index 00000000..74efa28f --- /dev/null +++ b/changelogs/client_server/newsfragments/1573.clarification @@ -0,0 +1 @@ +Clarify the event fields used in the ``/sync`` response. diff --git a/event-schemas/schema/core-event-schema/event.yaml b/event-schemas/schema/core-event-schema/event.yaml index 7a060283..0fe5ac6c 100644 --- a/event-schemas/schema/core-event-schema/event.yaml +++ b/event-schemas/schema/core-event-schema/event.yaml @@ -10,5 +10,6 @@ properties: type: string required: - type + - content title: Event type: object diff --git a/event-schemas/schema/core-event-schema/room_event.yaml b/event-schemas/schema/core-event-schema/room_event.yaml index ebf970ad..007372a5 100644 --- a/event-schemas/schema/core-event-schema/room_event.yaml +++ b/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. + 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: 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 diff --git a/event-schemas/schema/core-event-schema/state_event.yaml b/event-schemas/schema/core-event-schema/state_event.yaml index 71c4137b..37d4426f 100644 --- a/event-schemas/schema/core-event-schema/state_event.yaml +++ b/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 diff --git a/event-schemas/schema/core-event-schema/sync_room_event.yaml b/event-schemas/schema/core-event-schema/sync_room_event.yaml new file mode 100644 index 00000000..8006148f --- /dev/null +++ b/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 diff --git a/event-schemas/schema/core-event-schema/sync_state_event.yaml b/event-schemas/schema/core-event-schema/sync_state_event.yaml new file mode 100644 index 00000000..1b6ce9b2 --- /dev/null +++ b/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