From b0df8e7fb58ddef4f96c0c527b66d2c7e55255b9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Wed, 8 May 2024 15:59:17 +0200 Subject: [PATCH] Use `patternProperties` in more places with supported formats (#1813) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Allows to have more places where the property name's type is better defined. Signed-off-by: Kévin Commaille --- .../newsfragments/1813.clarification | 1 + .../newsfragments/1813.clarification | 1 + data/api/client-server/cross_signing.yaml | 18 +- .../definitions/device_keys.yaml | 10 +- .../definitions/one_time_keys.yaml | 6 +- data/api/client-server/key_backup.yaml | 14 +- data/api/client-server/keys.yaml | 95 +++-- data/api/client-server/rooms.yaml | 26 +- data/api/client-server/search.yaml | 40 +- data/api/client-server/sync.yaml | 392 +++++++++--------- data/api/client-server/to_device.yaml | 12 +- .../event-schemas/m.direct_to_device.yaml | 14 +- .../definitions/event-schemas/m.receipt.yaml | 90 ++-- data/api/server-server/transactions.yaml | 24 +- data/api/server-server/user_keys.yaml | 126 +++--- data/custom-formats.yaml | 5 + data/event-schemas/schema/m.direct.yaml | 10 +- .../schema/m.room.power_levels.yaml | 6 +- 18 files changed, 486 insertions(+), 404 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1813.clarification create mode 100644 changelogs/server_server/newsfragments/1813.clarification diff --git a/changelogs/client_server/newsfragments/1813.clarification b/changelogs/client_server/newsfragments/1813.clarification new file mode 100644 index 00000000..af643e2e --- /dev/null +++ b/changelogs/client_server/newsfragments/1813.clarification @@ -0,0 +1 @@ +Use `patternProperties` in more places with supported formats. diff --git a/changelogs/server_server/newsfragments/1813.clarification b/changelogs/server_server/newsfragments/1813.clarification new file mode 100644 index 00000000..af643e2e --- /dev/null +++ b/changelogs/server_server/newsfragments/1813.clarification @@ -0,0 +1 @@ +Use `patternProperties` in more places with supported formats. diff --git a/data/api/client-server/cross_signing.yaml b/data/api/client-server/cross_signing.yaml index 16539eb0..0f3a46be 100644 --- a/data/api/client-server/cross_signing.yaml +++ b/data/api/client-server/cross_signing.yaml @@ -165,10 +165,12 @@ paths: type: object description: |- A map of user ID to a map of key ID to signed JSON object. - additionalProperties: - type: object - additionalProperties: + patternProperties: + "^@": + x-pattern-format: mx-user-id type: object + additionalProperties: + type: object example: { "@alice:example.com": { "HIJKLMN": { @@ -238,11 +240,13 @@ paths: A map from user ID to key ID to an error for any signatures that failed. If a signature was invalid, the `errcode` will be set to `M_INVALID_SIGNATURE`. - additionalProperties: - type: object - additionalProperties: + patternProperties: + "^@": type: object - title: Error + x-pattern-format: mx-user-id + additionalProperties: + type: object + title: Error example: "@alice:example.com": HIJKLMN: diff --git a/data/api/client-server/definitions/device_keys.yaml b/data/api/client-server/definitions/device_keys.yaml index ab033941..2a7f8104 100644 --- a/data/api/client-server/definitions/device_keys.yaml +++ b/data/api/client-server/definitions/device_keys.yaml @@ -53,10 +53,12 @@ properties: `:` to the signature. The signature is calculated using the process described at [Signing JSON](/appendices/#signing-json). - additionalProperties: - type: object - additionalProperties: - type: string + patternProperties: + "^@": + x-pattern-format: mx-user-id + type: object + additionalProperties: + type: string example: "@alice:example.com": "ed25519:JLAFKJWSCS": "dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA" diff --git a/data/api/client-server/definitions/one_time_keys.yaml b/data/api/client-server/definitions/one_time_keys.yaml index d54494d9..78711350 100644 --- a/data/api/client-server/definitions/one_time_keys.yaml +++ b/data/api/client-server/definitions/one_time_keys.yaml @@ -20,6 +20,8 @@ additionalProperties: Signature for the device. Mapped from user ID to signature object, containing mapping from _key signing identifier_ to the signature (see also: [Signing JSON](/appendices/#signing-json)) - additionalProperties: - type: object + patternProperties: + "^@": + x-pattern-format: mx-user-id + type: object required: ['key', 'signatures'] diff --git a/data/api/client-server/key_backup.yaml b/data/api/client-server/key_backup.yaml index 103071dd..64833f6e 100644 --- a/data/api/client-server/key_backup.yaml +++ b/data/api/client-server/key_backup.yaml @@ -840,8 +840,11 @@ paths: rooms: type: object description: A map of room IDs to room key backup data. - additionalProperties: - $ref: definitions/room_key_backup.yaml + patternProperties: + "^!": + x-pattern-format: mx-room-id + allOf: + - $ref: definitions/room_key_backup.yaml example: "!room:example.org": sessions: @@ -944,8 +947,11 @@ paths: rooms: type: object description: A map of room IDs to room key backup data. - additionalProperties: - $ref: definitions/room_key_backup.yaml + patternProperties: + "^!": + x-pattern-format: mx-room-id + allOf: + - $ref: definitions/room_key_backup.yaml example: "!room:example.org": sessions: diff --git a/data/api/client-server/keys.yaml b/data/api/client-server/keys.yaml index f165f379..001fe1f5 100644 --- a/data/api/client-server/keys.yaml +++ b/data/api/client-server/keys.yaml @@ -137,11 +137,13 @@ paths: The keys to be downloaded. A map from user ID, to a list of device IDs, or to an empty list to indicate all devices for the corresponding user. - additionalProperties: - type: array - items: - type: string - description: device ID + patternProperties: + "^@": + x-pattern-format: mx-user-id + type: array + items: + type: string + description: device ID example: "@alice:example.com": [] required: @@ -177,24 +179,26 @@ paths: the information returned will be the same as uploaded via `/keys/upload`, with the addition of an `unsigned` property. - additionalProperties: - type: object - additionalProperties: - title: DeviceInformation - allOf: - - $ref: definitions/device_keys.yaml - properties: - unsigned: - title: UnsignedDeviceInfo - type: object - description: |- - Additional data added to the device key information - by intermediate servers, and not covered by the - signatures. - properties: - device_display_name: - type: string - description: The display name which the user set on the device. + patternProperties: + "^@": + x-pattern-format: mx-user-id + type: object + additionalProperties: + title: DeviceInformation + allOf: + - $ref: definitions/device_keys.yaml + properties: + unsigned: + title: UnsignedDeviceInfo + type: object + description: |- + Additional data added to the device key information + by intermediate servers, and not covered by the + signatures. + properties: + device_display_name: + type: string + description: The display name which the user set on the device. example: "@alice:example.com": JLAFKJWSCS: @@ -221,8 +225,11 @@ paths: `/keys/device_signing/upload`, along with the signatures uploaded via `/keys/signatures/upload` that the requesting user is allowed to see. - additionalProperties: - $ref: definitions/cross_signing_key.yaml + patternProperties: + "^@": + x-pattern-format: mx-user-id + allOf: + - $ref: definitions/cross_signing_key.yaml example: "@alice:example.com": user_id: "@alice:example.com" @@ -238,8 +245,11 @@ paths: from user ID, to self-signing key information. For each key, the information returned will be the same as uploaded via `/keys/device_signing/upload`. - additionalProperties: - $ref: definitions/cross_signing_key.yaml + patternProperties: + "^@": + x-pattern-format: mx-user-id + allOf: + - $ref: definitions/cross_signing_key.yaml example: "@alice:example.com": user_id: "@alice:example.com" @@ -258,8 +268,11 @@ paths: from user ID, to user-signing key information. The information returned will be the same as uploaded via `/keys/device_signing/upload`. - additionalProperties: - $ref: definitions/cross_signing_key.yaml + patternProperties: + "^@": + x-pattern-format: mx-user-id + allOf: + - $ref: definitions/cross_signing_key.yaml example: "@alice:example.com": user_id: "@alice:example.com" @@ -297,12 +310,14 @@ paths: description: |- The keys to be claimed. A map from user ID, to a map from device ID to algorithm name. - additionalProperties: - type: object - additionalProperties: - type: string - description: algorithm - example: signed_curve25519 + patternProperties: + "^@": + x-pattern-format: mx-user-id + type: object + additionalProperties: + type: string + description: algorithm + example: signed_curve25519 example: "@alice:example.com": JLAFKJWSCS: signed_curve25519 @@ -342,10 +357,12 @@ paths: If necessary, the claimed key might be a fallback key. Fallback keys are re-used by the server until replaced by the device. - additionalProperties: - type: object - additionalProperties: - $ref: "definitions/one_time_keys.yaml" + patternProperties: + "^@": + x-pattern-format: mx-user-id + type: object + additionalProperties: + $ref: "definitions/one_time_keys.yaml" example: "@alice:example.com": JLAFKJWSCS: diff --git a/data/api/client-server/rooms.yaml b/data/api/client-server/rooms.yaml index be5466b7..a2197f34 100644 --- a/data/api/client-server/rooms.yaml +++ b/data/api/client-server/rooms.yaml @@ -299,18 +299,20 @@ paths: type: object properties: joined: - additionalProperties: - title: RoomMember - type: object - properties: - display_name: - type: string - description: The display name of the user this object is representing. - avatar_url: - type: string - format: uri - description: The avatar of the user this object is representing, as an [`mxc://` - URI](/client-server-api/#matrix-content-mxc-uris). + patternProperties: + "^@": + x-pattern-format: mx-user-id + title: RoomMember + type: object + properties: + display_name: + type: string + description: The display name of the user this object is representing. + avatar_url: + type: string + format: uri + description: The avatar of the user this object is representing, as an [`mxc://` + URI](/client-server-api/#matrix-content-mxc-uris). description: A map from user ID to a RoomMember object. type: object examples: diff --git a/data/api/client-server/search.yaml b/data/api/client-server/search.yaml index 2d0475c5..587894ff 100644 --- a/data/api/client-server/search.yaml +++ b/data/api/client-server/search.yaml @@ -225,19 +225,21 @@ paths: The historic profile information of the users that sent the events returned. - The `string` key is the user ID for which + The key is the user ID for which the profile belongs to. - additionalProperties: - type: object - title: User Profile - properties: - displayname: - type: string - title: Display name - avatar_url: - type: string - format: uri - title: Avatar Url + patternProperties: + "^@": + x-pattern-format: mx-user-id + type: object + title: User Profile + properties: + displayname: + type: string + title: Display name + avatar_url: + type: string + format: uri + title: Avatar Url events_before: type: array title: Events Before @@ -262,13 +264,15 @@ paths: This is included if the request had the `include_state` key set with a value of `true`. - The `string` key is the room ID for which the `State + The key is the room ID for which the `State Event` array belongs to. - additionalProperties: - type: array - title: Room State - items: - $ref: definitions/client_event.yaml + patternProperties: + "^!": + x-pattern-format: mx-room-id + type: array + title: Room State + items: + $ref: definitions/client_event.yaml groups: type: object title: Groups diff --git a/data/api/client-server/sync.yaml b/data/api/client-server/sync.yaml index 3f06d13c..efe36c5c 100644 --- a/data/api/client-server/sync.yaml +++ b/data/api/client-server/sync.yaml @@ -141,223 +141,233 @@ paths: description: |- The rooms that the user has joined, mapped as room ID to room information. - additionalProperties: - title: Joined Room - type: object - properties: - summary: - title: RoomSummary - type: object - description: |- - Information about the room which clients may need to - correctly render it to users. - properties: - m.heroes: - type: array - description: |- - The users which can be used to generate a room name - if the room does not have one. Required if the room's - `m.room.name` or `m.room.canonical_alias` state events - are unset or empty. - - This should be the first 5 members of the room, ordered - by stream ordering, which are joined or invited. The - list must never include the client's own user ID. When - no joined or invited members are available, this should - consist of the banned and left users. More than 5 members - may be provided, however less than 5 should only be provided - when there are less than 5 members to represent. - - When lazy-loading room members is enabled, the membership - events for the heroes MUST be included in the `state`, - unless they are redundant. When the list of users changes, - the server notifies the client by sending a fresh list of - heroes. If there are no changes since the last sync, this - field may be omitted. - items: - type: string - m.joined_member_count: - type: integer - description: |- - The number of users with `membership` of `join`, - including the client's own user ID. If this field has - not changed since the last sync, it may be omitted. - Required otherwise. - m.invited_member_count: - type: integer - description: |- - The number of users with `membership` of `invite`. - If this field has not changed since the last sync, it - may be omitted. Required otherwise. - state: - title: State - type: object - description: |- - Updates to the state, between the time indicated by - the `since` parameter, and the start of the - `timeline` (or all state up to the start of the - `timeline`, if `since` is not given, or - `full_state` is true). + patternProperties: + "^!": + x-pattern-format: mx-room-id + title: Joined Room + type: object + properties: + summary: + title: RoomSummary + type: object + description: |- + Information about the room which clients may need to + correctly render it to users. + properties: + m.heroes: + type: array + description: |- + The users which can be used to generate a room name + if the room does not have one. Required if the room's + `m.room.name` or `m.room.canonical_alias` state events + are unset or empty. - N.B. state updates for `m.room.member` events will - be incomplete if `lazy_load_members` is enabled in - the `/sync` filter, and only return the member events - required to display the senders of the timeline events - in this response. - allOf: - - $ref: definitions/state_event_batch.yaml - timeline: - title: Timeline - type: object - description: |- - The timeline of messages and state changes in the - room. - allOf: - - $ref: definitions/timeline_batch.yaml - ephemeral: - title: Ephemeral - type: object - description: |- - The new ephemeral events in the room (events that - aren't recorded in the timeline or state of the - room). In this version of the spec, these are - [typing notification](#typing-notifications) and - [read receipt](#receipts) events. - allOf: - - $ref: definitions/event_batch.yaml - account_data: - title: Account Data - type: object - description: |- - The private data that this user has attached to - this room. - allOf: - - $ref: definitions/event_batch.yaml - unread_notifications: - title: Unread Notification Counts - type: object - description: |- - Counts of unread notifications for this room. See the - [Receiving notifications](/client-server-api/#receiving-notifications) section - for more information on how these are calculated. + This should be the first 5 members of the room, ordered + by stream ordering, which are joined or invited. The + list must never include the client's own user ID. When + no joined or invited members are available, this should + consist of the banned and left users. More than 5 members + may be provided, however less than 5 should only be provided + when there are less than 5 members to represent. - If `unread_thread_notifications` was specified as `true` on the `RoomEventFilter`, - these counts will only be for the main timeline rather than all events in the room. - See the [threading module](#threading) for more information. - x-changedInMatrixVersion: - "1.4": | - Updated to reflect behaviour of having `unread_thread_notifications` as `true` in - the `RoomEventFilter` for `/sync`. - properties: - highlight_count: - title: Highlighted notification count - type: integer - description: The number of unread notifications for this room with the highlight - flag set. - notification_count: - title: Total notification count - type: integer - description: The total number of unread notifications for this room. - unread_thread_notifications: - title: Unread Thread Notification Counts - type: object - description: |- - If `unread_thread_notifications` was specified as `true` on the `RoomEventFilter`, - the notification counts for each [thread](#threading) in this room. The object is - keyed by thread root ID, with values matching `unread_notifications`. + When lazy-loading room members is enabled, the membership + events for the heroes MUST be included in the `state`, + unless they are redundant. When the list of users changes, + the server notifies the client by sending a fresh list of + heroes. If there are no changes since the last sync, this + field may be omitted. + items: + type: string + m.joined_member_count: + type: integer + description: |- + The number of users with `membership` of `join`, + including the client's own user ID. If this field has + not changed since the last sync, it may be omitted. + Required otherwise. + m.invited_member_count: + type: integer + description: |- + The number of users with `membership` of `invite`. + If this field has not changed since the last sync, it + may be omitted. Required otherwise. + state: + title: State + type: object + description: |- + Updates to the state, between the time indicated by + the `since` parameter, and the start of the + `timeline` (or all state up to the start of the + `timeline`, if `since` is not given, or + `full_state` is true). - If a thread does not have any notifications it can be omitted from this object. If - no threads have notification counts, this whole object can be omitted. - x-addedInMatrixVersion: "1.4" - additionalProperties: - title: ThreadNotificationCounts + N.B. state updates for `m.room.member` events will + be incomplete if `lazy_load_members` is enabled in + the `/sync` filter, and only return the member events + required to display the senders of the timeline events + in this response. + allOf: + - $ref: definitions/state_event_batch.yaml + timeline: + title: Timeline + type: object + description: |- + The timeline of messages and state changes in the + room. + allOf: + - $ref: definitions/timeline_batch.yaml + ephemeral: + title: Ephemeral + type: object + description: |- + The new ephemeral events in the room (events that + aren't recorded in the timeline or state of the + room). In this version of the spec, these are + [typing notification](#typing-notifications) and + [read receipt](#receipts) events. + allOf: + - $ref: definitions/event_batch.yaml + account_data: + title: Account Data + type: object + description: |- + The private data that this user has attached to + this room. + allOf: + - $ref: definitions/event_batch.yaml + unread_notifications: + title: Unread Notification Counts type: object + description: |- + Counts of unread notifications for this room. See the + [Receiving notifications](/client-server-api/#receiving-notifications) section + for more information on how these are calculated. + + If `unread_thread_notifications` was specified as `true` on the `RoomEventFilter`, + these counts will only be for the main timeline rather than all events in the room. + See the [threading module](#threading) for more information. + x-changedInMatrixVersion: + "1.4": | + Updated to reflect behaviour of having `unread_thread_notifications` as `true` in + the `RoomEventFilter` for `/sync`. properties: highlight_count: - title: ThreadedHighlightNotificationCount + title: Highlighted notification count type: integer - description: The number of unread notifications for this *thread* with the - highlight flag set. + description: The number of unread notifications for this room with the highlight + flag set. notification_count: - title: ThreadedTotalNotificationCount + title: Total notification count type: integer - description: The total number of unread notifications for this *thread*. + description: The total number of unread notifications for this room. + unread_thread_notifications: + title: Unread Thread Notification Counts + type: object + description: |- + If `unread_thread_notifications` was specified as `true` on the `RoomEventFilter`, + the notification counts for each [thread](#threading) in this room. The object is + keyed by thread root ID, with values matching `unread_notifications`. + + If a thread does not have any notifications it can be omitted from this object. If + no threads have notification counts, this whole object can be omitted. + x-addedInMatrixVersion: "1.4" + patternProperties: + "^\\$": + x-pattern-format: mx-event-id + title: ThreadNotificationCounts + type: object + properties: + highlight_count: + title: ThreadedHighlightNotificationCount + type: integer + description: The number of unread notifications for this *thread* with the + highlight flag set. + notification_count: + title: ThreadedTotalNotificationCount + type: integer + description: The total number of unread notifications for this *thread*. invite: title: Invited Rooms type: object description: |- The rooms that the user has been invited to, mapped as room ID to room information. - additionalProperties: - title: Invited Room - type: object - properties: - invite_state: - title: InviteState - type: object - description: |- - The [stripped state](#stripped-state) of a room that the user has been invited - to. - properties: - events: - description: The [stripped state events](#stripped-state) that form the invite - state. - items: - $ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml - type: array + patternProperties: + "^!": + x-pattern-format: mx-room-id + title: Invited Room + type: object + properties: + invite_state: + title: InviteState + type: object + description: |- + The [stripped state](#stripped-state) of a room that the user has been invited + to. + properties: + events: + description: The [stripped state events](#stripped-state) that form the invite + state. + items: + $ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml + type: array knock: title: Knocked rooms type: object description: The rooms that the user has knocked upon, mapped as room ID to room information. - additionalProperties: - title: Knocked Room - type: object - properties: - knock_state: - title: KnockState - type: object - description: The [stripped state](#stripped-state) of a room that the user has - knocked upon. - properties: - events: - description: The [stripped state events](#stripped-state) that form the knock - state. - items: - $ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml - type: array + patternProperties: + "^!": + x-pattern-format: mx-room-id + title: Knocked Room + type: object + properties: + knock_state: + title: KnockState + type: object + description: The [stripped state](#stripped-state) of a room that the user has + knocked upon. + properties: + events: + description: The [stripped state events](#stripped-state) that form the knock + state. + items: + $ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml + type: array leave: title: Left rooms type: object description: |- The rooms that the user has left or been banned from, mapped as room ID to room information. - additionalProperties: - title: Left Room - type: object - properties: - state: - title: State - type: object - description: The state updates for the room up to the start of the timeline. - allOf: - - $ref: definitions/state_event_batch.yaml - timeline: - title: Timeline - type: object - description: |- - The timeline of messages and state changes in the - room up to the point when the user left. - allOf: - - $ref: definitions/timeline_batch.yaml - account_data: - title: Account Data - type: object - description: |- - The private data that this user has attached to - this room. - allOf: - - $ref: definitions/event_batch.yaml + patternProperties: + "^!": + x-pattern-format: mx-room-id + title: Left Room + type: object + properties: + state: + title: State + type: object + description: The state updates for the room up to the start of the timeline. + allOf: + - $ref: definitions/state_event_batch.yaml + timeline: + title: Timeline + type: object + description: |- + The timeline of messages and state changes in the + room up to the point when the user left. + allOf: + - $ref: definitions/timeline_batch.yaml + account_data: + title: Account Data + type: object + description: |- + The private data that this user has attached to + this room. + allOf: + - $ref: definitions/event_batch.yaml presence: title: Presence type: object diff --git a/data/api/client-server/to_device.yaml b/data/api/client-server/to_device.yaml index d8c0fff0..cea23ab7 100644 --- a/data/api/client-server/to_device.yaml +++ b/data/api/client-server/to_device.yaml @@ -57,12 +57,14 @@ paths: The messages to send. A map from user ID, to a map from device ID to message body. The device ID may also be `*`, meaning all known devices for the user. - additionalProperties: - type: object - additionalProperties: + patternProperties: + "^@": + x-pattern-format: mx-user-id type: object - title: EventContent - description: Message content + additionalProperties: + type: object + title: EventContent + description: Message content example: "@alice:example.com": TLLBEANAAG: diff --git a/data/api/server-server/definitions/event-schemas/m.direct_to_device.yaml b/data/api/server-server/definitions/event-schemas/m.direct_to_device.yaml index 6cb59fdd..3740eace 100644 --- a/data/api/server-server/definitions/event-schemas/m.direct_to_device.yaml +++ b/data/api/server-server/definitions/event-schemas/m.direct_to_device.yaml @@ -51,13 +51,15 @@ allOf: The contents of the messages to be sent. These are arranged in a map of user IDs to a map of device IDs to message bodies. The device ID may also be `*`, meaning all known devices for the user. - additionalProperties: - type: object - title: User Devices - additionalProperties: + patternProperties: + "^@": + x-pattern-format: mx-user-id type: object - title: Device Message Contents - properties: {} + title: User Devices + additionalProperties: + type: object + title: Device Message Contents + properties: {} example: { "@alice:example.org": { "IWHQUZUIAH": { diff --git a/data/api/server-server/definitions/event-schemas/m.receipt.yaml b/data/api/server-server/definitions/event-schemas/m.receipt.yaml index 677dc28d..60bff325 100644 --- a/data/api/server-server/definitions/event-schemas/m.receipt.yaml +++ b/data/api/server-server/definitions/event-schemas/m.receipt.yaml @@ -33,54 +33,58 @@ allOf: description: |- Receipts for a particular room. The string key is the room ID for which the receipts under it belong. - additionalProperties: - type: object - title: Room Receipts - properties: - # We strongly define the receipt type to help spec future ones later - # on. At that point, m.read can become optional (maybe). - "m.read": - type: object - description: |- - Read receipts for users in the room. The string key is the user - ID the receipt belongs to. - additionalProperties: + patternProperties: + "^!": + x-pattern-format: mx-room-id + type: object + title: Room Receipts + properties: + # We strongly define the receipt type to help spec future ones later + # on. At that point, m.read can become optional (maybe). + "m.read": type: object - title: User Read Receipt - properties: - event_ids: - type: array - description: |- - The extremity event IDs that the user has read up to. - minItems: 1 - maxItems: 1 - items: - type: string - example: ['$read_this_event:matrix.org'] - data: + description: |- + Read receipts for users in the room. The string key is the user + ID the receipt belongs to. + patternProperties: + "^@": + x-pattern-format: mx-user-id type: object - description: Metadata for the read receipt. - title: Read Receipt Metadata + title: User Read Receipt properties: - ts: - type: integer - format: int64 + event_ids: + type: array description: |- - A POSIX timestamp in milliseconds for when the user read - the event specified in the read receipt. - example: 1533358089009 - thread_id: + The extremity event IDs that the user has read up to. + minItems: 1 + maxItems: 1 + items: type: string - x-addedInMatrixVersion: "1.4" - description: |- - The root thread event's ID (or `main`) for which - thread this receipt is intended to be under. If - not specified, the read receipt is *unthreaded* - (default). - example: "$threadroot" - required: ['ts'] - required: ['event_ids', 'data'] - required: ['m.read'] + example: ['$read_this_event:matrix.org'] + data: + type: object + description: Metadata for the read receipt. + title: Read Receipt Metadata + properties: + ts: + type: integer + format: int64 + description: |- + A POSIX timestamp in milliseconds for when the user read + the event specified in the read receipt. + example: 1533358089009 + thread_id: + type: string + x-addedInMatrixVersion: "1.4" + description: |- + The root thread event's ID (or `main`) for which + thread this receipt is intended to be under. If + not specified, the read receipt is *unthreaded* + (default). + example: "$threadroot" + required: ['ts'] + required: ['event_ids', 'data'] + required: ['m.read'] example: { "!some_room:example.org": { "m.read": { diff --git a/data/api/server-server/transactions.yaml b/data/api/server-server/transactions.yaml index 6edd04c3..48377553 100644 --- a/data/api/server-server/transactions.yaml +++ b/data/api/server-server/transactions.yaml @@ -74,17 +74,19 @@ paths: description: |- The PDUs from the original transaction. The string key represents the ID of the PDU (event) that was processed. - additionalProperties: - type: object - title: PDU Processing Result - description: Information about how the PDU was handled. - properties: - error: - type: string - description: |- - A human readable description about what went wrong in processing this PDU. - If no error is present, the PDU can be considered successfully handled. - example: You are not allowed to send a message to this room. + patternProperties: + "^\\$": + x-pattern-format: mx-event-id + type: object + title: PDU Processing Result + description: Information about how the PDU was handled. + properties: + error: + type: string + description: |- + A human readable description about what went wrong in processing this PDU. + If no error is present, the PDU can be considered successfully handled. + example: You are not allowed to send a message to this room. required: - pdus examples: diff --git a/data/api/server-server/user_keys.yaml b/data/api/server-server/user_keys.yaml index 780303e3..6f242614 100644 --- a/data/api/server-server/user_keys.yaml +++ b/data/api/server-server/user_keys.yaml @@ -36,12 +36,14 @@ paths: The keys to be claimed. A map from user ID, to a map from device ID to algorithm name. Requested users must be local to the receiving homeserver. - additionalProperties: - type: object - additionalProperties: - type: string - description: algorithm - example: signed_curve25519 + patternProperties: + "^@": + x-pattern-format: mx-user-id + type: object + additionalProperties: + type: string + description: algorithm + example: signed_curve25519 example: "@alice:example.com": JLAFKJWSCS: signed_curve25519 @@ -65,35 +67,37 @@ paths: See the [Client-Server Key Algorithms](/client-server-api/#key-algorithms) section for more information on the Key Object format. # User - additionalProperties: - type: object - # Device - additionalProperties: + patternProperties: + "^@": + x-pattern-format: mx-user-id type: object - # Key + # Device additionalProperties: - oneOf: - - type: string - - type: object - title: KeyObject - properties: - key: - type: string - description: The key, encoded using unpadded base64. - signatures: - type: object - title: Signatures - additionalProperties: + type: object + # Key + additionalProperties: + oneOf: + - type: string + - type: object + title: KeyObject + properties: + key: + type: string + description: The key, encoded using unpadded base64. + signatures: type: object + title: Signatures additionalProperties: - type: string - description: |- - Signature of the key object. + type: object + additionalProperties: + type: string + description: |- + Signature of the key object. - The signature is calculated using the process described at [Signing JSON](/appendices/#signing-json). - required: - - key - - signatures + The signature is calculated using the process described at [Signing JSON](/appendices/#signing-json). + required: + - key + - signatures example: "@alice:example.com": JLAFKJWSCS: @@ -124,11 +128,13 @@ paths: device IDs, or to an empty list to indicate all devices for the corresponding user. Requested users must be local to the receiving homeserver. - additionalProperties: - type: array - items: - type: string - description: Device ID + patternProperties: + "^@": + x-pattern-format: mx-user-id + type: array + items: + type: string + description: Device ID example: "@alice:example.com": [] required: @@ -150,23 +156,25 @@ paths: the information returned will be the same as uploaded via `/keys/upload`, with the addition of an `unsigned` property. - additionalProperties: - type: object - additionalProperties: - allOf: - - $ref: ../client-server/definitions/device_keys.yaml - properties: - unsigned: - title: UnsignedDeviceInfo - type: object - description: |- - Additional data added to the device key information - by intermediate servers, and not covered by the - signatures. - properties: - device_display_name: - type: string - description: The display name which the user set on the device. + patternProperties: + "^@": + x-pattern-format: mx-user-id + type: object + additionalProperties: + allOf: + - $ref: ../client-server/definitions/device_keys.yaml + properties: + unsigned: + title: UnsignedDeviceInfo + type: object + description: |- + Additional data added to the device key information + by intermediate servers, and not covered by the + signatures. + properties: + device_display_name: + type: string + description: The display name which the user set on the device. master_keys: x-addedInMatrixVersion: "1.1" type: object @@ -177,8 +185,11 @@ paths: `/keys/device_signing/upload`, along with the signatures uploaded via `/keys/signatures/upload` that the user is allowed to see. - additionalProperties: - $ref: ../client-server/definitions/cross_signing_key.yaml + patternProperties: + "^@": + x-pattern-format: mx-user-id + allOf: + - $ref: ../client-server/definitions/cross_signing_key.yaml example: "@alice:example.com": user_id: "@alice:example.com" @@ -194,8 +205,11 @@ paths: from user ID, to self-signing key information. For each key, the information returned will be the same as uploaded via `/keys/device_signing/upload`. - additionalProperties: - $ref: ../client-server/definitions/cross_signing_key.yaml + patternProperties: + "^@": + x-pattern-format: mx-user-id + allOf: + - $ref: ../client-server/definitions/cross_signing_key.yaml example: "@alice:example.com": user_id: "@alice:example.com" diff --git a/data/custom-formats.yaml b/data/custom-formats.yaml index 5da7e6ab..2075c146 100644 --- a/data/custom-formats.yaml +++ b/data/custom-formats.yaml @@ -32,6 +32,11 @@ mx-event-id: url: /appendices#event-ids # regex: "^\\$" +mx-room-id: + title: Room ID + url: /appendices#room-ids + # regex: "^!" + uri: title: URI url: http://tools.ietf.org/html/rfc3986 diff --git a/data/event-schemas/schema/m.direct.yaml b/data/event-schemas/schema/m.direct.yaml index 3256b574..9b9e8251 100644 --- a/data/event-schemas/schema/m.direct.yaml +++ b/data/event-schemas/schema/m.direct.yaml @@ -9,10 +9,12 @@ description: |- that user ID. properties: content: - additionalProperties: - type: array - items: - type: string + patternProperties: + "^@": + x-pattern-format: mx-user-id + type: array + items: + type: string type: object description: |- The mapping of user ID to a list of room IDs of the 'direct' rooms for diff --git a/data/event-schemas/schema/m.room.power_levels.yaml b/data/event-schemas/schema/m.room.power_levels.yaml index f5f15fab..858c5274 100644 --- a/data/event-schemas/schema/m.room.power_levels.yaml +++ b/data/event-schemas/schema/m.room.power_levels.yaml @@ -67,8 +67,10 @@ properties: by the `events` key. Defaults to 50 if unspecified. type: integer users: - additionalProperties: - type: integer + patternProperties: + "^@": + x-pattern-format: mx-user-id + type: integer description: The power levels for specific users. This is a mapping from `user_id` to power level for that user. title: User power levels type: object