From 8328e485ea7336d11886d47caafc7851de9c9c73 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Wed, 27 Jul 2016 13:50:11 +0100 Subject: [PATCH] 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. --- .../definitions/push_condition.yaml | 26 +++++++++++++- api/client-server/definitions/push_rule.yaml | 32 +++++++++++++++-- api/client-server/pushrules.yaml | 35 ++++++++++--------- changelogs/client_server.rst | 2 ++ 4 files changed, 76 insertions(+), 19 deletions(-) diff --git a/api/client-server/definitions/push_condition.yaml b/api/client-server/definitions/push_condition.yaml index 7647d197..796a51f4 100644 --- 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 diff --git a/api/client-server/definitions/push_rule.yaml b/api/client-server/definitions/push_rule.yaml index 465880c3..14a9b7d4 100644 --- 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 diff --git a/api/client-server/pushrules.yaml b/api/client-server/pushrules.yaml index e38fe6db..939150fe 100644 --- 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: diff --git a/changelogs/client_server.rst b/changelogs/client_server.rst index 0fc63669..8d903cd0 100644 --- a/changelogs/client_server.rst +++ b/changelogs/client_server.rst @@ -7,6 +7,8 @@ (`#362 `_). - Emphasise that ``POST /tokenrefresh`` should expire the access token (`#363 `_). + - Clarify the fields which are applicable to different types of push rule + (`#365 `_). - Changes to the API which will be backwards-compatible for clients: