From 55c0b968b5aaa86c9c37415dded849b060f47f24 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sun, 26 Aug 2018 22:22:14 -0600 Subject: [PATCH 1/6] 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 --- .../definitions/event_batch.yaml | 5 +- .../definitions/room_event_batch.yaml | 27 +++++++++ .../definitions/state_event_batch.yaml | 28 +++++++++ .../definitions/timeline_batch.yaml | 7 ++- api/client-server/sync.yaml | 9 +-- .../schema/core-event-schema/event.yaml | 1 + .../schema/core-event-schema/room_event.yaml | 39 ++---------- .../core-event-schema/sync_room_event.yaml | 60 +++++++++++++++++++ .../core-event-schema/sync_state_event.yaml | 35 +++++++++++ 9 files changed, 167 insertions(+), 44 deletions(-) create mode 100644 api/client-server/definitions/room_event_batch.yaml create mode 100644 api/client-server/definitions/state_event_batch.yaml create mode 100644 event-schemas/schema/core-event-schema/sync_room_event.yaml create mode 100644 event-schemas/schema/core-event-schema/sync_state_event.yaml diff --git a/api/client-server/definitions/event_batch.yaml b/api/client-server/definitions/event_batch.yaml index 21377a41926..d169c355554 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 00000000000..7367198fe64 --- /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 00000000000..db01ecb104f --- /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 ce613ac437d..abf93830dac 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 4b44c20e139..6a1d4f60242 100644 --- a/api/client-server/sync.yaml +++ b/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", diff --git a/event-schemas/schema/core-event-schema/event.yaml b/event-schemas/schema/core-event-schema/event.yaml index 7a06028313d..0fe5ac6c515 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 a8a23f54909..007372a5e7f 100644 --- a/event-schemas/schema/core-event-schema/room_event.yaml +++ b/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. - 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: 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 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 00000000000..300dfb2b56a --- /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: 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 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 00000000000..a073caac829 --- /dev/null +++ b/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 From fd47184ce37d4b6c387ed5d884c11946e560d20a Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sun, 26 Aug 2018 22:23:38 -0600 Subject: [PATCH 2/6] Changelog --- changelogs/client_server/newsfragments/1573.clarification | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/1573.clarification diff --git a/changelogs/client_server/newsfragments/1573.clarification b/changelogs/client_server/newsfragments/1573.clarification new file mode 100644 index 00000000000..74efa28f3fc --- /dev/null +++ b/changelogs/client_server/newsfragments/1573.clarification @@ -0,0 +1 @@ +Clarify the event fields used in the ``/sync`` response. From efef3412a0278d1dff714a8fe9c157369e4db2ff Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 Aug 2018 19:07:32 -0600 Subject: [PATCH 3/6] Take out the underscore restriction from state events It's not needed anymore, and we should remove it while we're in the area. Includes other misc changes to the schema layout. --- .../schema/core-event-schema/state_event.yaml | 14 +------------- .../schema/core-event-schema/sync_room_event.yaml | 3 +-- .../schema/core-event-schema/sync_state_event.yaml | 2 +- 3 files changed, 3 insertions(+), 16 deletions(-) diff --git a/event-schemas/schema/core-event-schema/state_event.yaml b/event-schemas/schema/core-event-schema/state_event.yaml index 020e9087a60..37d4426f6e8 100644 --- a/event-schemas/schema/core-event-schema/state_event.yaml +++ b/event-schemas/schema/core-event-schema/state_event.yaml @@ -1,19 +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. The key MUST NOT start with '_'. - 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 index 300dfb2b56a..fbbf154fac6 100644 --- a/event-schemas/schema/core-event-schema/sync_room_event.yaml +++ b/event-schemas/schema/core-event-schema/sync_room_event.yaml @@ -26,8 +26,7 @@ properties: description: The globally unique event identifier. type: string sender: - description: Contains the fully-qualified ID of the user who *sent* - this event. + 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 diff --git a/event-schemas/schema/core-event-schema/sync_state_event.yaml b/event-schemas/schema/core-event-schema/sync_state_event.yaml index a073caac829..30af969880b 100644 --- a/event-schemas/schema/core-event-schema/sync_state_event.yaml +++ b/event-schemas/schema/core-event-schema/sync_state_event.yaml @@ -27,7 +27,7 @@ properties: 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 '_'. + key makes this event a State Event. type: string required: - state_key From fc037b3a7210863814444e545aaaa542702a0c7f Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 31 Aug 2018 09:33:30 -0600 Subject: [PATCH 4/6] Fix merge --- event-schemas/schema/core-event-schema/sync_room_event.yaml | 3 ++- event-schemas/schema/core-event-schema/sync_state_event.yaml | 4 ++++ 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/event-schemas/schema/core-event-schema/sync_room_event.yaml b/event-schemas/schema/core-event-schema/sync_room_event.yaml index fbbf154fac6..8006148fe60 100644 --- a/event-schemas/schema/core-event-schema/sync_room_event.yaml +++ b/event-schemas/schema/core-event-schema/sync_room_event.yaml @@ -31,7 +31,8 @@ properties: origin_server_ts: description: Timestamp in milliseconds on originating homeserver when this event was sent. - type: number + type: integer + format: int64 unsigned: description: Contains optional extra information about the event. properties: diff --git a/event-schemas/schema/core-event-schema/sync_state_event.yaml b/event-schemas/schema/core-event-schema/sync_state_event.yaml index 30af969880b..1b6ce9b2234 100644 --- a/event-schemas/schema/core-event-schema/sync_state_event.yaml +++ b/event-schemas/schema/core-event-schema/sync_state_event.yaml @@ -28,6 +28,10 @@ properties: 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 From 2f824df8dd72454909087ccfafcb6bf9c778d1e0 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 31 Aug 2018 09:43:29 -0600 Subject: [PATCH 5/6] Define the real event types on the invite_state --- api/client-server/sync.yaml | 25 +++++++++++++++++++++++-- 1 file changed, 23 insertions(+), 2 deletions(-) diff --git a/api/client-server/sync.yaml b/api/client-server/sync.yaml index 0f096e13788..9422abb4160 100644 --- a/api/client-server/sync.yaml +++ b/api/client-server/sync.yaml @@ -202,8 +202,29 @@ paths: the room then the current state will be given as a delta against the archived ``state`` not the ``invite_state``. - allOf: - - $ref: "definitions/state_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`` 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 + required: + - type + - state_key + - content + title: StrippedState + type: object + type: array leave: title: Left rooms type: object From e3ad253dcaeb184e64147d1f4ecbd4e06b4c7834 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 31 Aug 2018 09:44:29 -0600 Subject: [PATCH 6/6] A sender is also required for the invite_state --- api/client-server/sync.yaml | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/api/client-server/sync.yaml b/api/client-server/sync.yaml index 9422abb4160..bb514bbeb2f 100644 --- a/api/client-server/sync.yaml +++ b/api/client-server/sync.yaml @@ -206,7 +206,9 @@ paths: events: description: The StrippedState events that form the invite state. items: - description: 'A stripped down state event, with only the ``type``, ``state_key`` and ``content`` keys.' + description: |- + A stripped down state event, with only the ``type``, ``state_key``, + ``sender``, and ``content`` keys. properties: content: description: The ``content`` for the event. @@ -218,10 +220,14 @@ paths: 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