OpenAPI compliance: avoid $ref siblings (#1457)

This strives to fix all remaining cases where additional attributes
(most often 'description' but not only) are provided next to $ref
by wrapping $ref in allOf; and also drops allOf in a couple of places
where $ref is the only element under it.

changelogs/client_server/newsfragments/1457.clarification

@@ -0,0 +1 @@
+Wrap $ref in allOf where other attributes are present, to improve OpenAPI compliance.

changelogs/identity_service/newsfragments/1457.clarification

@@ -0,0 +1 @@
+Wrap $ref in allOf where other attributes are present, to improve OpenAPI compliance.

changelogs/server_server/newsfragments/1457.clarification

@@ -0,0 +1 @@
+Wrap $ref in allOf where other attributes are present, to improve OpenAPI compliance.

data/api/client-server/definitions/errors/rate_limited.yaml

@@ -11,23 +11,24 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-$ref: error.yaml
+allOf:
-type: object
+  - $ref: error.yaml
-title: RateLimitError
+  - type: object
-description: The rate limit was reached for this request
+    title: RateLimitError
-properties:
+    description: The rate limit was reached for this request
-  errcode:
+    properties:
-    type: string
+      errcode:
-    description: The M_LIMIT_EXCEEDED error code
+        type: string
-    example: M_LIMIT_EXCEEDED
+        description: The M_LIMIT_EXCEEDED error code
-  error:
+        example: M_LIMIT_EXCEEDED
-    type: string
+      error:
-    description: A human-readable error message.
+        type: string
-    example: Too many requests
+        description: A human-readable error message.
-  retry_after_ms:
+        example: Too many requests
-    type: integer
+      retry_after_ms:
-    description: |-
+        type: integer
-      The amount of time in milliseconds the client should wait
+        description: |-
-      before trying the request again.
+          The amount of time in milliseconds the client should wait
-    example: 2000
+          before trying the request again.
-required: ["errcode"]
+        example: 2000
+    required: ["errcode"]

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

@@ -16,9 +16,7 @@ properties:
   events:
     description: List of events.
     items:
-      allOf:
+      $ref: ../../../event-schemas/schema/core-event-schema/event.yaml
-      - $ref: ../../../event-schemas/schema/core-event-schema/event.yaml
-      type: object
     type: array
 type: object
 title: EventBatch

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

@@ -38,8 +38,7 @@ properties:
   conditions:
     type: array
     items:
-      allOf:
+      $ref: push_condition.yaml
-      - $ref: push_condition.yaml
     description: |-
       The conditions that must hold true for an event in order for a rule to be
       applied to an event. A rule with no conditions always matches. Only

data/api/client-server/notifications.yaml

@@ -109,10 +109,10 @@ paths:
                         - object
                         - string
                     event:
-                      type: object
                       title: Event
                       description: The Event object for the event that triggered the notification.
-                      "$ref": "definitions/client_event_without_room_id.yaml"
+                      allOf:
+                        - "$ref": "definitions/client_event_without_room_id.yaml"
                     profile_tag:
                       type: string
                       description: The profile tag of the rule that matched this event.

data/api/client-server/old_sync.yaml

@@ -221,7 +221,8 @@ paths:
                         type: object
                         title: "InviteEvent"
                         description: "The invite event if `membership` is `invite`"
-                        $ref: "definitions/client_event.yaml"
+                        allOf:
+                          - $ref: "definitions/client_event.yaml"
                     messages:
                       type: object
                       title: PaginationChunk

data/api/client-server/search.yaml

@@ -204,7 +204,8 @@ paths:
                               type: object
                               title: Event
                               description: The event that matched.
-                              "$ref": "definitions/client_event.yaml"
+                              allOf:
+                                - "$ref": "definitions/client_event.yaml"
                             context:
                               type: object
                               title: Event Context
@@ -270,7 +271,6 @@ paths:
                           type: array
                           title: Room State
                           items:
-                            type: object
                             "$ref": "definitions/client_event.yaml"
                       groups:
                         type: object

data/api/identity/v2_associations.yaml

@@ -191,7 +191,8 @@ paths:
                   The signatures of the verifying identity servers which show that the
                   association should be trusted, if you trust the verifying identity
                   services.
-                $ref: "../../schemas/server-signatures.yaml"
+                allOf:
+                  - $ref: "../../schemas/server-signatures.yaml"
             required:
               - address
               - medium

data/api/identity/v2_invitation_signing.yaml

@@ -74,7 +74,8 @@ paths:
               signatures:
                 type: object
                 description: The signature of the mxid, sender, and token.
-                $ref: "../../schemas/server-signatures.yaml"
+                allOf:
+                  - $ref: "../../schemas/server-signatures.yaml"
               token:
                 type: string
                 description: The token for the invitation.

data/api/server-server/definitions/event-schemas/m.device_list_update.yaml

@@ -85,7 +85,8 @@ allOf:
             description: |-
               The updated identity keys (if any) for this device.  May be absent if the
               device has no E2E keys defined.
-            $ref: ../../../client-server/definitions/device_keys.yaml
+            allOf:
+              - $ref: ../../../client-server/definitions/device_keys.yaml
         required:
           - user_id
           - device_id

data/api/server-server/definitions/event-schemas/m.signing_key_update.yaml

@@ -37,8 +37,8 @@ allOf:
             description: The user ID whose cross-signing keys have changed.
             example: "@alice:example.com"
           master_key:
-            type: object
+            allOf:
-            $ref: ../../../client-server/definitions/cross_signing_key.yaml
+              - $ref: ../../../client-server/definitions/cross_signing_key.yaml
             example: {
               "user_id": "@alice:example.com",
               "usage": ["master"],
@@ -47,8 +47,8 @@ allOf:
               }
             }
           self_signing_key:
-            type: object
+            allOf:
-            $ref: ../../../client-server/definitions/cross_signing_key.yaml
+              - $ref: ../../../client-server/definitions/cross_signing_key.yaml
             example: {
               "user_id": "@alice:example.com",
               "usage": ["self_signing"],

data/api/server-server/user_devices.yaml

@@ -76,7 +76,8 @@ paths:
                     keys:
                       type: object
                       description: Identity keys for the device.
-                      $ref: "../client-server/definitions/device_keys.yaml"
+                      allOf:
+                        - $ref: "../client-server/definitions/device_keys.yaml"
                     device_display_name:
                       type: string
                       description: Optional display name for the device.