Manual fixes to API files

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

data/api/client-server/appservice_room_directory.yaml

@@ -67,6 +67,7 @@ paths:
                 - visibility
         required: true
       security:
+        # again, this is the appservice's token - not a typical client's
         - accessToken: []
       responses:
         "200":
@@ -94,4 +95,6 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
+    # Note: this is the same access_token definition used elsewhere in the client
+    # server API, however this expects an access token for an application service.
     $ref: definitions/security.yaml

data/api/client-server/content-repo.yaml

@@ -38,12 +38,7 @@ paths:
             type: string
       requestBody:
         content:
-          application/json:
+          application/octet-stream:
-            schema:
-              type: string
-              example: <bytes>
-              format: byte
-          "*/*":
             schema:
               type: string
               example: <bytes>
@@ -146,12 +141,7 @@ paths:
             type: string
       requestBody:
         content:
-          application/json:
+          application/octet-stream:
-            schema:
-              type: string
-              example: <bytes>
-              format: byte
-          "*/*":
             schema:
               type: string
               example: <bytes>
@@ -168,9 +158,6 @@ paths:
               examples:
                 response:
                   value: {}
-            "*/*":
-              schema:
-                type: object
         "403":
           description: |-
             The user does not have permission to upload the content. Some reasons for this error include:
@@ -192,9 +179,6 @@ paths:
                     "errcode": "M_FORBIDDEN",
                     "error": "Cannot upload this content"
                   }
-            "*/*":
-              schema:
-                $ref: definitions/errors/error.yaml
         "409":
           description: |-
             The endpoint was called with a media ID that already has content. A
@@ -210,9 +194,6 @@ paths:
                     "errcode": "M_CANNOT_OVERWRITE_MEDIA",
                     "error": "Media already uploaded"
                   }
-            "*/*":
-              schema:
-                $ref: definitions/errors/error.yaml
         "413":
           description: The uploaded content is too large for the server.
           content:
@@ -225,18 +206,12 @@ paths:
                     "errcode": "M_TOO_LARGE",
                     "error": "Cannot upload files larger than 100mb"
                   }
-            "*/*":
-              schema:
-                $ref: definitions/errors/error.yaml
         "429":
           description: This request was rate-limited.
           content:
             application/json:
               schema:
                 $ref: definitions/errors/rate_limited.yaml
-            "*/*":
-              schema:
-                $ref: definitions/errors/rate_limited.yaml
       tags:
         - Media
   /media/v1/create:
@@ -266,6 +241,8 @@ paths:
       x-addedInMatrixVersion: "1.7"
       security:
         - accessToken: []
+      # empty json object
+      parameters: []
       responses:
         "200":
           description: The [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris) for
@@ -371,24 +348,23 @@ paths:
               schema:
                 type: string
           content:
-            "*/*":
+            application/octet-stream:
               schema:
                 type: string
+                # This is a workaround for us not being able to say the response is required.
                 description: "**Required.** The bytes for the uploaded file."
-                format: binary
         "429":
           description: This request was rate-limited.
           content:
-            "*/*":
+            application/json:
               schema:
                 $ref: definitions/errors/rate_limited.yaml
         "502":
           description: The content is too large for the server to serve.
           content:
-            "*/*":
+            application/json:
               schema:
                 $ref: definitions/errors/error.yaml
