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.
matrix-org · Mar 7, 2023 · 9ebcf5f · 9ebcf5f
1 parent 10844fe
commit 9ebcf5f
Show file tree

Hide file tree

Showing 14 changed files with 44 additions and 38 deletions.
diff --git a/changelogs/client_server/newsfragments/1457.clarification b/changelogs/client_server/newsfragments/1457.clarification
@@ -0,0 +1 @@
+Wrap $ref in allOf where other attributes are present, to improve OpenAPI compliance.
diff --git a/changelogs/identity_service/newsfragments/1457.clarification b/changelogs/identity_service/newsfragments/1457.clarification
@@ -0,0 +1 @@
+Wrap $ref in allOf where other attributes are present, to improve OpenAPI compliance.
diff --git a/changelogs/server_server/newsfragments/1457.clarification b/changelogs/server_server/newsfragments/1457.clarification
@@ -0,0 +1 @@
+Wrap $ref in allOf where other attributes are present, to improve OpenAPI compliance.
diff --git a/data/api/client-server/definitions/errors/rate_limited.yaml b/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
-type: object
-title: RateLimitError
-description: The rate limit was reached for this request
-properties:
-  errcode:
-    type: string
-    description: The M_LIMIT_EXCEEDED error code
-    example: M_LIMIT_EXCEEDED
-  error:
-    type: string
-    description: A human-readable error message.
-    example: Too many requests
-  retry_after_ms:
-    type: integer
-    description: |-
-      The amount of time in milliseconds the client should wait
-      before trying the request again.
-    example: 2000
-required: ["errcode"]
+allOf:
+  - $ref: error.yaml
+  - type: object
+    title: RateLimitError
+    description: The rate limit was reached for this request
+    properties:
+      errcode:
+        type: string
+        description: The M_LIMIT_EXCEEDED error code
+        example: M_LIMIT_EXCEEDED
+      error:
+        type: string
+        description: A human-readable error message.
+        example: Too many requests
+      retry_after_ms:
+        type: integer
+        description: |-
+          The amount of time in milliseconds the client should wait
+          before trying the request again.
+        example: 2000
+    required: ["errcode"]
diff --git a/data/api/client-server/definitions/event_batch.yaml b/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
-      type: object
+      $ref: ../../../event-schemas/schema/core-event-schema/event.yaml
     type: array
 type: object
 title: EventBatch
diff --git a/data/api/client-server/definitions/push_rule.yaml b/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

diff --git a/data/api/client-server/notifications.yaml b/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.

diff --git a/data/api/client-server/old_sync.yaml b/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

diff --git a/data/api/client-server/search.yaml b/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

diff --git a/data/api/identity/v2_associations.yaml b/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

diff --git a/data/api/identity/v2_invitation_signing.yaml b/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.

diff --git a/data/api/server-server/definitions/event-schemas/m.device_list_update.yaml b/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

diff --git a/data/api/server-server/definitions/event-schemas/m.signing_key_update.yaml b/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
-            $ref: ../../../client-server/definitions/cross_signing_key.yaml
+            allOf:
+              - $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
-            $ref: ../../../client-server/definitions/cross_signing_key.yaml
+            allOf:
+              - $ref: ../../../client-server/definitions/cross_signing_key.yaml
             example: {
               "user_id": "@alice:example.com",
               "usage": ["self_signing"],

diff --git a/data/api/server-server/user_devices.yaml b/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.