diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml
index cebfb2744..72565b684 100644
--- a/api/client-server/administrative_contact.yaml
+++ b/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.
diff --git a/api/client-server/device_management.yaml b/api/client-server/device_management.yaml
index 8039d71f7..094084bf1 100644
--- a/api/client-server/device_management.yaml
+++ b/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:
diff --git a/api/client-server/login.yaml b/api/client-server/login.yaml
index fac9361cf..d37d135dc 100644
--- a/api/client-server/login.yaml
+++ b/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.
diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml
index f57bd88c5..cf1a2f23f 100644
--- a/api/client-server/registration.yaml
+++ b/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: |-
diff --git a/api/client-server/search.yaml b/api/client-server/search.yaml
index 2d30ebefc..27e06727f 100644
--- a/api/client-server/search.yaml
+++ b/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
diff --git a/api/client-server/wellknown.yaml b/api/client-server/wellknown.yaml
index b63bd0410..3d1c0ae03 100644
--- a/api/client-server/wellknown.yaml
+++ b/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.