Merge pull request #1570 from turt2live/travis/c2s/sync-filtering

Update filtering API documentation

api/client-server/definitions/event_filter.yaml

@@ -11,7 +11,7 @@
 # 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: Filter
+title: EventFilter
 properties:
   limit:
     description: The maximum number of events to return.

api/client-server/definitions/room_event_filter.yaml

@@ -13,23 +13,23 @@
 # limitations under the License.
 allOf:
 - $ref: event_filter.yaml
-title: RoomEventFilter
+- type: object
-properties:
+  title: RoomEventFilter
-  not_rooms:
+  properties:
-    description: A list of room IDs to exclude. If this list is absent then no rooms
+    not_rooms:
-      are excluded. A matching room will be excluded even if it is listed in the ``'rooms'``
+      description: A list of room IDs to exclude. If this list is absent then no rooms
-      filter.
+        are excluded. A matching room will be excluded even if it is listed in the ``'rooms'``
-    items:
+        filter.
-      type: string
+      items:
-    type: array
+        type: string
-  rooms:
+      type: array
-    description: A list of room IDs to include. If this list is absent then all rooms
+    rooms:
-      are included.
+      description: A list of room IDs to include. If this list is absent then all rooms
-    items:
+        are included.
-      type: string
+      items:
-    type: array
+        type: string
-  contains_url:
+      type: array
-    type: boolean
+    contains_url:
-    description: If ``true``, includes only events with a url key in their content. If
+      type: boolean
-      ``false``, excludes those events.
+      description: If ``true``, includes only events with a ``url`` key in their content. If
-type: object
+        ``false``, excludes those events. Defaults to ``false``.

api/client-server/definitions/sync_filter.yaml

@@ -11,6 +11,8 @@
 # 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.
+type: object
+title: Filter
 properties:
   event_fields:
     description: List of event fields to include. If this list is absent then all
@@ -40,6 +42,7 @@ properties:
   room:
     title: RoomFilter
     description: Filters to be applied to room data.
+    type: object
     properties:
       not_rooms:
         description: A list of room IDs to exclude. If this list is absent then no rooms
@@ -76,5 +79,3 @@ properties:
         allOf:
         - $ref: room_event_filter.yaml
         description: The per user account data to include for rooms.
-    type: object
-type: object

api/client-server/filter.yaml

@@ -54,44 +54,45 @@ paths:
             allOf:
               - $ref: "definitions/sync_filter.yaml"
             example: {
-                "room": {
+              "room": {
-                  "state": {
+                "state": {
-                    "types": ["m.room.*"],
+                  "types": ["m.room.*"],
-                    "not_rooms": ["!726s6s6q:example.com"]
+                  "not_rooms": ["!726s6s6q:example.com"]
-                  },
-                  "timeline": {
-                    "limit": 10,
-                    "types": ["m.room.message"],
-                    "not_rooms": ["!726s6s6q:example.com"],
-                    "not_senders": ["@spam:example.com"]
-                  },
-                  "ephemeral": {
-                    "types": ["m.receipt", "m.typing"],
-                    "not_rooms": ["!726s6s6q:example.com"],
-                    "not_senders": ["@spam:example.com"]
-                  }
                 },
-                "presence": {
+                "timeline": {
-                  "types": ["m.presence"],
+                  "limit": 10,
-                  "not_senders": ["@alice:example.com"]
+                  "types": ["m.room.message"],
+                  "not_rooms": ["!726s6s6q:example.com"],
+                  "not_senders": ["@spam:example.com"]
                 },
-                "event_format": "client",
+                "ephemeral": {
-                "event_fields": ["type", "content", "sender"]
+                  "types": ["m.receipt", "m.typing"],
-              }
+                  "not_rooms": ["!726s6s6q:example.com"],
+                  "not_senders": ["@spam:example.com"]
+                }
+              },
+              "presence": {
+                "types": ["m.presence"],
+                "not_senders": ["@alice:example.com"]
+              },
+              "event_format": "client",
+              "event_fields": ["type", "content", "sender"]
+            }
       responses:
         200:
           description: The filter was created.
-          examples:
-            application/json: {
-                "filter_id": "66696p746572"
-              }
           schema:
             type: object
             properties:
               filter_id:
                 type: string
                 description: |-
-                  The ID of the filter that was created.
+                  The ID of the filter that was created. Cannot start
+                  with a ``{`` as this character is used to determine
+                  if the filter provided is inline JSON or a previously
+                  declared filter by homeservers on some APIs.
+                example: "66696p746572"
+            required: ['filter_id']
       tags:
         - Room participation
   "/user/{userId}/filter/{filterId}":

changelogs/client_server/newsfragments/1570.clarification

@@ -0,0 +1 @@
+Clarify the object structures and defaults for Filters.