Clean up the pushrules API doc

* make it clearer which fields go in which parts of the rule * the example given appeared to be for a content rule, so use a content rule consistently through the examples.
8 years ago · 8328e485ea
parent 9a2af4fbc1
commit 8328e485ea
4 changed files with 76 additions and 19 deletions
--- a/api/client-server/definitions/push_condition.yaml
+++ b/api/client-server/definitions/push_condition.yaml
@ -11,6 +11,9 @@
 # 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.
+
+title: PushCondition
+type: object
 properties:
  kind:
    enum:
@ -18,4 +21,25 @@ properties:
    - contains_display_name
    - room_member_count
    type: string
-type: object
+  key:
+    type: string
+    description: |-
+      Required for ``event_match`` conditions. The dot-separated field of the
+      event to match.
+    x-example: content.body
+  pattern:
+    type: string
+    description: |-
+      Required for ``event_match`` conditions. The glob-style pattern to
+      match against. Patterns with no special glob characters should be
+      treated as having asterisks prepended and appended when testing the
+      condition.
+  is:
+    type: string
+    description: |-
+      Required for ``room_member_count`` conditions. A decimal integer
+      optionally prefixed by one of, ==, <, >, >= or <=. A prefix of < matches
+      rooms where the member count is strictly less than the given number and
+      so forth. If no prefix is present, this parameter defaults to ==.
+required:
+  - kind
--- a/api/client-server/definitions/push_rule.yaml
+++ b/api/client-server/definitions/push_rule.yaml
@ -11,6 +11,9 @@
 # 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.
+
+title: PushRule
+type: object
 properties:
  actions:
    items:
@ -18,11 +21,36 @@ properties:
      - object
      - string
    type: array
+    description: |-
+      The actions to perform when this rule is matched.
  default:
    type: boolean
+    description: |-
+      Whether this is a default rule, or has been set explicitly.
  enabled:
    type: boolean
+    description: |-
+      Whether the push rule is enabled or not.
  rule_id:
    type: string
-title: PushRule
-type: object
+    description: |-
+      The ID of this rule.
+  conditions:
+    type: array
+    items:
+      allOf:
+      - $ref: push_condition.yaml
+    description: |-
+      The conditions that must hold true for an event in order for a rule to be
+      applied to an event. A rule with no conditions always matches. Only
+      applicable to ``underride`` and ``override`` rules.
+  pattern:
+    type: string
+    description: |-
+      The glob-style pattern to match against.  Only applicable to ``content``
+      rules.
+required:
+  - actions
+  - default
+  - enabled
+  - rule_id
--- a/api/client-server/pushrules.yaml
+++ b/api/client-server/pushrules.yaml
@ -262,7 +262,7 @@ paths:
          type: string
          name: kind
          required: true
-          x-example: room
+          x-example: content
          enum: ["override", "underride", "sender", "room", "content"]
          description: |
            The kind of rule
@ -270,7 +270,7 @@ paths:
          type: string
          name: ruleId
          required: true
-          x-example: "#spam:example.com"
+          x-example: "nocake"
          description: |
            The identifier for the rule.
      responses:
@ -284,13 +284,13 @@ paths:
                "actions": [
                    "dont_notify"
                ],
-                "rule_id": "#spam:matrix.org",
+                "pattern": "cake*lie",
+                "rule_id": "nocake",
                "enabled": true
              }
          schema:
            type: object
            description: The push rule.
-            title: PushRule
            allOf: [
              "$ref": "definitions/push_rule.yaml"
            ]
@ -314,7 +314,7 @@ paths:
          type: string
          name: kind
          required: true
-          x-example: room
+          x-example: content
          enum: ["override", "underride", "sender", "room", "content"]
          description: |
            The kind of rule
@ -322,7 +322,7 @@ paths:
          type: string
          name: ruleId
          required: true
-          x-example: "#spam:example.com"
+          x-example: "nocake"
          description: |
            The identifier for the rule.
      responses:
@ -355,7 +355,7 @@ paths:
          type: string
          name: kind
          required: true
-          x-example: room
+          x-example: content
          enum: ["override", "underride", "sender", "room", "content"]
          description: |
            The kind of rule
@ -363,7 +363,7 @@ paths:
          type: string
          name: ruleId
          required: true
-          x-example: "#spam:example.com"
+          x-example: "nocake"
          description: |
            The identifier for the rule.
        - in: query
@ -411,11 +411,14 @@ paths:
                description: |-
                  The conditions that must hold true for an event in order for a
                  rule to be applied to an event. A rule with no conditions
-                  always matches.
+                  always matches. Only applicable to ``underride`` and ``override`` rules.
                items:
                  type: object
-                  title: conditions
                  allOf: [ "$ref": "definitions/push_condition.yaml" ]
+              pattern:
+                type: string
+                description: |-
+                  Only applicable to ``content`` rules. The glob-style pattern to match against.
            required: ["actions"]
      responses:
        200:
@ -461,7 +464,7 @@ paths:
          type: string
          name: kind
          required: true
-          x-example: room
+          x-example: cake
          enum: ["override", "underride", "sender", "room", "content"]
          description: |
            The kind of rule
@ -469,7 +472,7 @@ paths:
          type: string
          name: ruleId
          required: true
-          x-example: "#spam:example.com"
+          x-example: nocake
          description: |
            The identifier for the rule.
      responses:
@ -505,7 +508,7 @@ paths:
          type: string
          name: kind
          required: true
-          x-example: room
+          x-example: content
          enum: ["override", "underride", "sender", "room", "content"]
          description: |
            The kind of rule
@ -513,7 +516,7 @@ paths:
          type: string
          name: ruleId
          required: true
-          x-example: "#spam:example.com"
+          x-example: "nocake"
          description: |
            The identifier for the rule.
        - in: body
@ -562,7 +565,7 @@ paths:
          type: string
          name: kind
          required: true
-          x-example: room
+          x-example: content
          enum: ["override", "underride", "sender", "room", "content"]
          description: |
            The kind of rule
@ -570,7 +573,7 @@ paths:
          type: string
          name: ruleId
          required: true
-          x-example: "#spam:example.com"
+          x-example: nocake
          description: |
            The identifier for the rule.
      responses:
--- a/changelogs/client_server.rst
+++ b/changelogs/client_server.rst
@ -7,6 +7,8 @@
    (`#362 <https://github.com/matrix-org/matrix-doc/pull/362>`_).
  - Emphasise that ``POST /tokenrefresh`` should expire the access token
    (`#363 <https://github.com/matrix-org/matrix-doc/pull/363>`_).
+  - Clarify the fields which are applicable to different types of push rule
+    (`#365 <https://github.com/matrix-org/matrix-doc/pull/365>`_).

 - Changes to the API which will be backwards-compatible for clients: