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,8 +13,9 @@
 # limitations under the License.
 allOf:
 - $ref: event_filter.yaml
-title: RoomEventFilter
+- type: object
-properties:
+  title: RoomEventFilter
+  properties:
     not_rooms:
       description: A list of room IDs to exclude. If this list is absent then no rooms
         are excluded. A matching room will be excluded even if it is listed in the ``'rooms'``
@@ -30,6 +31,5 @@ properties:
       type: array
     contains_url:
       type: boolean
-    description: If ``true``, includes only events with a url key in their content. If
+      description: If ``true``, includes only events with a ``url`` key in their content. If
-      ``false``, excludes those events.
+        ``false``, excludes those events. Defaults to ``false``.
-type: object

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

@@ -81,17 +81,18 @@ paths:
       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.