-            application/json:
               examples:
                 response:
                   value: {
@@ -400,10 +376,9 @@ paths:
             The content is not yet available. A [standard error response](/client-server-api/#standard-error-response)
             will be returned with the `errcode` `M_NOT_YET_UPLOADED`.
           content:
-            "*/*":
+            application/json:
               schema:
                 $ref: definitions/errors/error.yaml
-            application/json:
               examples:
                 response:
                   value: {
@@ -485,24 +460,24 @@ paths:
               schema:
                 type: string
           content:
-            "*/*":
+            application/octet-stream:
               schema:
                 type: string
+                # This is a workaround for us not being able to say the response is required.
                 description: "**Required.** The bytes for the uploaded file."
                 format: binary
         "429":
           description: This request was rate-limited.
           content:
-            "*/*":
+            application/json:
               schema:
                 $ref: definitions/errors/rate_limited.yaml
         "502":
           description: The content is too large for the server to serve.
           content:
-            "*/*":
+            application/json:
               schema:
                 $ref: definitions/errors/error.yaml
-            application/json:
               examples:
                 response:
                   value: {
@@ -514,10 +489,9 @@ paths:
             The content is not yet available. A [standard error response](/client-server-api/#standard-error-response)
             will be returned with the `errcode` `M_NOT_YET_UPLOADED`.
           content:
-            "*/*":
+            application/json:
               schema:
                 $ref: definitions/errors/error.yaml
-            application/json:
               examples:
                 response:
                   value: {
@@ -620,11 +594,13 @@ paths:
             image/jpeg:
               schema:
                 type: string
+                # This is a workaround for us not being able to say the response is required.
                 description: "**Required.** The bytes for the thumbnail."
                 format: binary
             image/png:
               schema:
                 type: string
+                # This is a workaround for us not being able to say the response is required.
                 description: "**Required.** The bytes for the thumbnail."
                 format: binary
         "400":
@@ -633,13 +609,9 @@ paths:
             the content. For example, the client requested non-integer dimensions or asked
             for negatively-sized images.
           content:
-            image/jpeg:
-              schema:
-                $ref: definitions/errors/error.yaml
-            image/png:
-              schema:
-                $ref: definitions/errors/error.yaml
             application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
               examples:
                 response:
                   value: {
@@ -649,13 +621,9 @@ paths:
         "413":
           description: The local content is too large for the server to thumbnail.
           content:
-            image/jpeg:
-              schema:
-                $ref: definitions/errors/error.yaml
-            image/png:
-              schema:
-                $ref: definitions/errors/error.yaml
             application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
               examples:
                 response:
                   value: {
@@ -665,22 +633,15 @@ paths:
         "429":
           description: This request was rate-limited.
           content:
-            image/jpeg:
+            application/json:
-              schema:
-                $ref: definitions/errors/rate_limited.yaml
-            image/png:
               schema:
                 $ref: definitions/errors/rate_limited.yaml
         "502":
           description: The remote content is too large for the server to thumbnail.
           content:
-            image/jpeg:
-              schema:
-                $ref: definitions/errors/error.yaml
-            image/png:
-              schema:
-                $ref: definitions/errors/error.yaml
             application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
               examples:
                 response:
                   value: {
@@ -692,13 +653,9 @@ paths:
             The content is not yet available. A [standard error response](/client-server-api/#standard-error-response)
             will be returned with the `errcode` `M_NOT_YET_UPLOADED`.
           content:
-            image/jpeg:
-              schema:
-                $ref: definitions/errors/error.yaml
-            image/png:
-              schema:
-                $ref: definitions/errors/error.yaml
             application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
               examples:
                 response:
                   value: {

data/api/client-server/definitions/push_rule.yaml

@@ -17,9 +17,9 @@ type: object
 properties:
   actions:
     items:
-      type:
+      oneOf:
-      - object
+      - type: object
-      - string
+      - type: string
     type: array
     description: |-
       The actions to perform when this rule is matched.

data/api/client-server/device_management.yaml

@@ -124,7 +124,7 @@ paths:
           content:
             application/json:
               schema:
-                type: object
+                type: object  # empty json object
               examples:
                 response:
                   value: {}

data/api/client-server/inviting.yaml

@@ -16,6 +16,8 @@ info:
   title: Matrix Client-Server Room Joining API
   version: 1.0.0
 paths:
+  # With an extra " " to disambiguate from the 3pid invite endpoint
+  # The extra space makes it sort first for what I'm sure is a good reason.
   "/rooms/{roomId}/invite ":
     post:
       summary: Invite a user to participate in a particular room.

data/api/client-server/joining.yaml

@@ -143,8 +143,6 @@ paths:
           example:
             - matrix.org
             - elsewhere.ca
-          style: form
-          explode: false
           schema:
             type: array
             items:

data/api/client-server/keys.yaml

@@ -38,6 +38,10 @@ paths:
                   allOf:
                     - $ref: definitions/device_keys.yaml
                 one_time_keys:
+                  # $ref: "definitions/one_time_keys.yaml"
+                  # XXX: We can't define an actual object here, so we have to hope
+                  # that people will look at the swagger source or can figure it out
+                  # from the other endpoints/example.
                   type: object
                   title: OneTimeKeys
                   description: |-
@@ -61,6 +65,8 @@ paths:
                           ed25519:JLAFKJWSCS: IQeCEPb9HFk217cU9kw9EOiusC6kMIkoIRnbnfOh5Oc63S1ghgyjShBGpu34blQomoalCyXWyhaaT3MrLZYQAA
                 fallback_keys:
                   x-addedInMatrixVersion: "1.2"
+                  # $ref: "definitions/one_time_keys.yaml"
+                  # XXX: We can't define an actual object here - see above.
                   type: object
                   title: OneTimeKeys
                   description: |-
@@ -346,6 +352,11 @@ paths:
                     additionalProperties:
                       type: object
                       additionalProperties:
+                        # $ref: "definitions/one_time_keys.yaml"
+                        # XXX: We can't define an actual object here, so we have to hope
+                        # that people will read the link provided in the description
+                        # and figure it out from the other endpoints/example.
+                        # See also one_time_key parameter for /keys/upload above.
                         type: object
                         title: OneTimeKeys
                     example:

data/api/client-server/knocking.yaml

@@ -55,8 +55,6 @@ paths:
           example:
             - matrix.org
             - elsewhere.ca
-          style: form
-          explode: false
           schema:
             type: array
             items:

data/api/client-server/peeking_events.yaml

@@ -16,6 +16,8 @@ info:
   title: Matrix Client-Server Sync Guest API
   version: 1.0.0
 paths:
+  # With an extra " " to disambiguate from the getEvents endpoint
+  # The extra space makes it sort first for what I'm sure is a good reason.
   "/events ":
     get:
       summary: Listen on the event stream of a particular room.

data/api/client-server/presence.yaml

@@ -65,7 +65,7 @@ paths:
           content:
             application/json:
               schema:
-                type: object
+                type: object  # empty json object
               examples:
                 response:
                   value: {}
@@ -113,8 +113,7 @@ paths:
                       by this user.
                   status_msg:
                     description: The state message for this user if one was set.
-                    nullable: true
+                    type: ["string", "null"]
-                    type: string
                   currently_active:
                     type: boolean
                     description: Whether the user is currently active

data/api/client-server/profile.yaml

@@ -53,7 +53,7 @@ paths:
           content:
             application/json:
               schema:
-                type: object
+                type: object  # empty json object
               examples:
                 response:
                   value: {}
@@ -139,7 +139,7 @@ paths:
           content:
             application/json:
               schema:
-                type: object
+                type: object  # empty json object
               examples:
                 response:
                   value: {}

data/api/client-server/pusher.yaml

@@ -174,8 +174,7 @@ paths:
                     The kind of pusher to configure. `"http"` makes a pusher that
                     sends HTTP pokes. `"email"` makes a pusher that emails the
                     user with unread notifications. `null` deletes the pusher.
-                  nullable: true
+                  type: ["string", "null"]
-                  type: string
                 app_id:
                   type: string
                   description: |-

data/api/client-server/pushrules.yaml

@@ -350,7 +350,7 @@ paths:
           content:
             application/json:
               schema:
-                type: object
+                type: object  # empty json object
               examples:
                 response:
                   value: {}
@@ -487,7 +487,7 @@ paths:
           content:
             application/json:
               schema:
-                type: object
+                type: object  # empty json object
               examples:
                 response:
                   value: {}

data/api/client-server/receipts.yaml

@@ -89,7 +89,7 @@ paths:
             application/json:
               schema:
                 type: object
-                maxProperties: 0
+                maxProperties: 0  # empty json object
               examples:
                 response:
                   value: {}

data/api/client-server/registration.yaml

@@ -66,6 +66,8 @@ paths:
           name: kind
           required: false
           description: The kind of account to register. Defaults to `user`.
+          # swagger-UI overrides the default with the example, so better make the
+          # example the default.
           example: user
           schema:
             type: string

data/api/client-server/relations.yaml

@@ -97,6 +97,8 @@ paths:
               - b
               - f
       responses:
+        # note: this endpoint deliberately does not support rate limiting, therefore a
+        # 429 error response is not included.
         "200":
           description: |-
             The paginated child events which point to the parent. If no events are
@@ -161,6 +163,7 @@ paths:
                   }
       tags:
         - Event relationships
+  # The same as above, with added `/{relType}`
   "/rooms/{roomId}/relations/{eventId}/{relType}":
     get:
       summary: Get the child events for a given parent event, with a given `relType`.
@@ -251,6 +254,8 @@ paths:
               - b
               - f
       responses:
+        # note: this endpoint deliberately does not support rate limiting, therefore a
+        # 429 error response is not included.
         "200":
           description: |-
             The paginated child events which point to the parent. If no events are
@@ -317,6 +322,7 @@ paths:
                   }
       tags:
         - Event relationships
+  # The same as above, with added `/{eventType}`
   "/rooms/{roomId}/relations/{eventId}/{relType}/{eventType}":
     get:
       summary: Get the child events for a given parent event, with a given `relType`
@@ -419,6 +425,8 @@ paths:
               - b
               - f
       responses:
+        # note: this endpoint deliberately does not support rate limiting, therefore a
+        # 429 error response is not included.
         "200":
           description: |-
             The paginated child events which point to the parent. If no events are

data/api/client-server/rooms.yaml

@@ -200,6 +200,9 @@ paths:
           example: YWxsCgpOb25lLDM1ODcwOA
           schema:
             type: string
+        # XXX: As mentioned in MSC1227, replacing `[not_]membership` with a JSON
+        # filter might be a better alternative.
+        # See https://github.com/matrix-org/matrix-doc/issues/1337
         - in: query
           name: membership
           description: |-

data/api/client-server/typing.yaml

@@ -70,7 +70,7 @@ paths:
           content:
             application/json:
               schema:
-                type: object
+                type: object  # empty json object
               examples:
                 response:
                   value: {}

data/api/identity/v2_terms.yaml

@@ -52,6 +52,7 @@ paths:
                             might be and could be "alpha", semantically versioned, or arbitrary.
                       required:
                         - version
+                      # TODO: TravisR - Make this render
                       additionalProperties:
                         type: object
                         title: Internationalised Policy

data/api/push-gateway/push_notifier.yaml

@@ -202,7 +202,7 @@ paths:
           content:
             application/json:
               schema:
-                type: object
+                type: object  # empty json object
                 properties:
                   rejected:
                     type: array

data/api/server-server/backfill.yaml

@@ -40,8 +40,6 @@ paths:
           required: true
           example:
             - $abc123:matrix.org
-          style: form
-          explode: false
           schema:
             type: array
             items:

data/api/server-server/definitions/unsigned_pdu_base.yaml

@@ -56,20 +56,21 @@ properties:
       maxItems: 2
       minItems: 2
       items:
-        - type: string
+        anyOf:
-          title: Event ID
+          - type: string
-          example: "$abc123:matrix.org"
+            title: Event ID
-        - type: object
+            example: "$abc123:matrix.org"
-          title: Event Hash
+          - type: object
-          example: {
+            title: Event Hash
-            "sha256": "Base64EncodedSha256HashesShouldBe43BytesLong"
+            example: {
-          }
+              "sha256": "Base64EncodedSha256HashesShouldBe43BytesLong"
-          properties:
+            }
-            sha256:
+            properties:
-              type: string
+              sha256:
-              description: The event hash.
+                type: string
-              example: Base64EncodedSha256HashesShouldBe43BytesLong
+                description: The event hash.
-          required: ['sha256']
+                example: Base64EncodedSha256HashesShouldBe43BytesLong
+            required: ['sha256']
   depth:
     type: integer
     description: |-
@@ -91,20 +92,21 @@ properties:
       maxItems: 2
       minItems: 2
       items:
-        - type: string
+        anyOf:
-          title: Event ID
+          - type: string
-          example: "$abc123:matrix.org"
+            title: Event ID
-        - type: object
+            example: "$abc123:matrix.org"
-          title: Event Hash
+          - type: object
-          example: {
+            title: Event Hash
-            "sha256": "Base64EncodedSha256HashesShouldBe43BytesLong"
+            example: {
-          }
+              "sha256": "Base64EncodedSha256HashesShouldBe43BytesLong"
-          properties:
+            }
-            sha256:
+            properties:
-              type: string
+              sha256:
-              description: The event hash.
+                type: string
-              example: Base64EncodedSha256HashesShouldBe43BytesLong
+                description: The event hash.
-          required: ['sha256']
+                example: Base64EncodedSha256HashesShouldBe43BytesLong
+            required: ['sha256']
   redacts:
     type: string
     description: For redaction events, the ID of the event being redacted.

data/api/server-server/invites-v1.yaml

@@ -75,6 +75,22 @@ paths:
                           example:
                             $ref: ../../event-schemas/examples/invite_room_state.json
               type: object
+            example: {
+              "room_id": "!somewhere:example.org",
+              "type": "m.room.member",
+              "state_key": "@joe:elsewhere.com",
+              "origin": "example.org",
+              "origin_server_ts": 1549041175876,
+              "sender": "@someone:example.org",
+              "content": {
+                  "membership": "invite"
+              },
+              "signatures": {
+                "example.com": {
+                  "ed25519:key_version": "SomeSignatureHere"
+                },
+              }
+            }
         required: true
       responses:
         "200":

data/api/server-server/invites-v2.yaml

@@ -78,6 +78,25 @@ paths:
               required:
                 - room_version
                 - event
+            example: {
+              "room_version": "2",
+              "event": {
+                "room_id": "!somewhere:example.org",
+                "type": "m.room.member",
+                "state_key": "@joe:elsewhere.com",
+                "origin": "example.org",
+                "origin_server_ts": 1549041175876,
+                "sender": "@someone:example.org",
+                "content": {
+                    "membership": "invite"
+                },
+                "signatures": {
+                  "example.com": {
+                    "ed25519:key_version": "SomeSignatureHere"
+                  },
+                }
+              }
+            }
         required: true
       responses:
         "200":

data/api/server-server/joins-v1.yaml

@@ -49,8 +49,6 @@ paths:
           example:
             - "1"
             - "2"
-          style: form
-          explode: false
           schema:
             type: array
             items:
@@ -321,6 +319,18 @@ paths:
                 - origin_server_ts
                 - type
                 - content
+            example: {
+              "room_id": "!somewhere:example.org",
+              "type": "m.room.member",
+              "state_key": "@someone:example.org",
+              "origin": "example.org",
+              "origin_server_ts": 1549041175876,
+              "sender": "@someone:example.org",
+              "content": {
+                  "membership": "join",
+                  "join_authorised_via_users_server": "@anyone:resident.example.org"
+              }
+            }
         required: true
       responses:
         "200":
@@ -356,9 +366,6 @@ paths:
                             description: |-
                               The [PDUs](/server-server-api/#pdus) that make up the auth chain. The event format varies depending
                               on the room version - check the [room version specification](/rooms) for precise event formats.
-                            schema:
-                              type: object
-                              properties: {}
                         state:
                           type: array
                           description: |-
@@ -372,9 +379,6 @@ paths:
                             description: |-
                               The [PDUs](/server-server-api/#pdus) for the fully resolved state of the room. The event format varies depending
                               on the room version - check the [room version specification](/rooms) for precise event formats.
-                            schema:
-                              type: object
-                              properties: {}
                       required:
                         - auth_chain
                         - state

data/api/server-server/joins-v2.yaml

@@ -17,6 +17,7 @@ info:
   title: Matrix Federation Join Room API
   version: 1.0.0
 paths:
+  # Note: there is no v2 of make_join (yet)
   "/send_join/{roomId}/{eventId}":
     put:
       summary: Submit a signed join event to a resident server
@@ -138,6 +139,18 @@ paths:
                 - origin_server_ts
                 - type
                 - content
+            example: {
+              "room_id": "!somewhere:example.org",
+              "type": "m.room.member",
+              "state_key": "@someone:example.org",
+              "origin": "example.org",
+              "origin_server_ts": 1549041175876,
+              "sender": "@someone:example.org",
+              "content": {
+                  "membership": "join",
+                  "join_authorised_via_users_server": "@anyone:resident.example.org"
+              }
+            }
         required: true
       responses:
         "200":
@@ -171,9 +184,6 @@ paths:
                     items:
                       type: object
                       title: PDU
-                      schema:
-                        type: object
-                        properties: {}
                     x-changedInMatrixVersion:
                       "1.6": |-
                         reworded to include only consider state events returned in
@@ -190,9 +200,6 @@ paths:
                     items:
                       type: object
                       title: PDU
-                      schema:
-                        type: object
-                        properties: {}
                     x-changedInMatrixVersion:
                       "1.6": permit omission of membership events.
                   event:

data/api/server-server/keys_query.yaml

@@ -88,7 +88,7 @@ paths:
                     given.
                   additionalProperties:
                     type: object
-                    name: ServerName
+                    title: ServerName
                     description: The server names to query.
                     additionalProperties:
                       type: object

data/api/server-server/knocks.yaml

@@ -44,12 +44,10 @@ paths:
         - in: query
           name: ver
           description: The room versions the sending server has support for.
-          required: true
+          required: true  # knocking was supported in v7
           example:
             - "1"
             - "7"
-          style: form
-          explode: false
           schema:
             type: array
             items:
@@ -121,7 +119,7 @@ paths:
                       - content
                       - sender
                 required:
-                  - room_version
+                  - room_version  # knocking was added in v7
                   - event
               examples:
                 response:
@@ -273,6 +271,17 @@ paths:
                 - origin_server_ts
                 - type
                 - content
+            example: {
+              "room_id": "!somewhere:example.org",
+              "type": "m.room.member",
+              "state_key": "@someone:example.org",
+              "origin": "example.org",
+              "origin_server_ts": 1549041175876,
+              "sender": "@someone:example.org",
+              "content": {
+                  "membership": "knock"
+              }
+            }
         required: true
       responses:
         "200":

data/api/server-server/leaving-v1.yaml

@@ -222,6 +222,17 @@ paths:
                 - type
                 - depth
                 - content
+            example: {
+              "room_id": "!somewhere:example.org",
+              "type": "m.room.member",
+              "state_key": "@someone:example.org",
+              "origin": "example.org",
+              "origin_server_ts": 1549041175876,
+              "sender": "@someone:example.org",
+              "content": {
+                  "membership": "leave"
+              }
+            }
         required: true
       responses:
         "200":

data/api/server-server/leaving-v2.yaml

@@ -17,6 +17,7 @@ info:
   title: Matrix Federation Leave Room API
   version: 1.0.0
 paths:
+  # Note: there is no v2 of make_leave (yet)
   "/send_leave/{roomId}/{eventId}":
     put:
       summary: Submit a signed leave event to a resident server
@@ -107,6 +108,17 @@ paths:
                 - type
                 - depth
                 - content
+            example: {
+              "room_id": "!somewhere:example.org",
+              "type": "m.room.member",
+              "state_key": "@someone:example.org",
+              "origin": "example.org",
+              "origin_server_ts": 1549041175876,
+              "sender": "@someone:example.org",
+              "content": {
+                  "membership": "leave"
+              }
+            }
         required: true
       responses:
         "200":

data/api/server-server/public_rooms.yaml

@@ -159,6 +159,7 @@ paths:
                         - $ref: ../client-server/definitions/public_rooms_chunk.yaml
                         - type: object
                           properties:
+                            # Override description of join_rule
                             join_rule:
                               type: string
                               description: |-

data/api/server-server/third_party_invite.yaml

@@ -151,6 +151,27 @@ paths:
                 - sender
                 - state_key
                 - content
+            example: {
+              "type": "m.room.member",
+              "room_id": "!abc123:matrix.org",
+              "sender": "@joe:matrix.org",
+              "state_key": "@someone:example.org",
+              "content": {
+                "membership": "invite",
+                "third_party_invite": {
+                  "display_name": "alice",
+                  "signed": {
+                    "mxid": "@alice:localhost",
+                    "token": "abc123",
+                    "signatures": {
+                      "magic.forest": {
+                        "ed25519:3": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg"
+                      }
+                    }
+                  }
+                }
+              }
+            }
         description: A partial `m.room.member` event
         required: true
       responses:
@@ -225,6 +246,8 @@ paths:
                         type: string
                         description: The user ID that sent the invite.
                         example: "@bob:matrix.org"
+                      # TODO (TravisR): Make this reusable when doing IS spec changes
+                      #   also make sure it isn't lying about anything, like the key version
                       signed:
                         type: object
                         title: Identity Server Signatures
@@ -240,6 +263,7 @@ paths:
                             example: "@alice:matrix.org"
                           token:
                             type: string
+                            # TODO: What is this actually?
                             description: A token.
                             example: Hello World
                           signatures:

data/api/server-server/user_keys.yaml

@@ -63,10 +63,13 @@ paths:
 
                       See the [Client-Server Key Algorithms](/client-server-api/#key-algorithms) section for more information on
                       the Key Object format.
+                    # User
                     additionalProperties:
                       type: object
+                      # Device
                       additionalProperties:
                         type: object
+                        # Key
                         additionalProperties:
                           type: object
                           title: KeyObject