Minor tweaks; allow objects without props/parents if a title is set

This allows us to do things like {Tweaks} where Tweaks is defined somewhere
else.

api/client-server/v1/push_notifier.yaml

@@ -18,7 +18,7 @@ paths:
       description: |-
         This endpoint is invoked by HTTP pushers to notify a push gateway about
         an event.
-        *NB: Notifications are send to the URL configured when the pusher is
+        *NB: Notifications are sent to the URL configured when the pusher is
         created. This means that the HTTP path may be different depending on the
         push gateway.*
       parameters:
@@ -111,10 +111,6 @@ paths:
                   content:
                     type: object
                     title: EventContent
-                    properties:
-                      body:
-                        type: string
-                        description: Message text
                     description: |-
                       The ``content`` field from the event, if present. If the
                       event had no content field, this field is omitted.
@@ -162,21 +158,12 @@ paths:
                         A dictionary of additional pusher-specific data. For
                         'http' pushers, this is the data dictionary passed in at
                         pusher creation minus the ``url`` key.
-                      properties:
-                        foo:
-                          type: string
                     tweaks:
                       type: object
                       title: Tweaks
                       description: |-
                         A dictionary of customisations made to the way this
                         notification is to be presented. These are added by push rules.
-                      properties:
-                        sound:
-                          type: string
-                          description: |-
-                            Sets the sound file that should be played.
-                            ``default`` means that a default sound should be played.
       responses:
         200:
           description: A list of rejected push keys.

api/client-server/v1/pusher.yaml

@@ -69,7 +69,7 @@ paths:
                 description: |-
                   This is a string that determines what set of device rules will
                   be matched when evaluating push rules for this pusher. It is
-                  an arbitrary string. Multiple devices maybe use the same
+                  an arbitrary string. Multiple devices may use the same
                   ``profile_tag``. It is advised that when an app's data is
                   copied or restored to a different device, this value remain
                   the same. Client apps should offer ways to change the

specification/modules/push.rst

@@ -5,21 +5,21 @@ Push Notifications
 
 ::
 
-                                   +--------------------+ +-------------------+
+                                   +--------------------+  +-------------------+
-                  Matrix HTTP      |                    | |                   |
+                  Matrix HTTP      |                    |  |                   |
-             Notification Protocol |   App Developer    | |   Device Vendor   |
+             Notification Protocol |   App Developer    |  |   Device Vendor   |
-                                   |                    | |                   |
+                                   |                    |  |                   |
-           +-------------------+   | +----------------+ | | +---------------+ |
+           +-------------------+   | +----------------+ |  | +---------------+ |
-           |                   |   | |                | | | |               | |
+           |                   |   | |                | |  | |               | |
-           | Matrix Home Server+----->  Push Gateway  | +---> Push Provider | |
+           | Matrix Home Server+----->  Push Gateway  +------> Push Provider | |
-           |                   |   | |                | | | |               | |
+           |                   |   | |                | |  | |               | |
-           +-^-----------------+   | +----------------+ | | +----+----------+ |
+           +-^-----------------+   | +----------------+ |  | +----+----------+ |
-             |                     |                    | |      |            |
+             |                     |                    |  |      |            |
-    Matrix   |                     |                    | |      |            |
+    Matrix   |                     |                    |  |      |            |
- Client/Server API  +              |                    | |      |            |
+ Client/Server API  +              |                    |  |      |            |
-             |      |              +--------------------+ +-------------------+
+             |      |              +--------------------+  +-------------------+
-             |   +--+-+                                          |             
+             |   +--+-+                                           |             
-             |   |    <------------------------------------------+             
+             |   |    <-------------------------------------------+             
              +---+    |                                                        
                  |    |          Provider Push Protocol                        
                  +----+                                                        
@@ -28,7 +28,7 @@ Push Notifications
 
 
 This module adds support for push notifications. Homeservers send notifications
-of user events to user-configured HTTP endpoints. Users may also configure a
+of events to user-configured HTTP endpoints. Users may also configure a
 number of rules that determine which events generate notifications. These are
 all stored and managed by the user's homeserver. This allows user-specific push
 settings to be reused between client applications.
@@ -105,8 +105,8 @@ Override Rules ``override``
 Content-specific Rules ``content``
   These configure behaviour for (unencrypted) messages that match certain
   patterns. Content rules take one parameter: ``pattern``, that gives the glob
-  pattern to match against. This is treated in the same way as pattern for
+  pattern to match against. This is treated in the same way as ``pattern`` for
-  ``event_match`` conditions, below.
+  ``event_match``.
 Room-specific Rules ``room``
   These rules change the behaviour of all messages for a given room. The
   ``rule_id`` of a room rule is always the ID of the room that it affects.
@@ -146,6 +146,51 @@ match an event, the homeserver MUST NOT notify the Push Gateway for that event.
 Homeservers MUST NOT notify the Push Gateway for events that the user has sent
 themselves.
 
