wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

keys.yml: fix one_time_keys object contents (#1127)

Browse source 
* keys.yml: fix one_time_keys object contents

The alternatives previously listed under two additionalProperties levels
are actually one _more_ level deeper; we still can't define them in
a formal way before moving to OpenAPI 3 but at least let's be honest
and say there's always a dict where there's always a dict. Also,
since the same data structure is used in three places now, at least
give it a name, and document the actual definition (once) separately
(not using it now because it's OpenAPI 3).

* Changelog
This commit is contained in:
Alexey Rusakov 2022-06-15 06:03:53 +02:00 • committed by GitHub
parent 980d9cd6e9
commit dcc1f4adee
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
3 changed files with 41 additions and 45 deletions
Download patch file Download diff file Expand all files Collapse all files

1
changelogs/client_server/newsfragments/1127.clarification Normal file
View file

@ -0,0 +1 @@
Fix various typos throughout the specification.

24
data/api/client-server/definitions/one_time_keys.yaml Normal file
View file

@ -0,0 +1,24 @@
---
title: OneTimeKeys
type: object
description: |-
One-time public keys. The names of the properties should be in the format
`<algorithm>:<key_id>`. The format of the key is determined
by the [key algorithm](/client-server-api/#key-algorithms).
additionalProperties:
oneOf:
- type: string
- type: object
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,
containing mapping from _key signing identifier_ to the signature
(see also: https://spec.matrix.org/v1.2/appendices/#signing-json)
additionalProperties:
type: object
required: ['key', 'signatures']

61
data/api/client-server/keys.yaml
View file

@ -53,7 +53,12 @@ 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 swagger source or can figure it out
# from the other endpoints/example.
type: object
title: OneTimeKeys
description: |-
One-time public keys for "pre-key" messages. The names of
the properties should be in the format
@ -61,26 +66,6 @@ paths:
by the [key algorithm](/client-server-api/#key-algorithms).
May be absent if no new one-time keys are required.
additionalProperties:
type:
- string
- object
# 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: {
"curve25519:AAAAAQ": "/qyvZvwjiTxGdGU0RCguDCLeR+nmsb3FfNG3/Ve4vU8",
"signed_curve25519:AAAAHg": {
@ -101,8 +86,11 @@ paths:
}
}
fallback_keys:
type: object
x-addedInMatrixVersion: "1.2"
# $ref: "definitions/one_time_keys.yaml"
# XXX: We can't define an actual object here - see above.
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
@ -117,11 +105,6 @@ paths:
be included to denote that the key is a fallback key.
May be absent if a new fallback key is not required.
additionalProperties:
type:
- string
- object
# XXX: We can't define an actual object here - see one_time_keys.
example: {
"curve25519:AAAAAG": "/qyvZvwjiTxGdGU0RCguDCLeR+nmsb3FfNG3/Ve4vU8",
"signed_curve25519:AAAAGj": {
@ -420,25 +403,13 @@ paths:
additionalProperties:
type: object
additionalProperties:
type:
- string
- object
# 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']
# $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
example: {
"@alice:example.com": {
"JLAFKJWSCS": {