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: |-
-                    Additional authentication information for the
-                    user-interactive authentication API.
-                $ref: "definitions/auth_data.yaml"
+                allOf:
+                - description: |-
+                      Additional authentication information for the
+                      user-interactive authentication API.
+                - $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

@@ -83,7 +83,7 @@ paths:
           schema:
             type: object
             allOf:
-               - $ref: "definitions/client_device.yaml"
+              - $ref: "definitions/client_device.yaml"
           examples:
             application/json: {
                 "device_id": "QBUAZIFURK",
@@ -158,9 +158,10 @@ paths:
             properties:
               auth:
                 description: |-
-                    Additional authentication information for the
-                    user-interactive authentication API.
-                "$ref": "definitions/auth_data.yaml"
+                  Additional authentication information for the
+                  user-interactive authentication API.
+                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
-                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"
+                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"
         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: |-
-                  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"
+                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"
               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: |-
-                  Additional authentication information for the user-interactive authentication API.
-                "$ref": "definitions/auth_data.yaml"
+                allOf:
+                - description: |-
+                    Additional authentication information for the user-interactive authentication API.
+                - "$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.