+Actions
++++++++
+All rules have an associated list of ``actions``. An action affects if and how a
+notification is delivered for a matching event. The following actions are defined:
+
+``notify``
+  This causes each matching event to generate a notification.
+``dont_notify``
+  This prevents each matching event from generating a notification
+``coalesce``
+  This enables notifications for matching events but activates homeserver
+  specific behaviour to intelligently coalesce multiple events into a single 
+  notification. Not all homeservers may support this. Those that do not support
+  it should treat it as the ``notify`` action.
+``set_tweak``
+  Sets an entry in the ``tweaks`` dictionary key that is sent in the notification
+  request to the Push Gateway. This takes the form of a dictionary with a
+  ``set_tweak`` key whose value is the name of the tweak to set. It may also
+  have a ``value`` key which is the value to which it should be set.
+
+Actions that have no parameters are represented as a string. Otherwise, they are
+represented as a dictionary with a key equal to their name and other keys as
+their parameters, e.g. ``{ "set_tweak": "sound", "value": "default" }``
+
+Tweaks
+^^^^^^
+The ``set_tweak`` action is used to add an entry to the 'tweaks' dictionary
+that is sent in the notification request to the Push Gateway. The following
+tweaks are defined:
+
+``sound``
+  A string representing the sound to be played when this notification arrives.
+  A value of ``default`` means to play a default sound.
+``highlight``
+  A boolean representing whether or not this message should be highlighted in
+  the UI. This will normally take the form of presenting the message in a
+  different colour and/or style. The UI might also be adjusted to draw
+  particular attention to the room in which the event occurred. The ``value``
+  may be omitted from the highlight tweak, in which case it should default to
+  ``true``.
+
+Tweaks are passed transparently through the homeserver so client applications
+and Push Gateways may agree on additional tweaks. For example, a tweak may be
+added to specify how to flash the notification light on a mobile device.
+
 Predefined Rules
 ++++++++++++++++
 Homeservers can specify "server-default rules" which operate at a lower priority
@@ -251,49 +296,7 @@ server-default rules are specified:
         ],
     }
 
-Actions
-+++++++
-All rules have an associated list of ``actions``. An action affects if and how a
-notification is delivered for a matching event. The following actions are defined:
-
-``notify``
-  This causes each matching event to generate a notification.
-``dont_notify``
-  This prevents this event from generating a notification
-``coalesce``
-  This enables notifications for matching events but activates homeserver
-  specific behaviour to intelligently coalesce multiple events into a single 
-  notification. Not all homeservers may support this. Those that do not support
-  it should treat it as the ``notify`` action.
-``set_tweak``
-  Sets an entry in the ``tweaks`` dictionary key that is sent in the notification
-  request. This takes the form of a dictionary with a ``set_tweak`` key whose value
-  is the name of the tweak to set. It may also have a ``value`` key which is
-  the value to which it should be set.
-
-Actions that have no parameters are represented as a string. Otherwise, they are
-represented as a dictionary with a key equal to their name and other keys as
-their parameters, e.g. ``{ "set_tweak": "sound", "value": "default" }``
-
-Tweaks
-^^^^^^
-The ``set_tweak`` action is used to add an entry to the 'tweaks' dictionary
-that is sent in the notification request. The following tweaks are defined:
 
-``sound``
-  A string representing the sound to be played when this notification arrives.
-  A value of ``default`` means to play a default sound.
-``highlight``
-  A boolean representing whether or not this message should be highlighted in
-  the UI. This will normally take the form of presenting the message in a
-  different colour and/or style. The UI might also be adjusted to draw
-  particular attention to the room in which the event occurred. The ``value``
-  may be omitted from the highlight tweak, in which case it should default to
-  ``true``.
-
-Tweaks are passed transparently through the homeserver so client applications
-and Push Gateways may agree on additional tweaks. For example, a tweak may be
-added to specify how to flash the notification light on a mobile device.
 
 Conditions
 ++++++++++
@@ -396,8 +399,8 @@ Server behaviour
 ----------------
 
 This describes the format used by "HTTP" pushers to send notifications of
-events. If the endpoint returns an HTTP error code, the homeserver should retry
+events to Push Gateways. If the endpoint returns an HTTP error code, the
-for a reasonable amount of time with a reasonable back-off scheme.
+homeserver SHOULD retry for a reasonable amount of time using exponential-backoff.
 
 {{push_notifier_http_api}}
 

templating/matrix_templates/units.py

@@ -61,6 +61,13 @@ def get_json_schema_object_fields(obj, enforce_title=False):
                 if pretty_key:
                     props[pretty_key] = props[key_name]
                     del props[key_name]
+    if not props and not parents:
+        # Sometimes you just want to specify that a thing is an object without
+        # doing all the keys. Allow people to do that if they set a 'title'.
+        if obj.get("title"):
+            parents = [{
+                "$ref": obj.get("title")
+            }]
     if not props and not parents:
         raise Exception(
             "Object %s has no properties or parents." % obj