Fix requiredness syntax

content/client-server-api/modules/report_content.md

@@ -35,14 +35,3 @@ based on whether or not the reporting user is joined to any rooms that the
 reported user is joined to. This is because users can be exposed to harmful
 content without being joined to a room. For instance, through user
 directories or invites.
-
-Clients can infer whether a reported event, room or user exists based on the
-404 responses of the reporting endpoints. Homeservers that wish to conceal
-this information MAY return 200 responses regardless of the existence of the
-reported subject.
-
-Furthermore, it might be possible for clients to deduce whether a reported
-event, room or user exists by timing the response. This is because only a
-report for an existing subject will require the homeserver to do further
-processing. To combat this, homeserver implementations MAY add a random
-delay when generating a response.

data/api/client-server/report_content.yaml

@@ -45,7 +45,9 @@ paths:
               properties:
                 reason:
                   type: string
-                  description: The reason the room is being reported.
+                  description: The reason the room is being reported. May be blank.
+              required:
+                - reason
         required: true
       security:
         - accessTokenQuery: []
@@ -88,6 +90,11 @@ paths:
         Reports an event as inappropriate to the server, which may then notify
         the appropriate people. The caller must be joined to the room to report
         it.
+
+        Furthermore, it might be possible for clients to deduce whether a reported
+        event exists by timing the response. This is because only a report for an
+        existing event will require the homeserver to do further processing. To
+        combat this, homeservers MAY add a random delay when generating a response.
       operationId: reportEvent
       parameters:
         - in: path
@@ -169,6 +176,15 @@ paths:
         that the reported user is joined to.
 
         Clients may wish to [ignore](#ignoring-users) users after reporting them.
+
+        Clients could infer whether a reported user exists based on the 404 response.
+        Homeservers that wish to conceal this information MAY return 200 responses
+        regardless of the existence of the reported user.
+
+        Furthermore, it might be possible for clients to deduce whether a reported
+        user exists by timing the response. This is because only a report for an
+        existing user will require the homeserver to do further processing. To
+        combat this, homeservers MAY add a random delay when generating a response.
       operationId: reportUser
       parameters:
         - in: path
@@ -191,14 +207,18 @@ paths:
               properties:
                 reason:
                   type: string
-                  description: The reason the room is being reported.
+                  description: The reason the room is being reported. May be blank.
+              required:
+                - reason
         required: true
       security:
         - accessTokenQuery: []
         - accessTokenBearer: []
       responses:
         "200":
-          description: The user has been reported successfully.
+          description: |
+            The user has been reported successfully or the server chose
+            to not disclose whether the users exists.
           content:
             application/json:
               schema: