Merge 70f6749c92 into d28e05af87

Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com>

changelogs/client_server/newsfragments/2255.clarification

@@ -0,0 +1 @@
+Usage of the `event_id_only` format for push notifications is not mandatory.

changelogs/server_server/newsfragments/2191.clarification

@@ -0,0 +1 @@
+Clarify what the minimum_valid_until_ts field means when it is set in key queries.

data/api/client-server/pusher.yaml

@@ -230,11 +230,14 @@ paths:
                     format:
                       type: string
                       description: |-
-                        The format to send notifications in to Push Gateways if the
+                        The format in which to send notifications to the push gateway
-                        `kind` is `http`. The details about what fields the
+                        if the `kind` is `http`. The details about what fields the
-                        homeserver should send to the push gateway are defined in the
+                        homeserver should include are defined in the
-                        [Push Gateway Specification](/push-gateway-api/). Currently the only format
+                        [Push Gateway Specification](/push-gateway-api/). If omitted,
-                        available is 'event_id_only'.
+                        the server is expected to populate all of the event-related fields
+                        specified in [`/_matrix/push/v1/notify`](/push-gateway-api/#post_matrixpushv1notify).
+                      enum:
+                        - "event_id_only"
                 append:
                   type: boolean
                   description: |-

data/api/server-server/keys_query.yaml

@@ -34,8 +34,8 @@ paths:
         - in: query
           name: minimum_valid_until_ts
           description: |-
-            A millisecond POSIX timestamp in milliseconds indicating when the returned
+            A millisecond POSIX timestamp. The returned keys MUST be valid
-            certificates will need to be valid until to be useful to the requesting server.
+            until at least this timestamp.
 
             If not supplied, the current time as determined by the notary server is used.
           required: false
@@ -98,9 +98,8 @@ paths:
                           type: integer
                           format: int64
                           description: |-
-                            A millisecond POSIX timestamp in milliseconds indicating when
+                            A millisecond POSIX timestamp. The returned keys
-                            the returned certificates will need to be valid until to be
+                            MUST be valid until at least this timestamp.
-                            useful to the requesting server.
 
                             If not supplied, the current time as determined by the notary
                             server is used.