c2s: clean up $ref objects

* Most of the changes: align to the $ref object definition
  (https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03#section-3)
  that says that any attribute other than $ref be ignored.
* Remove extraneous leading ./ in $ref paths
* Fix an apparent typo in registration.yaml:
  /account/password/msisdn/requestToken used a file from ../identity/*
  instead of its c2s namesake.

api/client-server/administrative_contact.yaml

@@ -201,10 +201,11 @@ paths:
             type: object
             properties:
               auth:
-                description: |-
+                allOf:
+                - description: |-
                       Additional authentication information for the
                       user-interactive authentication API.
-                $ref: "definitions/auth_data.yaml"
+                - $ref: "definitions/auth_data.yaml"
               client_secret:
                 type: string
                 description: The client secret used in the session with the homeserver.
@@ -432,7 +433,7 @@ paths:
           name: body
           required: true
           schema:
-            $ref: "./definitions/request_email_validation.yaml"
+            $ref: "definitions/request_email_validation.yaml"
       responses:
         200:
           description: |-
@@ -482,7 +483,7 @@ paths:
           name: body
           required: true
           schema:
-            $ref: "./definitions/request_msisdn_validation.yaml"
+            $ref: "definitions/request_msisdn_validation.yaml"
       responses:
         200:
           description: An SMS message was sent to the given phone number.

api/client-server/device_management.yaml

@@ -160,7 +160,8 @@ paths:
                 description: |-
                   Additional authentication information for the
                   user-interactive authentication API.
-                "$ref": "definitions/auth_data.yaml"
+                allOf:
+                  - "$ref": "definitions/auth_data.yaml"
       responses:
         200:
           description: |-
@@ -203,10 +204,11 @@ paths:
                   description: A list of device IDs.
                 example: ["QBUAZIFURK", "AUIECTSRND"]
               auth:
+                allOf:
+                  - "$ref": "definitions/auth_data.yaml"
                 description: |-
                     Additional authentication information for the
                     user-interactive authentication API.
-                "$ref": "definitions/auth_data.yaml"
             required:
               - devices
       responses:

api/client-server/login.yaml

@@ -100,7 +100,6 @@ paths:
                 enum: ["m.login.password", "m.login.token"]
                 description: The login type being used.
               identifier:
-                description: Identification information for the user.
                 "$ref": "definitions/user_identifier.yaml"
               user:
                 type: string
@@ -176,13 +175,14 @@ paths:
                   ID of the logged-in device. Will be the same as the
                   corresponding parameter in the request, if one was specified.
               well_known:
-                type: object
+                allOf:
+                  - type: object
                     description: |-
                       Optional client configuration provided by the server. If present,
                       clients SHOULD use the provided object to reconfigure themselves,
                       optionally validating the URLs within. This object takes the same
                       form as the one returned from .well-known autodiscovery.
-                "$ref": "definitions/wellknown/full.yaml"
+                  - "$ref": "definitions/wellknown/full.yaml"
         400:
           description: |-
             Part of the request was invalid. For example, the login type may not be recognised.

api/client-server/registration.yaml

@@ -89,13 +89,14 @@ paths:
             type: object
             properties:
               auth:
-                description: |-
+                allOf:
+                - description: |-
                     Additional authentication information for the
                     user-interactive authentication API. Note that this
                     information is *not* used to define how the registered user
                     should be authenticated, but is instead used to
                     authenticate the ``register`` call itself.
-                "$ref": "definitions/auth_data.yaml"
+                - "$ref": "definitions/auth_data.yaml"
               username:
                 type: string
                 description: |-
@@ -228,7 +229,7 @@ paths:
           name: body
           required: true
           schema:
-            $ref: "./definitions/request_email_validation.yaml"
+            $ref: "definitions/request_email_validation.yaml"
       responses:
         200:
           description: |-
@@ -278,7 +279,7 @@ paths:
           name: body
           required: true
           schema:
-            $ref: "./definitions/request_msisdn_validation.yaml"
+            $ref: "definitions/request_msisdn_validation.yaml"
       responses:
         200:
           description: |-
@@ -346,9 +347,10 @@ paths:
                 description: The new password for the account.
                 example: "ihatebananas"
               auth:
-                description: |-
+                allOf:
+                - description: |-
                     Additional authentication information for the user-interactive authentication API.
-                "$ref": "definitions/auth_data.yaml"
+                - "$ref": "definitions/auth_data.yaml"
             required: ["new_password"]
       responses:
         200:
@@ -397,7 +399,7 @@ paths:
           name: body
           required: true
           schema:
-            $ref: "./definitions/request_email_validation.yaml"
+            $ref: "definitions/request_email_validation.yaml"
       responses:
         200:
           description: An email was sent to the given address.
@@ -455,7 +457,7 @@ paths:
           name: body
           required: true
           schema:
-            $ref: "../identity/definitions/request_msisdn_validation.yaml"
+            $ref: "definitions/request_msisdn_validation.yaml"
       responses:
         200:
           description: An SMS message was sent to the given phone number.
@@ -516,7 +518,8 @@ paths:
               auth:
                 description: |-
                   Additional authentication information for the user-interactive authentication API.
-                "$ref": "definitions/auth_data.yaml"
+                allOf:
+                  - $ref: "definitions/auth_data.yaml"
               id_server:
                 type: string
                 description: |-

api/client-server/search.yaml

@@ -96,7 +96,8 @@ paths:
                         # for now :/
                         description: |-
                           This takes a `filter`_.
-                        $ref: "definitions/room_event_filter.yaml"
+                        allOf:
+                          - $ref: "definitions/room_event_filter.yaml"
                       order_by:
                         title: "Ordering"
                         type: string

api/client-server/wellknown.yaml

@@ -39,7 +39,6 @@ paths:
         200:
           description: Server discovery information.
           schema:
-            type: object
             "$ref": "definitions/wellknown/full.yaml"
         404:
           description: No server discovery information available.