Merge 7506e9ab89 into f6d5009959

Signed-off-by: Andy Balaam <andy.balaam@matrix.org>

changelogs/application_service/newsfragments/2182.clarification

@@ -0,0 +1 @@
+Minor fixes to JSON schemas.

changelogs/client_server/newsfragments/2132.clarification

@@ -0,0 +1 @@
+Declare the event schemas to follow JSON Schema spec 2020-12.

changelogs/client_server/newsfragments/2182.clarification

@@ -0,0 +1 @@
+Minor fixes to JSON schemas.

changelogs/client_server/newsfragments/2187.feature

@@ -0,0 +1 @@
+Add the `use_state_after` query parameter and `state_after` response property to `GET /sync`, as per [MSC4222](https://github.com/matrix-org/matrix-spec-proposals/issues/4222).

changelogs/internal/newsfragments/2189.clarification

@@ -0,0 +1 @@
+Specify a correct spelling for "display name".

changelogs/internal/newsfragments/2190.clarification

@@ -0,0 +1 @@
+Clarify that clients should replace events with the most recent replacement by origin_server_ts.

content/client-server-api/modules/event_replacements.md

@@ -195,7 +195,7 @@ given event (for example, if an event is edited multiple times). These should
 be [aggregated](#aggregations-of-child-events) by the homeserver.
 
 The aggregation format of `m.replace` relationships gives the **most recent**
-replacement event, formatted [as normal](#room-event-format).
+valid replacement event, formatted [as normal](#room-event-format).
 
 The most recent event is determined by comparing `origin_server_ts`; if two or
 more replacement events have identical `origin_server_ts`, the event with the
@@ -268,6 +268,11 @@ Client authors are reminded to take note of the requirements for [Validity of
 replacement events](#validity-of-replacement-events), and to ignore any
 invalid replacement events that are received.
 
+Clients should render the content of the **most recent** valid replacement event. The
+most recent event is determined by comparing `origin_server_ts`; if two or more
+replacement events have identical `origin_server_ts`, the event with the
+lexicographically largest `event_id` is treated as more recent.
+
 ##### Permalinks
 
 When creating [links](/appendices/#uris) to events (also known as permalinks),

data/api/application-service/definitions/protocol.yaml

@@ -23,3 +23,4 @@ allOf:
       type: array
       items:
         $ref: protocol_instance.yaml
+  required: ['instances']

data/api/application-service/definitions/protocol_base.yaml

@@ -77,4 +77,4 @@ properties:
         "placeholder": "#foobar"
       }
     }
-required: ['user_fields', 'location_fields', 'icon', 'field_types', 'instances']
+required: ['user_fields', 'location_fields', 'icon', 'field_types']

data/api/client-server/definitions/protocol.yaml

@@ -41,3 +41,4 @@ allOf:
                   This is the identifier to use as the `third_party_instance_id` in a request to
                   [`POST /_matrix/client/v3/publicRooms`](/client-server-api/#post_matrixclientv3publicrooms).
                 example: "irc-freenode"
+  required: ['instances']

data/api/client-server/definitions/room_summary.yaml

@@ -42,9 +42,3 @@ allOf:
       room_version:
         description: The version of the room.
         type: string
-
-required:
-  - room_id
-  - num_joined_members
-  - world_readable
-  - guest_can_join

data/api/client-server/room_summary.yaml

@@ -89,11 +89,6 @@ paths:
                           - leave
                           - ban
                         type: string
-                required:
-                  - guest_can_join
-                  - num_joined_members
-                  - room_id
-                  - world_readable
               examples:
                 response:
                   value: {

data/api/client-server/sync.yaml

@@ -117,6 +117,31 @@ paths:
           example: 30000
           schema:
             type: integer
+        - in: query
+          name: use_state_after
+          x-addedInMatrixVersion: "1.16"
+          description: |-
+            Controls whether to receive state changes between the previous sync
+            and the **start** of the timeline, or between the previous sync and
+            the **end** of the timeline.
+
+            If this is set to `true`, servers MUST respond with the state
+            between the previous sync and the **end** of the timeline in
+            `state_after` and MUST omit `state`.
+
+            If `false`, servers MUST respond with the state between the previous
+            sync and the **start** of the timeline in `state` and MUST omit
+            `state_after`.
+
+            Even if this is set to `true`, clients MUST update their local state
+            with events in `state` and `timeline` if `state_after` is missing in
+            the response, for compatibility with servers that don't support this
+            parameter.
+
+            By default, this is `false`.
+          example: false
+          schema:
+            type: boolean
       responses:
         "200":
           description: The initial snapshot or delta for the client to use to update their
@@ -197,16 +222,50 @@ paths:
                                 type: object
                                 description: |-
                                   Updates to the state, between the time indicated by
-                                  the `since` parameter, and the start of the
-                                  `timeline` (or all state up to the start of the
+                                  the `since` parameter, and the **start** of the
+                                  `timeline` (or all state up to the **start** of the
                                   `timeline`, if `since` is not given, or
                                   `full_state` is true).
 
-                                  N.B. state updates for `m.room.member` events will
+                                  {{% boxes/note %}}
+                                  State updates for `m.room.member` events will
                                   be incomplete if `lazy_load_members` is enabled in
                                   the `/sync` filter, and only return the member events
                                   required to display the senders of the timeline events
                                   in this response.
+                                  {{% /boxes/note %}}
+
+                                  MUST be omitted if `use_state_after` was set to `true`
+                                  in the request.
+                                allOf:
+                                  - $ref: definitions/state_event_batch.yaml
+                              state_after:
+                                title: State
+                                type: object
+                                x-addedInMatrixVersion: "1.16"
+                                description: |-
+                                  Updates to the state, between the time indicated by
+                                  the `since` parameter, and the **end** of the
+                                  `timeline` (or all state up to the **end** of the
+                                  `timeline`, if `since` is not given, or
+                                  `full_state` is true).
+
+                                  {{% boxes/note %}}
+                                  State updates for `m.room.member` events will
+                                  be incomplete if `lazy_load_members` is enabled in
+                                  the `/sync` filter, and only return the member events
+                                  required to display the senders of the timeline events
+                                  in this response.
+                                  {{% /boxes/note %}}
+
+                                  If this field is set, even if it is empty, clients MUST
+                                  only update their local state with events in this list,
+                                  and MUST NOT update their local state with events in
+                                  `timeline`. If this field is not set, clients MUST update
+                                  their local state with events in `state` and `timeline`.
+
+                                  **Required** if `use_state_after` was set to `true` in the
+                                  request, even if it is empty.
                                 allOf:
                                   - $ref: definitions/state_event_batch.yaml
                               timeline:
@@ -353,7 +412,28 @@ paths:
                               state:
                                 title: State
                                 type: object
-                                description: The state updates for the room up to the start of the timeline.
+                                description: |-
+                                  The state updates for the room up to the **start** of the timeline.
+
+                                  MUST be omitted if `use_state_after` was set to `true` in the
+                                  request.
+                                allOf:
+                                  - $ref: definitions/state_event_batch.yaml
+                              state_after:
+                                title: State
+                                type: object
+                                x-addedInMatrixVersion: "1.16"
+                                description: |-
+                                  The state updates for the room up to the **end** of the timeline.
+
+                                  If this field is set, even if it is empty, clients MUST only
+                                  update their local state with events in this list, and MUST NOT
+                                  update their local state with events in `timeline`. If this field
+                                  is not set, clients MUST update their local state with events in
+                                  `state` and `timeline`.
+
+                                  **Required** if `use_state_after` was set to `true` in the
+                                  request, even if it is empty.
                                 allOf:
                                   - $ref: definitions/state_event_batch.yaml
                               timeline:

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

@@ -1,15 +1,15 @@
 $schema: https://json-schema.org/draft/2020-12/schema
 
+title: RoomEvent
+description: Room Events have the following fields.
 allOf:
 - $ref: sync_room_event.yaml
-description: Room Events have the following fields.
-properties:
+- type: object
+  properties:
     room_id:
       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
-required:
-- room_id
-title: RoomEvent
-type: object
+  required:
+  - room_id

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

@@ -19,11 +19,13 @@
 
 $schema: https://json-schema.org/draft/2020-12/schema
 
-allOf:
-- $ref: event.yaml
+title: SyncRoomEvent
 description: In addition to the Event fields, Room Events have the following additional
   fields.
-properties:
+allOf:
+- $ref: event.yaml
+- type: object
+  properties:
     event_id:
       description: The globally unique event identifier.
       type: string
@@ -37,9 +39,7 @@ properties:
       format: int64
     unsigned:
       $ref: unsigned_prop.yaml
-required:
-- event_id
-- sender
-- origin_server_ts
-title: SyncRoomEvent
-type: object
+  required:
+  - event_id
+  - sender
+  - origin_server_ts

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

@@ -16,11 +16,13 @@
 
 $schema: https://json-schema.org/draft/2020-12/schema
 
-allOf:
-- $ref: sync_room_event.yaml
+title: SyncStateEvent
 description: In addition to the Room Event fields, State Events have the following
   additional fields.
-properties:
+allOf:
+- $ref: sync_room_event.yaml
+- type: object
+  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
@@ -30,7 +32,5 @@ properties:
         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: SyncStateEvent
-type: object
+  required:
+  - state_key

meta/documentation_style.rst

@@ -60,6 +60,11 @@ General
      you have at home. "identity server" is clear, whereas "identityserver" is
      horrible.
 
+* When talking about a user's "display name", it is spelt as two words. In
+  identifiers such as within the content of an ``m.room.member`` event, it is
+  spelt as a single word, ``displayname``. (There are some historical exceptions
+  to this where the identifier is spelt ``display_name``.)
+
 * Lists should:
 
   * Be introduced with a colon.
@@ -84,12 +89,12 @@ Changes between spec versions
 Sections should reference the Matrix spec version they were added/changed in. This
 is often a guess at what the next version will be - please use the currently released
 version with a minor version bump as the referenced version. For example, if the
-current version is `v1.1` then annotate your changes with `v1.2`.
+current version is ``v1.1`` then annotate your changes with ``v1.2``.
 
 "Added/changed in" tags can be documented as the following:
 
-* `{{% added-in v="1.2" %}}` or `{{% changed-in v="1.2" %}}` within Markdown documents.
-* `x-addedInMatrixVersion` and `x-changedInMatrixVersion` within OpenAPI.
+* ``{{% added-in v="1.2" %}}`` or ``{{% changed-in v="1.2" %}}`` within Markdown documents.
+* ``x-addedInMatrixVersion`` and ``x-changedInMatrixVersion`` within OpenAPI.
 
 OpenAPI
 ~~~~~~~
@@ -185,4 +190,4 @@ Describing grammar
 
 Use  `RFC5234-style ABNF <https://datatracker.ietf.org/doc/html/rfc5234>`_ when describing
 the grammar for something in the spec, such as user IDs or server names. Use lowercase
-and underscore-delimited element names (`user_id`, not `UserID` or `user-id`).
+and underscore-delimited element names (``user_id``, not ``UserID`` or ``user-id``).