From 2d18aac2016eea45a3de1847dd795a679a1b59c1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Commaille?=
 <76261501+zecakeh@users.noreply.github.com>
Date: Tue, 30 Apr 2024 19:13:05 +0200
Subject: [PATCH] Use `OneTimeKeys` schema (#1800)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This was commented prior to the
port to OpenAPI 3.1 for technical reasons (#1127).
Now we can use it just fine.

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
---
 .../internal/newsfragments/1800.clarification |  1 +
 .../definitions/one_time_keys.yaml            |  3 ++-
 data/api/client-server/keys.yaml              | 20 +++++--------------
 3 files changed, 8 insertions(+), 16 deletions(-)
 create mode 100644 changelogs/internal/newsfragments/1800.clarification

diff --git a/changelogs/internal/newsfragments/1800.clarification b/changelogs/internal/newsfragments/1800.clarification
new file mode 100644
index 00000000..7dfac999
--- /dev/null
+++ b/changelogs/internal/newsfragments/1800.clarification
@@ -0,0 +1 @@
+Use reference to `OneTimeKeys` schema in OpenAPI definitions.
diff --git a/data/api/client-server/definitions/one_time_keys.yaml b/data/api/client-server/definitions/one_time_keys.yaml
index ceb69291..d54494d9 100644
--- a/data/api/client-server/definitions/one_time_keys.yaml
+++ b/data/api/client-server/definitions/one_time_keys.yaml
@@ -9,6 +9,7 @@ additionalProperties:
   oneOf:
     - type: string
     - type: object
+      title: KeyObject
       properties:
         key:
           type: string
@@ -18,7 +19,7 @@ additionalProperties:
           description: |-
             Signature for the device. Mapped from user ID to signature object,
             containing mapping from _key signing identifier_ to the signature
-            (see also: https://spec.matrix.org/v1.2/appendices/#signing-json)
+            (see also: [Signing JSON](/appendices/#signing-json))
           additionalProperties:
             type: object
       required: ['key', 'signatures']
diff --git a/data/api/client-server/keys.yaml b/data/api/client-server/keys.yaml
index 2fd40172..f165f379 100644
--- a/data/api/client-server/keys.yaml
+++ b/data/api/client-server/keys.yaml
@@ -39,12 +39,9 @@ paths:
                   allOf:
                     - $ref: definitions/device_keys.yaml
                 one_time_keys:
-                  # $ref: "definitions/one_time_keys.yaml"
-                  # XXX: We can't define an actual object here, so we have to hope
-                  # that people will look at the OpenAPI source or can figure it out
-                  # from the other endpoints/example.
+                  allOf:
+                    - $ref: "definitions/one_time_keys.yaml"
                   type: object
-                  title: OneTimeKeys
                   description: |-
                     One-time public keys for "pre-key" messages.  The names of
                     the properties should be in the format
@@ -65,10 +62,9 @@ paths:
                           ed25519:JLAFKJWSCS: IQeCEPb9HFk217cU9kw9EOiusC6kMIkoIRnbnfOh5Oc63S1ghgyjShBGpu34blQomoalCyXWyhaaT3MrLZYQAA
                 fallback_keys:
                   x-addedInMatrixVersion: "1.2"
-                  # $ref: "definitions/one_time_keys.yaml"
-                  # XXX: We can't define an actual object here - see above.
+                  allOf:
+                    - $ref: "definitions/one_time_keys.yaml"
                   type: object
-                  title: OneTimeKeys
                   description: |-
                     The public key which should be used if the device's one-time keys
                     are exhausted. The fallback key is not deleted once used, but should
@@ -349,13 +345,7 @@ paths:
                     additionalProperties:
                       type: object
                       additionalProperties:
-                        # $ref: "definitions/one_time_keys.yaml"
-                        # XXX: We can't define an actual object here, so we have to hope
-                        # that people will read the link provided in the description
-                        # and figure it out from the other endpoints/example.
-                        # See also one_time_key parameter for /keys/upload above.
-                        type: object
-                        title: OneTimeKeys
+                        $ref: "definitions/one_time_keys.yaml"
                     example:
                       "@alice:example.com":
                         JLAFKJWSCS: