Clarify the key object definition for the key management API

Fixes https://github.com/matrix-org/matrix-doc/issues/1907


One too far

api/client-server/keys.yaml

@@ -59,22 +59,41 @@ paths:
                   by the key algorithm.
 
                   May be absent if no new one-time keys are required.
-                additionalProperties:
-                  type:
-                    - string
-                    - object
-                example:
-                  "curve25519:AAAAAQ": "/qyvZvwjiTxGdGU0RCguDCLeR+nmsb3FfNG3/Ve4vU8"
-                  signed_curve25519:AAAAHg:
-                    key: "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs"
-                    signatures:
-                      "@alice:example.com":
-                        ed25519:JLAFKJWSCS: "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw"
-                  signed_curve25519:AAAAHQ:
-                    key: "j3fR3HemM16M7CWhoI4Sk5ZsdmdfQHsKL1xuSft6MSw"
-                    signatures:
-                      "@alice:example.com":
-                        ed25519:JLAFKJWSCS: "IQeCEPb9HFk217cU9kw9EOiusC6kMIkoIRnbnfOh5Oc63S1ghgyjShBGpu34blQomoalCyXWyhaaT3MrLZYQAA"
+                  additionalProperties:
+                    type:
+                      - string
+                      - type: object
+                        title: KeyObject
+                        properties:
+                          key:
+                            type: string
+                            description: The key, encoded using unpadded base64.
+                          signatures:
+                            type: object
+                            description: |-
+                              Signature for the device. Mapped from user ID to signature object.
+                            additionalProperties:
+                              type: string
+                        required: ['key', 'signatures']
+                example: {
+                  "curve25519:AAAAAQ": "/qyvZvwjiTxGdGU0RCguDCLeR+nmsb3FfNG3/Ve4vU8",
+                  "signed_curve25519:AAAAHg": {
+                    "key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs",
+                    "signatures": {
+                      "@alice:example.com": {
+                        "ed25519:JLAFKJWSCS": "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw"
+                      }
+                    }
+                  },
+                  "signed_curve25519:AAAAHQ": {
+                    "key": "j3fR3HemM16M7CWhoI4Sk5ZsdmdfQHsKL1xuSft6MSw",
+                    "signatures": {
+                      "@alice:example.com": {
+                        "ed25519:JLAFKJWSCS": "IQeCEPb9HFk217cU9kw9EOiusC6kMIkoIRnbnfOh5Oc63S1ghgyjShBGpu34blQomoalCyXWyhaaT3MrLZYQAA"
+                      }
+                    }
+                  }
+                }
       responses:
         200:
           description:
@@ -246,8 +265,9 @@ paths:
                     type: string
                     description: algorithm
                     example: "signed_curve25519"
-                example:
+                example: {
                   "@alice:example.com": { "JLAFKJWSCS": "signed_curve25519" }
+                }
             required:
               - one_time_keys
       responses:
@@ -281,14 +301,37 @@ paths:
                     type:
                       - string
                       - object
-                example:
-                  "@alice:example.com":
-                    JLAFKJWSCS:
-                      signed_curve25519:AAAAHg:
-                        key: "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs"
-                        signatures:
-                          "@alice:example.com":
-                            ed25519:JLAFKJWSCS: "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw"
+                      # XXX: We can't define an actual object here, so we have to hope
+                      # that people will look at the swagger source or can figure it out
+                      # from the other endpoints/example.
+                      # - type: object
+                      #   title: KeyObject
+                      #   properties:
+                      #     key:
+                      #       type: string
+                      #       description: The key, encoded using unpadded base64.
+                      #     signatures:
+                      #       type: object
+                      #       description: |-
+                      #         Signature for the device. Mapped from user ID to signature object.
+                      #       additionalProperties:
+                      #         type: string
+                      #   required: ['key', 'signatures']
+                example: {
+                  "@alice:example.com": {
+                    "JLAFKJWSCS": {
+                      "signed_curve25519:AAAAHg": {
+                        "key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs",
+                        "signatures": {
+                          "@alice:example.com": {
+                            "ed25519:JLAFKJWSCS": "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw"
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+            required: ['one_time_keys']
       tags:
         - End-to-end encryption
   "/keys/changes":

api/server-server/user_keys.yaml

@@ -77,25 +77,34 @@ paths:
                   additionalProperties:
                     type:
                       - string
-                      - object
-            required: ['one_time_keys']
-          examples:
-            application/json: {
-              "one_time_keys": {
-                "@alice:example.com": {
-                  "JLAFKJWSCS": {
-                    "signed_curve25518:AAAAHg": {
-                      "key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs",
-                      "signatures": {
-                        "@alice:example.com": {
-                          "ed25519:JLAFKJWSCS": "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw"
+                      - type: object
+                        title: KeyObject
+                        properties:
+                          key:
+                            type: string
+                            description: The key, encoded using unpadded base64.
+                          signatures:
+                            type: object
+                            description: |-
+                              Signature for the device. Mapped from user ID to signature object.
+                            additionalProperties:
+                              type: string
+                        required: ['key', 'signatures']
+                example: {
+                  "@alice:example.com": {
+                    "JLAFKJWSCS": {
+                      "signed_curve25519:AAAAHg": {
+                        "key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs",
+                        "signatures": {
+                          "@alice:example.com": {
+                            "ed25519:JLAFKJWSCS": "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw"
+                          }
                         }
                       }
                     }
                   }
                 }
-              }
-            }
+            required: ['one_time_keys']
   "/user/keys/query":
     post:
       summary: Download device identity keys.

changelogs/client_server/newsfragments/2083.clarification

@@ -0,0 +1 @@
+Clarify the key object definition for the key management API.

changelogs/server_server/newsfragments/2083.clarification

@@ -0,0 +1 @@
+Clarify the key object definition for the key management API.