From c662976fab7ad35eeb7e5e82956002d88282e361 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Tue, 2 May 2023 11:41:59 +0100 Subject: [PATCH 01/59] Fix generation of anchors for additional properties (#1488) but objects defined under `additionalProperties` missed out on them. This fixes that. --- .../internal/newsfragments/1488.clarification | 1 + .../json-schema/resolve-additional-types.html | 17 ++++++----------- 2 files changed, 7 insertions(+), 11 deletions(-) create mode 100644 changelogs/internal/newsfragments/1488.clarification diff --git a/changelogs/internal/newsfragments/1488.clarification b/changelogs/internal/newsfragments/1488.clarification new file mode 100644 index 00000000..d54557d9 --- /dev/null +++ b/changelogs/internal/newsfragments/1488.clarification @@ -0,0 +1 @@ +Fix generation of anchors for additional properties diff --git a/layouts/partials/json-schema/resolve-additional-types.html b/layouts/partials/json-schema/resolve-additional-types.html index a93dc0ac..a8f25be4 100644 --- a/layouts/partials/json-schema/resolve-additional-types.html +++ b/layouts/partials/json-schema/resolve-additional-types.html @@ -43,17 +43,12 @@ */}} {{ if $this_object.additionalProperties }} {{ if reflect.IsMap $this_object.additionalProperties }} - {{ $additional_objects = $additional_objects | append (partial "clean-object" $this_object.additionalProperties) }} - - {{ range $key, $property := $this_object.additionalProperties.properties }} - {{ $additional_objects = partial "get-additional-objects" (dict - "this_object" $property - "additional_objects" $additional_objects - "anchor_base" $anchor_base - "name" (printf "%s.%s" $name $key) - ) }} - {{ end }} - + {{ $additional_objects = partial "get-additional-objects" (dict + "this_object" $this_object.additionalProperties + "additional_objects" $additional_objects + "anchor_base" $anchor_base + "name" (printf "%s.additional" $name) + ) }} {{ end }} {{ end }} From cafb45354578aecb9fcc810c1f44d34ea5eace6f Mon Sep 17 00:00:00 2001 From: Kim Brose <2803622+HarHarLinks@users.noreply.github.com> Date: Tue, 2 May 2023 18:02:05 +0200 Subject: [PATCH 02/59] Fix m.location.yaml scheme (#1507) * Fix m.location.yaml scheme This appears to have been mixed up while refactoring https://github.com/matrix-org/matrix-spec/commit/f1f32d3a15c325ee8aa9d2c6bafd96c38069bb53#diff-eb879a272497c490480df3e07215d058ace2fa0bf456447786f299995fb467ef * Create 1507.clarification --- changelogs/client_server/newsfragments/1507.clarification | 1 + data/event-schemas/schema/m.room.message$m.location.yaml | 4 ++-- 2 files changed, 3 insertions(+), 2 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1507.clarification diff --git a/changelogs/client_server/newsfragments/1507.clarification b/changelogs/client_server/newsfragments/1507.clarification new file mode 100644 index 00000000..c810cc8c --- /dev/null +++ b/changelogs/client_server/newsfragments/1507.clarification @@ -0,0 +1 @@ +Clarify `m.location` scheme by partially reverting [f1f32d3](https://github.com/matrix-org/matrix-spec/commit/f1f32d3a15c325ee8aa9d2c6bafd96c38069bb53). Contributed by @HarHarLinks. diff --git a/data/event-schemas/schema/m.room.message$m.location.yaml b/data/event-schemas/schema/m.room.message$m.location.yaml index 37f723f2..27b2b039 100644 --- a/data/event-schemas/schema/m.room.message$m.location.yaml +++ b/data/event-schemas/schema/m.room.message$m.location.yaml @@ -20,8 +20,8 @@ properties: properties: thumbnail_url: description: |- - The URL to the thumbnail of the file. Only present if the - thumbnail is unencrypted. + The URL to a thumbnail of the location being represented. + Only present if the thumbnail is unencrypted. type: string thumbnail_file: description: |- From 6150f71ba1e0a3619fd500032712bd8548a976c3 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Wed, 3 May 2023 10:43:10 +0100 Subject: [PATCH 03/59] Corrections to the response format of `/_matrix/identity/v2/store-invite` (#1486) This has been wrong since the dawn of time. Fixes https://github.com/matrix-org/matrix-spec/issues/495 --- .../newsfragments/1486.clarification | 1 + data/api/identity/v2_store_invite.yaml | 41 ++++++++++++++----- 2 files changed, 31 insertions(+), 11 deletions(-) create mode 100644 changelogs/identity_service/newsfragments/1486.clarification diff --git a/changelogs/identity_service/newsfragments/1486.clarification b/changelogs/identity_service/newsfragments/1486.clarification new file mode 100644 index 00000000..c7372cc4 --- /dev/null +++ b/changelogs/identity_service/newsfragments/1486.clarification @@ -0,0 +1 @@ +Corrections to the response format of `/_matrix/identity/v2/store-invite`. diff --git a/data/api/identity/v2_store_invite.yaml b/data/api/identity/v2_store_invite.yaml index 86845eff..163081bb 100644 --- a/data/api/identity/v2_store_invite.yaml +++ b/data/api/identity/v2_store_invite.yaml @@ -142,20 +142,39 @@ paths: A list of [server's long-term public key, generated ephemeral public key]. items: - type: string + type: object + title: PublicKey + properties: + public_key: + type: string + description: | + The public key, encoded using [unpadded Base64](/appendices/#unpadded-base64). + key_validity_url: + type: string + description: | + The URI of an endpoint where the validity of this key can be checked + by passing it as a `public_key` query parameter. See + [key management](/identity-service-api/#key-management). + required: ['public_key', 'key_validity_url'] display_name: type: string - description: The generated (redacted) display_name. + description: The generated (redacted) display name. required: ['token', 'public_keys', 'display_name'] - example: - application/json: { - "token": "sometoken", - "public_keys": [ - "serverpublickey", - "ephemeralpublickey" - ], - "display_name": "f...@b..." - } + examples: + application/json: { + "token": "sometoken", + "public_keys": [ + { + "public_key": "serverPublicKeyBase64", + "key_validity_url": "https://example.com/_matrix/identity/v2/pubkey/isvalid" + }, + { + "public_key": "ephemeralPublicKeyBase64", + "key_validity_url": "https://example.com/_matrix/identity/v2/pubkey/ephemeral/isvalid" + } + ], + "display_name": "f...@b..." + } 400: description: | An error has occurred. From 283c5877fe079e2de2265398b4e6ced9cf265031 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Wed, 3 May 2023 13:40:54 +0100 Subject: [PATCH 04/59] Spec asynchronous uploads (#1499) Spec for matrix-org/matrix-spec-proposals#2246 --- .../client_server/newsfragments/1499.feature | 2 + content/client-server-api/_index.md | 11 +- data/api/client-server/content-repo.yaml | 270 ++++++++++++++++-- 3 files changed, 262 insertions(+), 21 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1499.feature diff --git a/changelogs/client_server/newsfragments/1499.feature b/changelogs/client_server/newsfragments/1499.feature new file mode 100644 index 00000000..efd70374 --- /dev/null +++ b/changelogs/client_server/newsfragments/1499.feature @@ -0,0 +1,2 @@ +Add new endpoints `POST /_matrix/media/v1/create` and `PUT /_matrix/media/v3/upload/{serverName}/{mediaId}`, and other changes for asynchronous media upload, as per [MSC2246](https://github.com/matrix-org/matrix-spec-proposals/pull/2246). + diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index f9b432d4..55f9987b 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -22,11 +22,12 @@ recommended outside test environments. Clients are authenticated using opaque `access_token` strings (see [Client Authentication](#client-authentication) for details). -All `POST` and `PUT` endpoints, with the exception of -[`POST /_matrix/media/v3/upload`](#post_matrixmediav3upload), require the -client to supply a request body containing a (potentially empty) JSON object. -Clients should supply a `Content-Type` header of `application/json` for all requests with JSON bodies, -but this is not required. +All `POST` and `PUT` endpoints, with the exception of [`POST +/_matrix/media/v3/upload`](#post_matrixmediav3upload) and [`PUT +/_matrix/media/v3/upload/{serverName}/{mediaId}`](http://localhost:1313/client-server-api/#put_matrixmediav3uploadservernamemediaid), +require the client to supply a request body containing a (potentially empty) +JSON object. Clients should supply a `Content-Type` header of +`application/json` for all requests with JSON bodies, but this is not required. Similarly, all endpoints require the server to return a JSON object, with the exception of 200 responses to diff --git a/data/api/client-server/content-repo.yaml b/data/api/client-server/content-repo.yaml index 219e33dd..328ae1c4 100644 --- a/data/api/client-server/content-repo.yaml +++ b/data/api/client-server/content-repo.yaml @@ -20,7 +20,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/media/v3 +basePath: /_matrix consumes: - application/json - "*/*" @@ -30,7 +30,7 @@ produces: securityDefinitions: $ref: definitions/security.yaml paths: - "/upload": + "/media/v3/upload": post: summary: Upload some content to the content repository. operationId: uploadContent @@ -101,7 +101,170 @@ paths: "$ref": "definitions/errors/rate_limited.yaml" tags: - Media - "/download/{serverName}/{mediaId}": + "/media/v3/upload/{serverName}/{mediaId}": + put: + summary: Upload content to an `mxc://` URI that was created earlier. + description: |- + This endpoint permits uploading content to an `mxc://` URI that was created + earlier via [POST /_matrix/media/v1/create](/client-server-api/#post_matrixmediav1create). + operationId: uploadContentToMXC + x-addedInMatrixVersion: "1.7" + parameters: + - in: path + type: string + name: serverName + x-example: matrix.org + required: true + description: | + The server name from the `mxc://` URI returned by `POST /_matrix/media/v1/create` (the authoritory component). + - in: path + type: string + name: mediaId + x-example: ascERGshawAWawugaAcauga + required: true + description: | + The media ID from the `mxc://` URI returned by `POST /_matrix/media/v1/create` (the path component). + - in: header + name: Content-Type + type: string + description: The content type of the file being uploaded + x-example: "application/pdf" + - in: query + type: string + x-example: "War and Peace.pdf" + name: filename + description: The name of the file being uploaded + - in: body + name: "content" + description: The content to be uploaded. + required: true + x-example: "" # so the spec shows "" without quotes. + schema: + type: string + example: "" + format: byte + responses: + 200: + description: The upload was successful. + schema: + type: object + examples: + application/json: {} + 403: + description: |- + The user does not have permission to upload the content. Some reasons for this error include: + + - The server does not permit the file type. + - The user has reached a quota for uploaded content. + - The request comes from a different user than the one that called + [POST /_matrix/media/v1/create](/client-server-api/#post_matrixmediav1create). + + A [standard error response](/client-server-api/#standard-error-response) + will be returned with the `errcode` `M_FORBIDDEN`. + examples: + application/json: { + "errcode": "M_FORBIDDEN", + "error": "Cannot upload this content" + } + schema: + "$ref": "definitions/errors/error.yaml" + 409: + description: |- + The endpoint was called with a media ID that already has content. A + [standard error response](/client-server-api/#standard-error-response) + will be returned with the `errcode` `M_CANNOT_OVERWRITE_MEDIA`. + examples: + application/json: { + "errcode": "M_CANNOT_OVERWRITE_MEDIA", + "error": "Media already uploaded" + } + schema: + "$ref": "definitions/errors/error.yaml" + 413: + description: |- + The uploaded content is too large for the server. + examples: + application/json: { + "errcode": "M_TOO_LARGE", + "error": "Cannot upload files larger than 100mb" + } + schema: + "$ref": "definitions/errors/error.yaml" + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + tags: + - Media + "/media/v1/create": + post: + summary: Create a new `mxc://` URI without uploading the content. + description: |- + Creates a new `mxc://` URI, independently of the content being uploaded. The content must be provided later + via [`PUT /_matrix/media/v3/upload/{serverName}/{mediaId}`](http://localhost:1313/client-server-api/#put_matrixmediav3uploadservernamemediaid). + + The server may optionally enforce a maximum age for unused IDs, + and delete media IDs when the client doesn't start the upload in time, + or when the upload was interrupted and not resumed in time. The server + should include the maximum POSIX millisecond timestamp to complete the + upload in the `unused_expires_at` field in the response JSON. The + recommended default expiration is 24 hours which should be enough time + to accommodate users on poor connection who find a better connection to + complete the upload. + + As well as limiting the rate of requests to create `mxc://` URIs, the server + should limit the number of concurrent *pending media uploads* a given + user can have. A pending media upload is a created `mxc://` URI where (a) + the media has not yet been uploaded, and (b) has not yet expired (the + `unused_expires_at` timestamp has not yet passed). In both cases, the + server should respond with an HTTP 429 error with an errcode of + `M_LIMIT_EXCEEDED`. + operationId: createContent + consumes: ["application/json"] + produces: ["application/json"] + x-addedInMatrixVersion: "1.7" + security: + - accessToken: [] + # empty json object + parameters: [] + responses: + 200: + description: The [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris) for the uploaded content. + schema: + type: object + required: ["content_uri"] + properties: + content_uri: + type: string + format: uri + description: |- + The [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris) at + which the content will be available, once it is uploaded. + example: "mxc://example.com/AQwafuaFswefuhsfAFAgsw" + unused_expires_at: + type: integer + format: int64 + description: |- + The timestamp (in milliseconds since the unix epoch) when the + generated media id will expire, if media is not uploaded. + example: 1647257217083 + 403: + description: |- + The user does not have permission to upload the content. + examples: + application/json: { + "errcode": "M_FORBIDDEN", + "error": "Cannot upload this content" + } + schema: + "$ref": "definitions/errors/error.yaml" + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + tags: + - Media + "/media/v3/download/{serverName}/{mediaId}": get: summary: "Download content from the content repository." operationId: getContent @@ -131,6 +294,20 @@ paths: Indicates to the server that it should not attempt to fetch the media if it is deemed remote. This is to prevent routing loops where the server contacts itself. Defaults to true if not provided. + - in: query + type: integer + format: int64 + name: timeout_ms + x-example: 5000 + x-addedInMatrixVersion: "1.7" + default: 20000 + description: | + The maximum number of milliseconds that the client is willing to + wait to start receiving data, in the case that the content has not + yet been uploaded. The default value is 20000 (20 seconds). The + content repository can and should impose a maximum value for this + parameter. The content repository may also choose to respond before + the timeout. responses: 200: description: "The content that was previously uploaded." @@ -146,6 +323,10 @@ paths: type: file # This is a workaround for us not being able to say the response is required. description: "**Required.** The bytes for the uploaded file." + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" 502: description: |- The content is too large for the server to serve. @@ -156,13 +337,20 @@ paths: } schema: "$ref": "definitions/errors/error.yaml" - 429: - description: This request was rate-limited. + 504: + description: |- + The content is not yet available. A [standard error response](/client-server-api/#standard-error-response) + will be returned with the `errcode` `M_NOT_YET_UPLOADED`. + examples: + application/json: { + "errcode": "M_NOT_YET_UPLOADED", + "error": "Content has not yet been uploaded" + } schema: - "$ref": "definitions/errors/rate_limited.yaml" + "$ref": "definitions/errors/error.yaml" tags: - Media - "/download/{serverName}/{mediaId}/{fileName}": + "/media/v3/download/{serverName}/{mediaId}/{fileName}": get: summary: Download content from the content repository overriding the file name description: |- @@ -202,6 +390,20 @@ paths: Indicates to the server that it should not attempt to fetch the media if it is deemed remote. This is to prevent routing loops where the server contacts itself. Defaults to true if not provided. + - in: query + type: integer + format: int64 + name: timeout_ms + x-example: 5000 + x-addedInMatrixVersion: "1.7" + default: 20000 + description: | + The maximum number of milliseconds that the client is willing to + wait to start receiving data, in the case that the content has not + yet been uploaded. The default value is 20000 (20 seconds). The + content repository can and should impose a maximum value for this + parameter. The content repository may also choose to respond before + the timeout. responses: 200: description: "The content that was previously uploaded." @@ -218,6 +420,10 @@ paths: type: file # This is a workaround for us not being able to say the response is required. description: "**Required.** The bytes for the uploaded file." + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" 502: description: |- The content is too large for the server to serve. @@ -228,13 +434,20 @@ paths: } schema: "$ref": "definitions/errors/error.yaml" - 429: - description: This request was rate-limited. + 504: + description: |- + The content is not yet available. A [standard error response](/client-server-api/#standard-error-response) + will be returned with the `errcode` `M_NOT_YET_UPLOADED`. + examples: + application/json: { + "errcode": "M_NOT_YET_UPLOADED", + "error": "Content has not yet been uploaded" + } schema: - "$ref": "definitions/errors/rate_limited.yaml" + "$ref": "definitions/errors/error.yaml" tags: - Media - "/thumbnail/{serverName}/{mediaId}": + "/media/v3/thumbnail/{serverName}/{mediaId}": get: summary: Download a thumbnail of content from the content repository description: |- @@ -291,6 +504,20 @@ paths: Indicates to the server that it should not attempt to fetch the media if it is deemed remote. This is to prevent routing loops where the server contacts itself. Defaults to true if not provided. + - in: query + type: integer + format: int64 + name: timeout_ms + x-example: 5000 + x-addedInMatrixVersion: "1.7" + default: 20000 + description: | + The maximum number of milliseconds that the client is willing to + wait to start receiving data, in the case that the content has not + yet been uploaded. The default value is 20000 (20 seconds). The + content repository can and should impose a maximum value for this + parameter. The content repository may also choose to respond before + the timeout. responses: 200: description: "A thumbnail of the requested content." @@ -325,6 +552,10 @@ paths: } schema: "$ref": "definitions/errors/error.yaml" + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" 502: description: |- The remote content is too large for the server to thumbnail. @@ -335,13 +566,20 @@ paths: } schema: "$ref": "definitions/errors/error.yaml" - 429: - description: This request was rate-limited. + 504: + description: |- + The content is not yet available. A [standard error response](/client-server-api/#standard-error-response) + will be returned with the `errcode` `M_NOT_YET_UPLOADED`. + examples: + application/json: { + "errcode": "M_NOT_YET_UPLOADED", + "error": "Content has not yet been uploaded" + } schema: - "$ref": "definitions/errors/rate_limited.yaml" + "$ref": "definitions/errors/error.yaml" tags: - Media - "/preview_url": + "/media/v3/preview_url": get: summary: "Get information about a URL for a client" description: |- @@ -410,7 +648,7 @@ paths: "$ref": "definitions/errors/rate_limited.yaml" tags: - Media - "/config": + "/media/v3/config": get: summary: Get the configuration for the content repository. description: |- From e1dc5f8f53a4ec1eee2a26ed03bbd9e0ca0067d1 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Wed, 3 May 2023 09:39:49 -0400 Subject: [PATCH 05/59] Remove the `dont_notify` and `coalesce` push rule actions. (#1501) * Remove the `dont_notify` and `coalesce` push rule actions. Per MSC3987, these should both be considered no-ops. * Remove obsolete dont_notify from default rules. * Remove obsolete dont_notify from examples. --- .../newsfragments/1501.clarification | 1 + content/client-server-api/modules/push.md | 33 +++++++------------ data/api/client-server/pushrules.yaml | 12 ++----- data/event-schemas/examples/m.push_rules.yaml | 8 ++--- 4 files changed, 17 insertions(+), 37 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1501.clarification diff --git a/changelogs/client_server/newsfragments/1501.clarification b/changelogs/client_server/newsfragments/1501.clarification new file mode 100644 index 00000000..97fa837c --- /dev/null +++ b/changelogs/client_server/newsfragments/1501.clarification @@ -0,0 +1 @@ +Remove the `dont_notify` and `coalesce` push rule actions per [MSC3987](https://github.com/matrix-org/matrix-spec-proposals/pull/3987). diff --git a/content/client-server-api/modules/push.md b/content/client-server-api/modules/push.md index 66c498ea..9a2a671f 100644 --- a/content/client-server-api/modules/push.md +++ b/content/client-server-api/modules/push.md @@ -147,17 +147,6 @@ actions are defined: : This causes each matching event to generate a notification. -`dont_notify` - -: This prevents each matching event from generating a notification. - -`coalesce` - -: This enables notifications for matching events but activates homeserver - specific behaviour to intelligently coalesce multiple events into a - single notification. Not all homeservers may support this. Those that do - not support it should treat it as the `notify` action. - `set_tweak` : Sets an entry in the `tweaks` dictionary key that is sent in the @@ -195,6 +184,12 @@ they are represented as a dictionary with a key equal to their name and other keys as their parameters, e.g. `{ "set_tweak": "sound", "value": "default" }`. +{{% boxes/note %}} +Older versions of the Matrix specification included the `dont_notify` and +`coalesce` actions. These should both be considered no-ops (ignored, not +rejected) if received from a client. +{{% /boxes/note %}} + ##### Conditions `override` and `underride` rules MAY have a list of 'conditions'. All @@ -440,9 +435,7 @@ Definition: "default": true, "enabled": false, "conditions": [], - "actions": [ - "dont_notify" - ] + "actions": [] } ``` @@ -464,9 +457,7 @@ Definition: "pattern": "m.notice", } ], - "actions": [ - "dont_notify", - ] + "actions": [] } ``` @@ -526,9 +517,7 @@ Definition: "pattern": "m.room.member" } ], - "actions": [ - "dont_notify" - ] + "actions": [] } ``` @@ -882,14 +871,14 @@ To create a rule that suppresses notifications for the room with ID curl -X PUT -H "Content-Type: application/json" "https://example.com/_matrix/client/v3/pushrules/global/room/%21dj234r78wl45Gh4D%3Amatrix.org?access_token=123456" -d \ '{ - "actions" : ["dont_notify"] + "actions" : [] }' To suppress notifications for the user `@spambot:matrix.org`: curl -X PUT -H "Content-Type: application/json" "https://example.com/_matrix/client/v3/pushrules/global/sender/%40spambot%3Amatrix.org?access_token=123456" -d \ '{ - "actions" : ["dont_notify"] + "actions" : [] }' To always notify for messages that contain the work 'cake' and set a diff --git a/data/api/client-server/pushrules.yaml b/data/api/client-server/pushrules.yaml index 3a67aea8..817138d1 100644 --- a/data/api/client-server/pushrules.yaml +++ b/data/api/client-server/pushrules.yaml @@ -75,18 +75,14 @@ paths: ], "override": [ { - "actions": [ - "dont_notify" - ], + "actions": [], "conditions": [], "default": true, "enabled": false, "rule_id": ".m.rule.master" }, { - "actions": [ - "dont_notify" - ], + "actions": [], "conditions": [ { "key": "content.msgtype", @@ -286,9 +282,7 @@ paths: rule itself such as the rule's `actions` and `conditions` if set. examples: application/json: { - "actions": [ - "dont_notify" - ], + "actions": [], "pattern": "cake*lie", "rule_id": "nocake", "enabled": true, diff --git a/data/event-schemas/examples/m.push_rules.yaml b/data/event-schemas/examples/m.push_rules.yaml index 34bc2fe6..639c6ec7 100644 --- a/data/event-schemas/examples/m.push_rules.yaml +++ b/data/event-schemas/examples/m.push_rules.yaml @@ -23,18 +23,14 @@ ], "override": [ { - "actions": [ - "dont_notify" - ], + "actions": [], "conditions": [], "default": true, "enabled": false, "rule_id": ".m.rule.master" }, { - "actions": [ - "dont_notify" - ], + "actions": [], "conditions": [ { "key": "content.msgtype", From 50757e61b70d939f2b2d0b0c9e6e823005a3ed94 Mon Sep 17 00:00:00 2001 From: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> Date: Thu, 4 May 2023 10:04:23 +0100 Subject: [PATCH 06/59] Fix a list formatting error under C-S API -> `m.room.member` definition (#1509) * Fix a list formatting error under C-S API -> m.room.member definition * changelog --- changelogs/client_server/newsfragments/1509.clarification | 1 + data/event-schemas/schema/m.room.member.yaml | 4 ---- 2 files changed, 1 insertion(+), 4 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1509.clarification diff --git a/changelogs/client_server/newsfragments/1509.clarification b/changelogs/client_server/newsfragments/1509.clarification new file mode 100644 index 00000000..ca5f3aea --- /dev/null +++ b/changelogs/client_server/newsfragments/1509.clarification @@ -0,0 +1 @@ +Fix various typos throughout the specification. \ No newline at end of file diff --git a/data/event-schemas/schema/m.room.member.yaml b/data/event-schemas/schema/m.room.member.yaml index 24b6005f..f2d297b5 100644 --- a/data/event-schemas/schema/m.room.member.yaml +++ b/data/event-schemas/schema/m.room.member.yaml @@ -7,13 +7,9 @@ description: |- The following membership states are specified: - `invite` - The user has been invited to join a room, but has not yet joined it. They may not participate in the room until they join. - - `join` - The user has joined the room (possibly after accepting an invite), and may participate in it. - - `leave` - The user was once joined to the room, but has since left (possibly by choice, or possibly by being kicked). - - `ban` - The user has been banned from the room, and is no longer allowed to join it until they are un-banned from the room (by having their membership state set to a value other than `ban`). - - `knock` - The user has knocked on the room, requesting permission to participate. They may not participate in the room until they join. The `third_party_invite` property will be set if this invite is an `invite` event and is the successor of an `m.room.third_party_invite` event, and absent otherwise. From ade2d292104692a8bb39aa2313629519987e5faf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Thu, 4 May 2023 14:31:47 +0200 Subject: [PATCH 07/59] Fix internal link to asynchronous upload enpoint (#1510) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Fix internal link to asynchronous upload enpoint Signed-off-by: Kévin Commaille * Add changelog Signed-off-by: Kévin Commaille --------- Signed-off-by: Kévin Commaille --- changelogs/client_server/newsfragments/1510.feature | 2 ++ content/client-server-api/_index.md | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) create mode 100644 changelogs/client_server/newsfragments/1510.feature diff --git a/changelogs/client_server/newsfragments/1510.feature b/changelogs/client_server/newsfragments/1510.feature new file mode 100644 index 00000000..efd70374 --- /dev/null +++ b/changelogs/client_server/newsfragments/1510.feature @@ -0,0 +1,2 @@ +Add new endpoints `POST /_matrix/media/v1/create` and `PUT /_matrix/media/v3/upload/{serverName}/{mediaId}`, and other changes for asynchronous media upload, as per [MSC2246](https://github.com/matrix-org/matrix-spec-proposals/pull/2246). + diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 55f9987b..cf00870b 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -24,7 +24,7 @@ Authentication](#client-authentication) for details). All `POST` and `PUT` endpoints, with the exception of [`POST /_matrix/media/v3/upload`](#post_matrixmediav3upload) and [`PUT -/_matrix/media/v3/upload/{serverName}/{mediaId}`](http://localhost:1313/client-server-api/#put_matrixmediav3uploadservernamemediaid), +/_matrix/media/v3/upload/{serverName}/{mediaId}`](#put_matrixmediav3uploadservernamemediaid), require the client to supply a request body containing a (potentially empty) JSON object. Clients should supply a `Content-Type` header of `application/json` for all requests with JSON bodies, but this is not required. From dc5d95c242d1cf64ac19fea656649026c62cd1eb Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Mon, 8 May 2023 06:36:56 -0400 Subject: [PATCH 08/59] Clarify signatures upload endpoint (#1495) * clarify signatures upload endpoint * add changelog --- .../client_server/newsfragments/1495.clarification | 1 + data/api/client-server/cross_signing.yaml | 11 ++++++++--- 2 files changed, 9 insertions(+), 3 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1495.clarification diff --git a/changelogs/client_server/newsfragments/1495.clarification b/changelogs/client_server/newsfragments/1495.clarification new file mode 100644 index 00000000..8132e060 --- /dev/null +++ b/changelogs/client_server/newsfragments/1495.clarification @@ -0,0 +1 @@ +Clarify parts of the end-to-end encryption sections. diff --git a/data/api/client-server/cross_signing.yaml b/data/api/client-server/cross_signing.yaml index 0ac32cfb..817aeca9 100644 --- a/data/api/client-server/cross_signing.yaml +++ b/data/api/client-server/cross_signing.yaml @@ -149,8 +149,12 @@ paths: x-addedInMatrixVersion: "1.1" summary: Upload cross-signing signatures. description: |- - Publishes cross-signing signatures for the user. The request body is a - map from user ID to key ID to signed JSON object. + Publishes cross-signing signatures for the user. + + The request body is a map from user ID to key ID to signed JSON object. + The signed JSON object must match the key previously uploaded or + retrieved for the given key ID, with the exception of the `signatures` + property, which contains the new signature(s) to add. operationId: uploadCrossSigningSignatures security: - accessToken: [] @@ -158,7 +162,8 @@ paths: - in: body name: signatures description: |- - The signatures to be published. + A map from user ID to key ID to signed JSON objects containing the + signatures to be published. required: true schema: type: object From 188d568f3a086e4d2ceadad05d08ccac59a0e738 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Mon, 15 May 2023 16:31:47 +0100 Subject: [PATCH 09/59] Add 'deprecated:true' to /v1/send_{join,leave} (#1518) The words already say this is deprecated, but it was missing the flag. --- changelogs/server_server/newsfragments/1518.clarification | 1 + data/api/server-server/joins-v1.yaml | 1 + data/api/server-server/leaving-v1.yaml | 1 + 3 files changed, 3 insertions(+) create mode 100644 changelogs/server_server/newsfragments/1518.clarification diff --git a/changelogs/server_server/newsfragments/1518.clarification b/changelogs/server_server/newsfragments/1518.clarification new file mode 100644 index 00000000..3ccb2333 --- /dev/null +++ b/changelogs/server_server/newsfragments/1518.clarification @@ -0,0 +1 @@ +Fix various typos throughout the specification. diff --git a/data/api/server-server/joins-v1.yaml b/data/api/server-server/joins-v1.yaml index edb987f2..c9480c49 100644 --- a/data/api/server-server/joins-v1.yaml +++ b/data/api/server-server/joins-v1.yaml @@ -218,6 +218,7 @@ paths: "/send_join/{roomId}/{eventId}": put: + deprecated: true summary: Submit a signed join event to a resident server description: |- **Note:** diff --git a/data/api/server-server/leaving-v1.yaml b/data/api/server-server/leaving-v1.yaml index 40c8a062..5264d38c 100644 --- a/data/api/server-server/leaving-v1.yaml +++ b/data/api/server-server/leaving-v1.yaml @@ -141,6 +141,7 @@ paths: } "/send_leave/{roomId}/{eventId}": put: + deprecated: true summary: Submit a signed leave event to a resident server description: |- **Note:** From c1ac9a9ad793c07c1699b5b0fd2ea01436513443 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Tue, 16 May 2023 21:33:05 +0100 Subject: [PATCH 10/59] Update transaction ID scope (#1526) --- .../client_server/newsfragments/1526.feature | 1 + content/client-server-api/_index.md | 30 +++++++++++++------ 2 files changed, 22 insertions(+), 9 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1526.feature diff --git a/changelogs/client_server/newsfragments/1526.feature b/changelogs/client_server/newsfragments/1526.feature new file mode 100644 index 00000000..f26f96eb --- /dev/null +++ b/changelogs/client_server/newsfragments/1526.feature @@ -0,0 +1 @@ +Update the scope of transaction IDs, as per [MSC3970](https://github.com/matrix-org/matrix-spec-proposals/pull/3970). diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index cf00870b..798835a0 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -237,19 +237,32 @@ For example, `PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}` would return a `200 OK` with the `event_id` of the original request in the response body. -As well as the HTTP path, the scope of a transaction ID is a "client -session", where that session is identified by a particular access token. -When [refreshing](#refreshing-access-tokens) an access token, the -transaction ID's scope is retained. This means that if a client with -token `A` uses `TXN1` as their transaction ID, refreshes the token to -`B`, and uses `TXN1` again it'll be assumed to be a duplicate request -and ignored. If the client logs out and back in between the `A` and `B` -tokens, `TXN1` could be used once for each. +The scope of a transaction ID is for a single [device](../index.html#devices), +and a single HTTP endpoint. In other words: a single device could use the same +transaction ID for a request to [`PUT +/_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`](#put_matrixclientv3roomsroomidsendeventtypetxnid) +and [`PUT +/_matrix/client/v3/sendToDevice/{eventType}/{txnId}`](#put_matrixclientv3sendtodeviceeventtypetxnid), +and the two requests would be considered distinct because the two are +considered separate endpoints. Similarly, if a client logs out and back in +between two requests using the same transaction ID, the requests are distinct +because the act of logging in and out creates a new device (unless an existing +`device_id` is passed to [`POST +/_matrix/client/v3/login`](#post_matrixclientv3login)). On the other hand, if a +client re-uses a transaction ID for the same endpoint after +[refreshing](#refreshing-access-tokens) an access token, it will be assumed to +be a duplicate request and ignored. See also +[Relationship between access tokens and devices](#relationship-between-access-tokens-and-devices). Some API endpoints may allow or require the use of `POST` requests without a transaction ID. Where this is optional, the use of a `PUT` request is strongly recommended. +{{% boxes/rationale %}} +Prior to `v1.7`, transaction IDs were scoped to "client sessions" rather than +devices. +{{% /boxes/rationale %}} + ## Web Browser Clients It is realistic to expect that some clients will be written to be run @@ -2671,4 +2684,3 @@ systems. {{< cs-module name="event_annotations" >}} {{< cs-module name="threading" >}} {{< cs-module name="reference_relations" >}} - From 9766b142f1d130b0392ba09a2398bd98abfb0ebe Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Tue, 16 May 2023 21:35:44 +0100 Subject: [PATCH 11/59] event_replacements: fix rationale box (#1525) This was missing its %s --- changelogs/client_server/newsfragments/1525.feature | 1 + content/client-server-api/modules/event_replacements.md | 4 ++-- 2 files changed, 3 insertions(+), 2 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1525.feature diff --git a/changelogs/client_server/newsfragments/1525.feature b/changelogs/client_server/newsfragments/1525.feature new file mode 100644 index 00000000..119ab2d6 --- /dev/null +++ b/changelogs/client_server/newsfragments/1525.feature @@ -0,0 +1 @@ +Changes to the server-side aggregation of `m.replace` (edit) events, as per [MSC3925](https://github.com/matrix-org/matrix-spec-proposals/pull/3925). diff --git a/content/client-server-api/modules/event_replacements.md b/content/client-server-api/modules/event_replacements.md index 6767b73f..1f0985ed 100644 --- a/content/client-server-api/modules/event_replacements.md +++ b/content/client-server-api/modules/event_replacements.md @@ -249,14 +249,14 @@ events](#redactions-of-edited-events) below. **Note:** the `content` of the original event is left intact. In particular servers should **not** replace the content with that of the replacement event. -{{ boxes/rationale }} +{{% boxes/rationale %}} In previous versions of the specification, servers were expected to replace the content of an edited event whenever it was served to clients (with the exception of the [`GET /_matrix/client/v3/rooms/{roomId}/event/{eventId}`](#get_matrixclientv3roomsroomideventeventid) endpoint). However, that behaviour made reliable client-side implementation difficult, and servers should no longer make this replacement. -{{ /boxes/rationale }} +{{% /boxes/rationale %}} #### Client behaviour From 466acdfc467befa46278a5bfdbd51dec1db9ea13 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Wed, 17 May 2023 08:16:23 -0400 Subject: [PATCH 12/59] Update spec for MSC3952: intentional mentions (#1508) See MSC3952. --- .../client_server/newsfragments/1508.feature | 2 + .../modules/event_replacements.md | 67 ++++++++++++++ content/client-server-api/modules/mentions.md | 81 ++++++++++------- content/client-server-api/modules/push.md | 89 ++++++++++++++++++- .../client-server-api/modules/rich_replies.md | 32 ++++++- .../client-server/definitions/m.mentions.yaml | 37 ++++++++ 6 files changed, 271 insertions(+), 37 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1508.feature create mode 100644 data/api/client-server/definitions/m.mentions.yaml diff --git a/changelogs/client_server/newsfragments/1508.feature b/changelogs/client_server/newsfragments/1508.feature new file mode 100644 index 00000000..66e9670f --- /dev/null +++ b/changelogs/client_server/newsfragments/1508.feature @@ -0,0 +1,2 @@ +Document the `m.mentions` property; the `.m.rule.is_user_mention` and `.m.rule.is_room_mention` push rules; and other behaviour from [MSC3952](https://github.com/matrix-org/matrix-spec-proposals/pull/3952). + diff --git a/content/client-server-api/modules/event_replacements.md b/content/client-server-api/modules/event_replacements.md index 1f0985ed..9afe304e 100644 --- a/content/client-server-api/modules/event_replacements.md +++ b/content/client-server-api/modules/event_replacements.md @@ -293,6 +293,73 @@ events will not be included in the aggregation bundled with the original event. Note that the subsequent edits are not actually redacted themselves: they simply serve no purpose within the visible timeline. +#### Edits of events with mentions + +When editing an event with [user and room mentions](#user-and-room-mentions) the +replacement event will have two `m.mentions` properties: + +* One at the top-level of the `content`, which should contain mentions due to + this edit revision. +* One inside the `m.new_content` property, which should contain the resolved mentions + for the final version of the event. + +The difference between these properties ensures that users will not be notified +for each edit revision of an event, but allows for new users to be mentioned (or +for re-notifying if the sending client feels a large enough revision was made). + +For example, if there is an event mentioning Alice: + +```json5 +{ + "event_id": "$original_event", + "type": "m.room.message", + "content": { + "body": "Hello Alice!", + "m.mentions": { + "user_ids": ["@alice:example.org"] + } + } +} +``` + +And an edit to also mention Bob: + +```json5 +{ + "content": { + "body": "* Hello Alice & Bob!", + "m.mentions": { + "user_ids": [ + // Include only the newly mentioned user. + "@bob:example.org" + ] + }, + "m.new_content": { + "body": "Hello Alice & Bob!", + "m.mentions": { + "user_ids": [ + // Include all of the mentioned users. + "@alice:example.org", + "@bob:example.org" + ] + }, + }, + "m.relates_to": { + "rel_type": "m.replace", + "event_id": "$original_event" + } + }, + // other fields as required by events +} +``` + +If an edit revision removes a user's mention then that user's Matrix ID should be +included in neither `m.mentions` property. + +Clients may also wish to modify the [client behaviour](#user-and-room-mentions) of +determining if an event mentions the current user by checking the `m.mentions` +property under `m.new_content`. + #### Edits of replies Some particular constraints apply to events which replace a diff --git a/content/client-server-api/modules/mentions.md b/content/client-server-api/modules/mentions.md index fe51208c..32309740 100644 --- a/content/client-server-api/modules/mentions.md +++ b/content/client-server-api/modules/mentions.md @@ -1,61 +1,76 @@ ### User and room mentions -This module allows users to mention other users and rooms within a room message. -This is achieved by including a [Matrix URI](/appendices/#uris) in the HTML body of -an [m.room.message](#mroommessage) event. This module does not have any server-specific -behaviour to it. +{{% changed-in v="1.7" %}} -Mentions apply only to [m.room.message](#mroommessage) events where the `msgtype` is -`m.text`, `m.emote`, or `m.notice`. The `format` for the event must be -`org.matrix.custom.html` and therefore requires a `formatted_body`. +This module allows users to "mention" other users and rooms within a room event. +This is primarily used as an indicator that the recipient should receive a notification +about the event. +This is achieved by including metadata in the `m.mentions` content property of +the event to reference the entity being mentioned. -To make a mention, reference the entity being mentioned in the -`formatted_body` using an anchor, like so: +`m.mentions` is defined as follows: -```json -{ - "body": "Hello Alice!", - "msgtype": "m.text", - "format": "org.matrix.custom.html", - "formatted_body": "Hello Alice!" -} -``` +{{% definition path="api/client-server/definitions/m.mentions" %}} + +Additionally, see the [`.m.rule.is_user_mention`](#_m_rule_is_user_mention) and +[`.m.rule.is_room_mention`](#_m_rule_is_room_mention) push rules. +Users should not add their own Matrix ID to the `m.mentions` property as outgoing +messages cannot self-notify. + +{{% boxes/warning %}} +If an encrypted event contains an `m.mentions` in its payload, it should be +encrypted as normal. To properly process mentions in encrypted rooms, events +must be decrypted first. See [receiving notifications](#receiving-notifications). +{{% /boxes/warning %}} + +Note that, for backwards compatibility, push rules such as [`.m.rule.contains_display_name`](#_m_rule_contains_display_name), +[`.m.rule.contains_user_name`](#_m_rule_contains_user_name), and +[`.m.rule.roomnotif`](#_m_rule_roomnotif) continue to match if the `body` of +the event contains the user's display name or ID. To avoid unintentional notifications, +**it is recommended that clients include a `m.mentions` property on each event**. +(If there are no mentions to include it can be an empty object.) + +{{% boxes/rationale %}} +In previous versions of the specification, mentioning users was done by +including the user's display name or the localpart of their Matrix ID and room +mentions were done by including the string "@room" in the plaintext `body` of +the event. This was prone to confusing and buggy behaviour. +{{% /boxes/rationale %}} #### Client behaviour -In addition to using the appropriate `Matrix URI` for the mention, -clients should use the following guidelines when making mentions in -events to be sent: +Although it is possible to silently mention users, it is recommended to include a +[Matrix URI](/appendices/#uris) in the HTML body of an [m.room.message](#mroommessage) +event. This applies only to [m.room.message](#mroommessage) events where the `msgtype` is +`m.text`, `m.emote`, or `m.notice`. The `format` for the event must be +`org.matrix.custom.html` and therefore requires a `formatted_body`. -- When mentioning users, use the user's potentially ambiguous display +Clients should use the following guidelines when adding a `Matrix URI` +representing a mention to events to be sent: + +- When linking to users, use the user's potentially ambiguous display name for the anchor's text. If the user does not have a display name, use the user's ID. -- When mentioning rooms, use the canonical alias for the room. If the +- When linking to rooms, use the canonical alias for the room. If the room does not have a canonical alias, prefer one of the aliases listed on the room. If no alias can be found, fall back to the room ID. In all cases, use the alias/room ID being linked to as the anchor's text. The text component of the anchor should be used in the event's `body` -where the mention would normally be represented, as shown in the example +where the link would normally be represented, as shown in the example above. Clients should display mentions differently from other elements. For example, this may be done by changing the background color of the mention to indicate that it is different from a normal link. -If the current user is mentioned in a message (either by a mention as -defined in this module or by a push rule), the client should show that +If the current user is mentioned in a message, the client should show that mention differently from other mentions, such as by using a red -background color to signify to the user that they were mentioned. +background color to signify to the user that they were mentioned. Note that +it is possible for a user to be mentioned without including their `Matrix URI` +in the event. When clicked, the mention should navigate the user to the appropriate user or room information. - -{{% boxes/note %}} -Similar to legacy [matrix.to URLs](/appendices/#matrixto-navigation), -groups used to be representable by mentions. They follow a similar format -to room mentions, though using the group ID in both the link and anchor -text. -{{% /boxes/note %}} \ No newline at end of file diff --git a/content/client-server-api/modules/push.md b/content/client-server-api/modules/push.md index 9a2a671f..ad2c544b 100644 --- a/content/client-server-api/modules/push.md +++ b/content/client-server-api/modules/push.md @@ -521,7 +521,46 @@ Definition: } ``` -**`.m.rule.contains_display_name`** + **`.m.rule.is_user_mention`** + +{{< added-in v="1.7" >}} + +Matches any message which contains the user's Matrix ID in the list of `user_ids` +under the `m.mentions` property. + +Definition: + +```json +{ + "rule_id": ".m.rule.is_user_mention", + "default": true, + "enabled": true, + "conditions": [ + { + "kind": "event_property_contains", + "key": "content.m\\.mentions.user_ids", + "value": "[the user's Matrix ID]" + } + ], + "actions": [ + "notify", + { + "set_tweak": "sound", + "value": "default" + }, + { + "set_tweak": "highlight" + } + ] +} +``` + + **`.m.rule.contains_display_name`** + +{{% changed-in v="1.7" %}} + +As of `v1.7`, this rule is deprecated and **should only be enabled if the event +does not have an [`m.mentions` property](#definition-mmentions)**. Matches any message whose content contains the user's current display name in the room in which it was sent. @@ -551,7 +590,46 @@ Definition: } ``` -**`.m.rule.roomnotif`** + **`.m.rule.is_room_mention`** + +{{< added-in v="1.7" >}} + +Matches any message from a sender with the proper power level with the `room` +property of the `m.mentions` property set to `true`. + +Definition: + +```json +{ + "rule_id": ".m.rule.is_room_mention", + "default": true, + "enabled": true, + "conditions": [ + { + "kind": "event_property_is", + "key": "content.m\\.mentions.room", + "value": true + }, + { + "kind": "sender_notification_permission", + "key": "room" + } + ], + "actions": [ + "notify", + { + "set_tweak": "highlight" + } + ] +} +``` + + **`.m.rule.roomnotif`** + +{{% changed-in v="1.7" %}} + +As of `v1.7`, this rule is deprecated and **should only be enabled if the event +does not have an [`m.mentions` property](#definition-mmentions)**. Matches any message from a sender with the proper power level whose content contains the text `@room`, signifying the whole room should be notified of @@ -674,7 +752,12 @@ Definition: ##### Default Content Rules -**`.m.rule.contains_user_name`** + **`.m.rule.contains_user_name`** + +{{% changed-in v="1.7" %}} + +As of `v1.7`, this rule is deprecated and **should only be enabled if the event +does not have an [`m.mentions` property](#definition-mmentions)**. Matches any message whose content contains the local part of the user's Matrix ID, separated by word boundaries. diff --git a/content/client-server-api/modules/rich_replies.md b/content/client-server-api/modules/rich_replies.md index 5132c36e..a0018630 100644 --- a/content/client-server-api/modules/rich_replies.md +++ b/content/client-server-api/modules/rich_replies.md @@ -176,4 +176,34 @@ This is where the reply goes. For `m.image`, the text should be `"sent an image."`. For `m.video`, the text should be `"sent a video."`. For `m.audio`, the text should be -`"sent an audio file"`. \ No newline at end of file +`"sent an audio file"`. + +#### Mentioning the replied to user + +In order to notify users of the reply, it may be desirable to include the `sender` +of the replied to event and any users mentioned in that event. See +[user and room mentions](#user-and-room-mentions) for additional information. + +An example including mentioning the original sender and other users: + +```json5 +{ + "content": { + "m.relates_to": { + "m.in_reply_to": { + "event_id": "$another_event" + } + }, + "body": "That sounds like a great idea!", + "m.mentions": { + "user_ids": [ + // The sender of $another_event. + "@alice:example.org", + // Another Matrix ID copied from the m.mentions property of $another_event. + "@bob:example.org" + ] + } + }, + // other fields as required by events +} +``` diff --git a/data/api/client-server/definitions/m.mentions.yaml b/data/api/client-server/definitions/m.mentions.yaml new file mode 100644 index 00000000..806897b4 --- /dev/null +++ b/data/api/client-server/definitions/m.mentions.yaml @@ -0,0 +1,37 @@ +# Copyright 2023 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# 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. + +type: object +title: m.mentions +description: |- + Describes whether the event mentions other users or the room. This is contained + within the event's `content` alongside other fields for the relevant event type. +example: { + "body": "Hello Alice!", + "msgtype": "m.text", + "format": "org.matrix.custom.html", + "formatted_body": "Hello Alice!", + "m.mentions": { + "user_ids": ["@alice:example.org"] + } +} +properties: + user_ids: + type: string[] + description: A list of Matrix IDs of mentioned users. + room: + type: boolean + description: |- + A boolean set to `true` to mention the room, for an `@room` notification. + (`room` should otherwise not be included on the event.) From 4fabef1c973222242531318bdc3fdc7d71b0b063 Mon Sep 17 00:00:00 2001 From: Nick Mills-Barrett Date: Wed, 17 May 2023 16:17:20 +0100 Subject: [PATCH 13/59] Add `allow_redirect` query parameter to relevant media endpoints (#1529) * Add `allow_redirect` query parameter to relevant media endpoints * Add added in version flag to `allow_redirect` params * Add 307/308 responses to media endpoints * Add changelogs --- .../client_server/newsfragments/1529.feature | 1 + data/api/client-server/content-repo.yaml | 69 +++++++++++++++++++ 2 files changed, 70 insertions(+) create mode 100644 changelogs/client_server/newsfragments/1529.feature diff --git a/changelogs/client_server/newsfragments/1529.feature b/changelogs/client_server/newsfragments/1529.feature new file mode 100644 index 00000000..48f1d90b --- /dev/null +++ b/changelogs/client_server/newsfragments/1529.feature @@ -0,0 +1 @@ +Addition of redirect downloads, as per [MSC3860](https://github.com/matrix-org/matrix-spec-proposals/pull/3860). diff --git a/data/api/client-server/content-repo.yaml b/data/api/client-server/content-repo.yaml index 328ae1c4..e12c5612 100644 --- a/data/api/client-server/content-repo.yaml +++ b/data/api/client-server/content-repo.yaml @@ -308,6 +308,17 @@ paths: content repository can and should impose a maximum value for this parameter. The content repository may also choose to respond before the timeout. + - in: query + type: boolean + name: allow_redirect + x-addedInMatrixVersion: "1.7" + x-example: false + required: false + default: false + description: | + Indicates to the server that it may return a 307 or 308 redirect response that points + at the relevant media content. When not explicitly set to true the server must return + the media content itself. responses: 200: description: "The content that was previously uploaded." @@ -323,6 +334,18 @@ paths: type: file # This is a workaround for us not being able to say the response is required. description: "**Required.** The bytes for the uploaded file." + 307: + description: "A redirect to the thumbnail of the requested content." + headers: + Location: + description: "The URL of the thumbnail content." + type: "string" + 308: + description: "A redirect to the thumbnail of the requested content." + headers: + Location: + description: "The URL of the thumbnail content." + type: "string" 429: description: This request was rate-limited. schema: @@ -404,6 +427,17 @@ paths: content repository can and should impose a maximum value for this parameter. The content repository may also choose to respond before the timeout. + - in: query + type: boolean + name: allow_redirect + x-addedInMatrixVersion: "1.7" + x-example: false + required: false + default: false + description: | + Indicates to the server that it may return a 307 or 308 redirect response that points + at the relevant media content. When not explicitly set to true the server must return + the media content itself. responses: 200: description: "The content that was previously uploaded." @@ -420,6 +454,18 @@ paths: type: file # This is a workaround for us not being able to say the response is required. description: "**Required.** The bytes for the uploaded file." + 307: + description: "A redirect to the thumbnail of the requested content." + headers: + Location: + description: "The URL of the thumbnail content." + type: "string" + 308: + description: "A redirect to the thumbnail of the requested content." + headers: + Location: + description: "The URL of the thumbnail content." + type: "string" 429: description: This request was rate-limited. schema: @@ -518,6 +564,17 @@ paths: content repository can and should impose a maximum value for this parameter. The content repository may also choose to respond before the timeout. + - in: query + type: boolean + name: allow_redirect + x-addedInMatrixVersion: "1.7" + x-example: false + required: false + default: false + description: | + Indicates to the server that it may return a 307 or 308 redirect response that points + at the relevant media content. When not explicitly set to true the server must return + the media content itself. responses: 200: description: "A thumbnail of the requested content." @@ -530,6 +587,18 @@ paths: type: file # This is a workaround for us not being able to say the response is required. description: "**Required.** The bytes for the thumbnail." + 307: + description: "A redirect to the thumbnail of the requested content." + headers: + Location: + description: "The URL of the thumbnail content." + type: "string" + 308: + description: "A redirect to the thumbnail of the requested content." + headers: + Location: + description: "The URL of the thumbnail content." + type: "string" 400: description: |- The request does not make sense to the server, or the server cannot thumbnail From cad4f78711c51a4b66fdaaf540ecb0802f3fd99b Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Fri, 19 May 2023 10:29:31 +0100 Subject: [PATCH 14/59] Update 1473.clarification fix formatting --- changelogs/server_server/newsfragments/1473.clarification | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changelogs/server_server/newsfragments/1473.clarification b/changelogs/server_server/newsfragments/1473.clarification index c5cfb948..d67095d8 100644 --- a/changelogs/server_server/newsfragments/1473.clarification +++ b/changelogs/server_server/newsfragments/1473.clarification @@ -1 +1 @@ -* Remove leftover `{key_id}` from `/_matrix/key/v2/server/` +Remove leftover `{key_id}` from `/_matrix/key/v2/server/`. From 6496d374d267e30eac1430d588cc71a205524bb2 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 22 May 2023 22:38:26 -0600 Subject: [PATCH 15/59] Specify MSC3882: Using an existing session to log in another (#1530) * Specify MSC3882: Using an existing session to log in another MSC: https://github.com/matrix-org/matrix-spec-proposals/pull/3882 * Changelog entries * Update data/api/client-server/login.yaml Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> * Link to endpoint * Copy/paste `auth` dict definition * Move get_token API to the correct version prefix (v1, not v3) * Apply suggestions from code review Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --------- Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- .../client_server/newsfragments/1530.feature | 1 + .../client_server/newsfragments/1530.new | 1 + content/client-server-api/_index.md | 6 + data/api/client-server/login.yaml | 14 ++- data/api/client-server/login_token.yaml | 118 ++++++++++++++++++ 5 files changed, 139 insertions(+), 1 deletion(-) create mode 100644 changelogs/client_server/newsfragments/1530.feature create mode 100644 changelogs/client_server/newsfragments/1530.new create mode 100644 data/api/client-server/login_token.yaml diff --git a/changelogs/client_server/newsfragments/1530.feature b/changelogs/client_server/newsfragments/1530.feature new file mode 100644 index 00000000..90121439 --- /dev/null +++ b/changelogs/client_server/newsfragments/1530.feature @@ -0,0 +1 @@ +Add an ability to use an existing session to log in another, as per [MSC3882](https://github.com/matrix-org/matrix-spec-proposals/pull/3882). \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1530.new b/changelogs/client_server/newsfragments/1530.new new file mode 100644 index 00000000..ffe9abd9 --- /dev/null +++ b/changelogs/client_server/newsfragments/1530.new @@ -0,0 +1 @@ +[`POST /_matrix/client/v1/login/get_token`](/client-server-api/#post_matrixclientv1loginget_token). \ No newline at end of file diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 798835a0..8ebe8f71 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -1176,8 +1176,14 @@ client supports it, the client should redirect the user to the is complete, the client will need to submit a `/login` request matching `m.login.token`. +{{< added-in v="1.7" >}} Already-authenticated clients can additionally generate +a token for their user ID if supported by the homeserver using +[`POST /login/get_token`](/client-server-api/#post_matrixclientv1loginget_token). + {{% http-api spec="client-server" api="login" %}} +{{% http-api spec="client-server" api="login_token" %}} + {{% http-api spec="client-server" api="refresh" %}} {{% http-api spec="client-server" api="logout" %}} diff --git a/data/api/client-server/login.yaml b/data/api/client-server/login.yaml index 7c33d1a4..b62cf2d2 100644 --- a/data/api/client-server/login.yaml +++ b/data/api/client-server/login.yaml @@ -42,7 +42,8 @@ paths: examples: application/json: { "flows": [ - {"type": "m.login.password"} + {"type": "m.login.password"}, + {"type": "m.login.token", "get_login_token": true} ] } schema: @@ -54,12 +55,23 @@ paths: items: type: object title: LoginFlow + required: ['type'] properties: type: description: |- The login type. This is supplied as the `type` when logging in. type: string + get_login_token: + type: boolean + x-addedInMatrixVersion: "1.7" + description: |- + If `type` is `m.login.token`, an optional field to indicate + to the unauthenticated client that the homeserver supports + the [`POST /login/get_token`](/client-server-api/#post_matrixclientv1loginget_token) + endpoint. Note that supporting the endpoint does not + necessarily indicate that the user attempting to log in will + be able to generate such a token. 429: description: This request was rate-limited. schema: diff --git a/data/api/client-server/login_token.yaml b/data/api/client-server/login_token.yaml new file mode 100644 index 00000000..be0dca8b --- /dev/null +++ b/data/api/client-server/login_token.yaml @@ -0,0 +1,118 @@ +# Copyright 2023 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# 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. +swagger: '2.0' +info: + title: "Matrix Client-Server Registration and Login API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/v1 +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/login/get_token": + post: + summary: Optional endpoint to generate a single-use, time-limited, `m.login.token` token. + description: |- + Optional endpoint - the server is not required to implement this endpoint if it does not + intend to use or support this functionality. + + This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api). + + An already-authenticated client can call this endpoint to generate a single-use, time-limited, + token for an unauthenticated client to log in with, becoming logged in as the same user which + called this endpoint. The unauthenticated client uses the generated token in a `m.login.token` + login flow with the homeserver. + + Clients, both authenticated and unauthenticated, might wish to hide user interface which exposes + this feature if the server is not offering it. Authenticated clients can check for support on + a per-user basis with the `m.get_login_token` [capability](/client-server-api/#capabilities-negotiation), + while unauthenticated clients can detect server support by looking for an `m.login.token` login + flow with `get_login_token: true` on [`GET /login`](/client-server-api/#post_matrixclientv3login). + + In v1.7 of the specification, transmission of the generated token to an unauthenticated client is + left as an implementation detail. Future MSCs such as [MSC3906](https://github.com/matrix-org/matrix-spec-proposals/pull/3906) + might standarise a way to transmit the token between clients. + + The generated token MUST only be valid for a single login, enforced by the server. Clients which + intend to log in multiple devices must generate a token for each. + + With other User-Interactive Authentication (UIA)-supporting endpoints, servers sometimes do not re-prompt + for verification if the session recently passed UIA. For this endpoint, servers should always re-prompt + the user for verification to ensure explicit consent is gained for each additional client. + + Servers are encouraged to apply stricter than normal rate limiting to this endpoint, such as maximum + of 1 request per minute. + operationId: generateLoginToken + x-addedInMatrixVersion: "1.7" + security: + - accessToken: [] + parameters: + - in: body + name: body + required: true + schema: + type: object + properties: + auth: + description: |- + Additional authentication information for the user-interactive authentication API. + allOf: + - $ref: "definitions/auth_data.yaml" + responses: + 200: + description: The login token an unauthenticated client can use to log in as the requesting user. + examples: + application/json: { + "login_token": "", + "expires_in_ms": 120000 + } + schema: + type: object + required: ["login_token", "expires_in_ms"] + properties: + login_token: + type: string + description: The login token for the `m.login.token` login flow. + expires_in_ms: + type: integer + description: |- + The time remaining in milliseconds until the homeserver will no longer accept the token. `120000` + (2 minutes) is recommended as a default. + 400: + description: |- + The request was malformed, or the user does not have an ability to generate tokens for their devices, + as implied by the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api). + + Clients should verify whether the user has an ability to call this endpoint with the `m.get_login_token` + [capability](/client-server-api/#capabilities-negotiation). + schema: + "$ref": "definitions/errors/error.yaml" + 401: + description: |- + The homeserver requires additional authentication information. + schema: + "$ref": "definitions/auth_response.yaml" + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + tags: + - Session management From f564c07e600fa0f8ae63096387ed9cbc2066a022 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Tue, 23 May 2023 17:18:16 +0200 Subject: [PATCH 16/59] Fixes and clarifications around m.reaction (#1531) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- changelogs/client_server/newsfragments/1531.feature | 1 + content/client-server-api/modules/event_annotations.md | 6 ++++++ content/client-server-api/modules/push.md | 2 +- content/client-server-api/modules/receipts.md | 6 ------ data/event-schemas/schema/m.reaction.yaml | 8 +++++--- 5 files changed, 13 insertions(+), 10 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1531.feature diff --git a/changelogs/client_server/newsfragments/1531.feature b/changelogs/client_server/newsfragments/1531.feature new file mode 100644 index 00000000..a59c2177 --- /dev/null +++ b/changelogs/client_server/newsfragments/1531.feature @@ -0,0 +1 @@ +Add `m.annotation` relations (reactions), as per [MSC2677](https://github.com/matrix-org/matrix-spec-proposals/pull/2677). diff --git a/content/client-server-api/modules/event_annotations.md b/content/client-server-api/modules/event_annotations.md index 8aeff40f..661d8001 100644 --- a/content/client-server-api/modules/event_annotations.md +++ b/content/client-server-api/modules/event_annotations.md @@ -71,6 +71,12 @@ change their reaction, the original reaction should be redacted and a new one sent in its place. {{% /boxes/note %}} +{{% boxes/note %}} +The `key` field in `m.reaction` can be any string so clients must take care to +render long reactions in a sensible manner. For example, clients can elide +overly-long reactions. +{{% /boxes/note %}} + #### Server behaviour ##### Avoiding duplicate annotations diff --git a/content/client-server-api/modules/push.md b/content/client-server-api/modules/push.md index ad2c544b..d1855f58 100644 --- a/content/client-server-api/modules/push.md +++ b/content/client-server-api/modules/push.md @@ -700,7 +700,7 @@ Definition: {{% added-in v="1.7" %}} -Matches any event whose type is `m.room.reaction`. This suppresses notifications for [`m.reaction`](#mreaction) events. +Matches any event whose type is `m.reaction`. This suppresses notifications for [`m.reaction`](#mreaction) events. Definition: diff --git a/content/client-server-api/modules/receipts.md b/content/client-server-api/modules/receipts.md index 1b1af61a..8cd4e9f6 100644 --- a/content/client-server-api/modules/receipts.md +++ b/content/client-server-api/modules/receipts.md @@ -153,12 +153,6 @@ relationships and solid lines showing topological ordering. ![threaded-dag](/diagrams/threaded-dag.png) -{{% boxes/note %}} -`m.reaction` relationships are not currently specified, but are shown here for -their conceptual place in a threaded DAG. They are currently proposed as -[MSC2677](https://github.com/matrix-org/matrix-spec-proposals/pull/2677). -{{% /boxes/note %}} - This DAG can be represented as 3 threaded timelines, with `A` and `B` being thread roots: diff --git a/data/event-schemas/schema/m.reaction.yaml b/data/event-schemas/schema/m.reaction.yaml index 4d8ce43b..6d369c5f 100644 --- a/data/event-schemas/schema/m.reaction.yaml +++ b/data/event-schemas/schema/m.reaction.yaml @@ -30,8 +30,10 @@ properties: key: type: string description: |- - An emoji representing the reaction being made. Should include the - unicode emoji presentation selector (`\uFE0F`) for codepoints - which allow it (see the [emoji variation sequences + The reaction being made, usually an emoji. + + If this is an emoji, it should include the unicode emoji + presentation selector (`\uFE0F`) for codepoints which allow it + (see the [emoji variation sequences list](https://www.unicode.org/Public/UCD/latest/ucd/emoji/emoji-variation-sequences.txt)). example: "👍" From 9dd9639dd7c7dfb4712d389c4bcd14de9fa74840 Mon Sep 17 00:00:00 2001 From: Tulir Asokan Date: Tue, 23 May 2023 20:36:37 +0300 Subject: [PATCH 17/59] Add spec for MSC2659: application service ping endpoint (#1516) --- .../newsfragments/1516.feature | 1 + .../newsfragments/1516.new | 1 + content/application-service-api.md | 57 +++++++ data/api/application-service/ping.yaml | 63 ++++++++ data/api/client-server/appservice_ping.yaml | 150 ++++++++++++++++++ 5 files changed, 272 insertions(+) create mode 100644 changelogs/application_service/newsfragments/1516.feature create mode 100644 changelogs/application_service/newsfragments/1516.new create mode 100644 data/api/application-service/ping.yaml create mode 100644 data/api/client-server/appservice_ping.yaml diff --git a/changelogs/application_service/newsfragments/1516.feature b/changelogs/application_service/newsfragments/1516.feature new file mode 100644 index 00000000..ee222fb0 --- /dev/null +++ b/changelogs/application_service/newsfragments/1516.feature @@ -0,0 +1 @@ +Add homeserver->appservice ping mechanism, as per [MSC2659](https://github.com/matrix-org/matrix-spec-proposals/pull/2659). Contributed by @tulir at @beeper. diff --git a/changelogs/application_service/newsfragments/1516.new b/changelogs/application_service/newsfragments/1516.new new file mode 100644 index 00000000..c6244075 --- /dev/null +++ b/changelogs/application_service/newsfragments/1516.new @@ -0,0 +1 @@ +Add `POST /_matrix/app/v1/ping` and `POST /_matrix/client/v1/appservice/{appserviceId}/ping` endpoints as per [MSC2659](https://github.com/matrix-org/matrix-spec-proposals/pull/2659). diff --git a/content/application-service-api.md b/content/application-service-api.md index 7a14869a..f3db06cf 100644 --- a/content/application-service-api.md +++ b/content/application-service-api.md @@ -207,6 +207,54 @@ processed the events. {{% http-api spec="application-service" api="transactions" %}} +#### Pinging + +{{% added-in v="1.7" %}} + +The application service API includes a ping mechanism to allow +appservices to ensure that the homeserver can reach the appservice. +Appservices may use this mechanism to detect misconfigurations and +report them appropriately. + +Implementations using this mechanism should take care to not fail +entirely in the event of temporary issues, e.g. gracefully handling +cases where the appservice is started before the homeserver. + +The mechanism works as follows (note: the human-readable `error` fields +have been omitted for brevity): + +**Typical** + +``` +AS ---> HS : /_matrix/client/v1/appservice/{appserviceId}/ping {"transaction_id": "meow"} + HS ---> AS : /_matrix/app/v1/ping {"transaction_id": "meow"} + HS <--- AS : 200 OK {} +AS <--- HS : 200 OK {"duration_ms": 123} +``` + +**Incorrect `hs_token`** + +``` +AS ---> HS : /_matrix/client/v1/appservice/{appserviceId}/ping {"transaction_id": "meow"} + HS ---> AS : /_matrix/app/v1/ping {"transaction_id": "meow"} + HS <--- AS : 403 Forbidden {"errcode": "M_FORBIDDEN"} +AS <--- HS : 502 Bad Gateway {"errcode": "M_BAD_STATUS", "status": 403, "body": "{\"errcode\": \"M_FORBIDDEN\"}"} +``` + +**Can't connect to appservice** + +``` +AS ---> HS : /_matrix/client/v1/appservice/{appserviceId}/ping {"transaction_id": "meow"} + HS -/-> AS : /_matrix/app/v1/ping {"transaction_id": "meow"} +AS <--- HS : 502 Bad Gateway {"errcode": "M_CONNECTION_FAILED"} +``` + +The `/_matrix/app/v1/ping` endpoint is described here. The +[`/_matrix/client/v1/appservice/{appserviceId}/ping`](#post_matrixclientv1appserviceappserviceidping) +endpoint is under the Client-Server API extensions section below. + +{{% http-api spec="application-service" api="ping" %}} + #### Querying The application service API includes two querying APIs: for room aliases @@ -388,6 +436,15 @@ an application service-defined namespace will receive the same `M_EXCLUSIVE` error code, but only if the application service has defined the namespace as `exclusive`. +#### Pinging + +{{% added-in v="1.7" %}} + +This is the client-server API companion endpoint for the +[pinging](#pinging) mechanism described above. + +{{% http-api spec="client-server" api="appservice_ping" %}} + #### Using `/sync` and `/events` Application services wishing to use `/sync` or `/events` from the diff --git a/data/api/application-service/ping.yaml b/data/api/application-service/ping.yaml new file mode 100644 index 00000000..18682f11 --- /dev/null +++ b/data/api/application-service/ping.yaml @@ -0,0 +1,63 @@ +# Copyright 2023 Tulir Asokan +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# 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. +swagger: '2.0' +info: + title: "Matrix Application Service API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/app/v1 +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/ping": + post: + x-addedInMatrixVersion: "1.7" + summary: Ping the application service + description: |- + This API is called by the homeserver to ensure that the connection works + and the `hs_token` the homeserver has is correct. + + Currently this is only called by the homeserver as a direct result of + the application service calling + [`POST /_matrix/client/v1/appservice/{appserviceId}/ping`](#post_matrixclientv1appserviceappserviceidping). + operationId: ping + security: + - homeserverAccessToken: [] + parameters: + - in: body + name: body + description: Ping body with optional transaction ID. + schema: + type: object + example: { + "transaction_id": "mautrix-go_1683636478256400935_123" + } + properties: + transaction_id: + type: string + description: |- + A transaction ID for the ping, copied directly from the + `POST /_matrix/client/v1/appservice/{appserviceId}/ping` call. + responses: + 200: + description: The provided `hs_token` is valid and the ping request was successful. + examples: + application/json: {} + schema: + type: object diff --git a/data/api/client-server/appservice_ping.yaml b/data/api/client-server/appservice_ping.yaml new file mode 100644 index 00000000..4075e901 --- /dev/null +++ b/data/api/client-server/appservice_ping.yaml @@ -0,0 +1,150 @@ +# Copyright 2023 Tulir Asokan +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# 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. +swagger: '2.0' +info: + title: "Matrix Client-Server Application Service Ping API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/v1 +consumes: + - application/json +produces: + - application/json +securityDefinitions: + # Note: this is the same access_token definition used elsewhere in the client + # server API, however this expects an access token for an application service. + $ref: definitions/security.yaml +paths: + "/appservice/{appserviceId}/ping": + post: + x-addedInMatrixVersion: "1.7" + summary: |- + Ask the homeserver to ping the application service to ensure the connection works. + description: |- + This API asks the homeserver to call the + [`/_matrix/app/v1/ping`](#post_matrixappv1ping) endpoint on the + application service to ensure that the homeserver can communicate + with the application service. + + This API requires the use of an application service access token (`as_token`) + instead of a typical client's access token. This API cannot be invoked by + users who are not identified as application services. Additionally, the + appservice ID in the path must be the same as the appservice whose `as_token` + is being used. + operationId: pingAppservice + parameters: + - in: path + type: string + name: appserviceId + description: |- + The appservice ID of the appservice to ping. This must be the same + as the appservice whose `as_token` is being used to authenticate the + request. + required: true + x-example: "telegram" + - in: body + name: body + required: true + schema: + type: object + properties: + transaction_id: + type: string + description: |- + An optional transaction ID that is passed through to the `/_matrix/app/v1/ping` call. + example: "mautrix-go_1683636478256400935_123" + security: + # again, this is the appservice's token - not a typical client's + - accessToken: [] + responses: + 200: + description: The ping was successful. + schema: + type: object + properties: + duration_ms: + type: integer + description: |- + The duration in milliseconds that the + [`/_matrix/app/v1/ping`](#post_matrixappv1ping) + request took from the homeserver's point of view. + examples: + application/json: {"duration_ms": 123} + 400: + description: The application service doesn't have a URL configured. The errcode is `M_URL_NOT_SET`. + schema: + $ref: "definitions/errors/error.yaml" + examples: + application/json: { + "errcode": "M_URL_NOT_SET", + "error": "Application service doesn't have a URL configured" + } + 403: + description: The access token used to authenticate the request doesn't belong to an appservice, or belongs to a different appservice than the one in the path. The errcode is `M_FORBIDDEN`. + schema: + $ref: "definitions/errors/error.yaml" + examples: + application/json: { + "errcode": "M_FORBIDDEN", + "error": "Provided access token is not the appservice's as_token" + } + 502: + description: |- + The application service returned a bad status, or the connection failed. + The errcode is `M_BAD_STATUS` or `M_CONNECTION_FAILED`. + + For bad statuses, the response may include `status` and `body` + fields containing the HTTP status code and response body text + respectively to aid with debugging. + schema: + type: object + title: Error + description: A Matrix-level Error + properties: + errcode: + type: string + description: An error code. + enum: [M_BAD_STATUS, M_CONNECTION_FAILED] + error: + type: string + description: A human-readable error message. + example: Ping returned status 401 + status: + type: integer + description: The HTTP status code returned by the appservice. + example: 401 + body: + type: string + description: The HTTP response body returned by the appservice. + example: "{\"errcode\": \"M_UNKNOWN_TOKEN\"}" + required: ["errcode"] + examples: + application/json: { + "errcode": "M_BAD_STATUS", + "error": "Ping returned status 401", + "status": 401, + "body": "{\"errcode\": \"M_UNKNOWN_TOKEN\"}" + } + 504: + description: The connection to the application service timed out. The errcode is `M_CONNECTION_TIMEOUT`. + schema: + $ref: "definitions/errors/error.yaml" + examples: + application/json: { + "errcode": "M_CONNECTION_TIMEOUT", + "error": "Connection to application service timed out" + } From 17ebdf7c863b96db8c6ebe3eb075494ac3fc4064 Mon Sep 17 00:00:00 2001 From: Michael Kohler Date: Tue, 23 May 2023 20:28:46 +0200 Subject: [PATCH 18/59] Fix ASCII art alignment (#1534) * Fix ASCII art alignment Signed-off-by: Michael Kohler Fixes #1430 * Add changelog --------- Co-authored-by: Travis Ralston --- changelogs/internal/newsfragments/1534.clarification | 1 + content/_index.md | 4 ++-- 2 files changed, 3 insertions(+), 2 deletions(-) create mode 100644 changelogs/internal/newsfragments/1534.clarification diff --git a/changelogs/internal/newsfragments/1534.clarification b/changelogs/internal/newsfragments/1534.clarification new file mode 100644 index 00000000..ca5f3aea --- /dev/null +++ b/changelogs/internal/newsfragments/1534.clarification @@ -0,0 +1 @@ +Fix various typos throughout the specification. \ No newline at end of file diff --git a/content/_index.md b/content/_index.md index 6396e4a3..69832f2e 100644 --- a/content/_index.md +++ b/content/_index.md @@ -357,8 +357,8 @@ servers that are in the room that can be used to join via. HTTP GET #matrix:example.org !aaabaa:matrix.org - | ^ - | | + | ^ + | | _______V____________________|____ | example.org | | Mappings: | From 4fd9f399663257747b65fc8a3b9ecc488a670613 Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 23 May 2023 14:29:35 -0400 Subject: [PATCH 19/59] Add spec for MSC2746 (#1511) * Change version field to a string And add the notes on how the version field works. * Add spec requiring tracks to be within streams. * Put streams spec in its own section * Add 'invitee' field * Add party_id * Remember how JSON works * Add m.call.select_answer * Update examples * Add select_answer to call flow example diagram * Add m.call.reject * Make party_id required in other events * Add possible ways for client to handle an invite * Convert hangup & reject events to YAML So we can have a bulleted list in the description for the values of 'reason'. * Add new reason codes to hangup & reject * Add m.call.negotiate * Add other sections * Revert changes to package lock * Typos * Fix type of other version fields, fix anchor. * Add newsfragment * Fix reason in hangup/reject * Change tense Co-authored-by: Hubert Chathi * Tense, typos & grammar Co-authored-by: Hubert Chathi * Linkify Co-authored-by: Hubert Chathi * Remove unnecessary parts from link Co-authored-by: Hubert Chathi * Capitalise Co-authored-by: Hubert Chathi * Fix hangup reasons * Clarify who can answer Co-authored-by: Hubert Chathi * Linkify Co-authored-by: Hubert Chathi * Remove reference to 'this MSC'. * Move common VoIP fields into a call event type. * Move common voip events to the content, not the actual event * Remove reason from reject event I confused myself, but it's not in the MSC and it shouldn't be. * Failure to YAML * Fix number of room members allowed when sending voip events. Co-authored-by: Hubert Chathi * Add 'added in' version Co-authored-by: Hubert Chathi * Another added-in Co-authored-by: Hubert Chathi * Add missing comma --------- Co-authored-by: Hubert Chathi Co-authored-by: Travis Ralston --- .../client_server/newsfragments/1511.feature | 1 + .../client-server-api/modules/voip_events.md | 159 +++++++++++++++++- .../event-schemas/examples/m.call.answer.yaml | 3 +- .../examples/m.call.candidates.yaml | 3 +- .../event-schemas/examples/m.call.hangup.yaml | 6 +- .../event-schemas/examples/m.call.invite.yaml | 3 +- .../examples/m.call.negotiate.yaml | 14 ++ .../event-schemas/examples/m.call.reject.yaml | 9 + .../examples/m.call.select_answer.yaml | 10 ++ .../schema/core-event-schema/call_event.yaml | 25 +++ data/event-schemas/schema/m.call.answer.yaml | 13 +- .../schema/m.call.candidates.yaml | 13 +- data/event-schemas/schema/m.call.hangup.yaml | 89 ++++++---- data/event-schemas/schema/m.call.invite.yaml | 18 +- .../schema/m.call.negotiate.yaml | 74 ++++++++ data/event-schemas/schema/m.call.reject.yaml | 28 +++ .../schema/m.call.select_answer.yaml | 27 +++ 17 files changed, 426 insertions(+), 69 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1511.feature create mode 100644 data/event-schemas/examples/m.call.negotiate.yaml create mode 100644 data/event-schemas/examples/m.call.reject.yaml create mode 100644 data/event-schemas/examples/m.call.select_answer.yaml create mode 100644 data/event-schemas/schema/core-event-schema/call_event.yaml create mode 100644 data/event-schemas/schema/m.call.negotiate.yaml create mode 100644 data/event-schemas/schema/m.call.reject.yaml create mode 100644 data/event-schemas/schema/m.call.select_answer.yaml diff --git a/changelogs/client_server/newsfragments/1511.feature b/changelogs/client_server/newsfragments/1511.feature new file mode 100644 index 00000000..d3526b8e --- /dev/null +++ b/changelogs/client_server/newsfragments/1511.feature @@ -0,0 +1 @@ +Update VoIP spec for [MSC2746](https://github.com/matrix-org/matrix-spec-proposals/pull/2746). diff --git a/content/client-server-api/modules/voip_events.md b/content/client-server-api/modules/voip_events.md index 90471cae..75cc7757 100644 --- a/content/client-server-api/modules/voip_events.md +++ b/content/client-server-api/modules/voip_events.md @@ -6,11 +6,128 @@ This module outlines how two users in a room can set up a Voice over IP WebRTC 1.0 standard. Call signalling is achieved by sending [message events](#events) to the room. In this version of the spec, only two-party communication is supported (e.g. between two peers, or between a peer -and a multi-point conferencing unit). This means that clients MUST only -send call events to rooms with exactly two participants. +and a multi-point conferencing unit). Calls can take place in rooms with +multiple members, but only two devices can take part in the call. + +All VoIP events have a `version` field. This is used to determine whether +devices support this new version of the protocol. For example, clients can use +this field to know whether to expect an `m.call.select_answer` event from their +opponent. If clients see events with `version` other than `0` or `"1"` +(including, for example, the numeric value `1`), they should treat these the +same as if they had `version` == `"1"`. + +Note that this implies any and all future versions of VoIP events should be +backwards-compatible. If it does become necessary to introduce a non +backwards-compatible VoIP spec, the intention would be for it to simply use a +separate set of event types. + +#### Party Identifiers +Whenever a client first participates in a new call, it generates a `party_id` for itself to use for the +duration of the call. This needs to be long enough that the chance of a collision between multiple devices +both generating an answer at the same time generating the same party ID is vanishingly small: 8 uppercase + +lowercase alphanumeric characters is recommended. Parties in the call are identified by the tuple of +`(user_id, party_id)`. + +The client adds a `party_id` field containing this ID to the top-level of the content of all VoIP events +it sends on the call, including `m.call.invite`. Clients use this to identify remote echo of their own +events: since a user may call themselves, they cannot simply ignore events from their own user. This +field also identifies different answers sent by different clients to an invite, and matches `m.call.candidates` +events to their respective answer/invite. + +A client implementation may choose to use the device ID used in end-to-end cryptography for this purpose, +or it may choose, for example, to use a different one for each call to avoid leaking information on which +devices were used in a call (in an unencrypted room) or if a single device (ie. access token) were used to +send signalling for more than one call party. + +A grammar for `party_id` is defined [below](#grammar-for-voip-ids). + +#### Politeness +In line with [WebRTC perfect negotiation](https://w3c.github.io/webrtc-pc/#perfect-negotiation-example) +there are rules to establish which party is polite in the process of renegotiation. The callee is +always the polite party. In a glare situation, the politenes of a party is therefore determined by +whether the inbound or outbound call is used: if a client discards its outbound call in favour of +an inbound call, it becomes the polite party. + +#### Call Event Liveness +`m.call.invite` contains a `lifetime` field that indicates how long the offer is valid for. When +a client receives an invite, it should use the event's `age` field in the sync response plus the +time since it received the event from the homeserver to determine whether the invite is still valid. +The use of the `age` field ensures that incorrect clocks on client devices don't break calls. + +If the invite is still valid *and will remain valid for long enough for the user to accept the call*, +it should signal an incoming call. The amount of time allowed for the user to accept the call may +vary between clients. For example, it may be longer on a locked mobile device than on an unlocked +desktop device. + +The client should only signal an incoming call in a given room once it has completed processing the +entire sync response and, for encrypted rooms, attempted to decrypt all encrypted events in the +sync response for that room. This ensures that if the sync response contains subsequent events that +indicate the call has been hung up, rejected, or answered elsewhere, the client does not signal it. + +If on startup, after processing locally stored events, the client determines that there is an invite +that is still valid, it should still signal it but only after it has completed a sync from the homeserver. + +The minimal recommended lifetime is 90 seconds - this should give the user enough time to actually pick +up the call. + +#### ICE Candidate Batching +Clients should aim to send a small number of candidate events, with guidelines: + * ICE candidates which can be discovered immediately or almost immediately in the invite/answer + event itself (eg. host candidates). If server reflexive or relay candidates can be gathered in + a sufficiently short period of time, these should be sent here too. A delay of around 200ms is + suggested as a starting point. + * The client should then allow some time for further candidates to be gathered in order to batch them, + rather than sending each candidate as it arrives. A starting point of 2 seconds after sending the + invite or 500ms after sending the answer is suggested as a starting point (since a delay is natural + anyway after the invite whilst the client waits for the user to accept it). + +#### End-of-candidates +An ICE candidate whose value is the empty string means that no more ICE candidates will +be sent. Clients must send such a candidate in an `m.call.candidates` message. +The WebRTC spec requires browsers to generate such a candidate, however note that at time of writing, +not all browsers do (Chrome does not, but does generate an `icegatheringstatechange` event). The +client should send any remaining candidates once candidate generation finishes, ignoring timeouts above. +This allows bridges to batch the candidates together when bridging to protocols that don't support +trickle ICE. + +#### DTMF +Matrix clients can send DTMF as specified by WebRTC. The WebRTC standard as of August +2020 does not support receiving DTMF but a Matrix client can receive and interpret the DTMF sent +in the RTP payload. + +#### Grammar for VoIP IDs +`call_id`s and `party_id` are explicitly defined to be between 1 and 255 characters long, consisting +of the characters `[0-9a-zA-Z._~-]`. + +(Note that this matches the grammar of 'opaque IDs' from +[MSC1597](https://github.com/matrix-org/matrix-spec-proposals/blob/rav/proposals/id_grammar/proposals/1597-id-grammar.md#opaque-ids), +and that of the `id` property of the + [`m.login.sso` flow schema](#definition-mloginsso-flow-schema).) + +#### Behaviour on Room Leave +If the client sees the user it is in a call with leave the room, the client should treat this +as a hangup event for any calls that are in progress. No specific requirement is given for the +situation where a client has sent an invite and the invitee leaves the room, but the client may +wish to treat it as a rejection if there are no more users in the room who could answer the call +(eg. the user is now alone or the `invitee` field was set on the invite). + +The same behaviour applies when a client is looking at historic calls. + +#### Supported Codecs +The Matrix spec does not mandate particular audio or video codecs, but instead defers to the +WebRTC spec. A compliant Matrix VoIP client will behave in the same way as a supported 'browser' +in terms of what codecs it supports and what variants thereof. The latest WebRTC specification +applies, so clients should keep up to date with new versions of the WebRTC specification whether +or not there have been any changes to the Matrix spec. #### Events +##### Common Fields + +{{% event-fields event_type="call_event" %}} + +##### Events + {{% event-group group_name="m.call" %}} #### Client behaviour @@ -25,6 +142,7 @@ A call is set up with message events exchanged as follows: [..candidates..] --------> [Answers call] <--------------- m.call.answer + m.call.select_answer -----------> [Call is active and ongoing] <--------------- m.call.hangup ``` @@ -42,6 +160,43 @@ Or a rejected call: Calls are negotiated according to the WebRTC specification. +In response to an incoming invite, a client may do one of several things: + * Attempt to accept the call by sending an `m.call.answer`. + * Actively reject the call everywhere: send an `m.call.reject` as per above, which will stop the call from + ringing on all the user's devices and the caller's client will inform them that the user has + rejected their call. + * Ignore the call: send no events, but stop alerting the user about the call. The user's other + devices will continue to ring, and the caller's device will continue to indicate that the call + is ringing, and will time the call out in the normal way if no other device responds. + +##### Streams + +Clients are expected to send one stream with one track of kind `audio` (creating a +voice call). They can optionally send a second track in the same stream of kind +`video` (creating a video call). + +Clients implementing this specification use the first stream and will ignore +any streamless tracks. Note that in the JavaScript WebRTC API, this means +`addTrack()` must be passed two parameters: a track and a stream, not just a +track, and in a video call the stream must be the same for both audio and video +track. + +A client may send other streams and tracks but the behaviour of the other party +with respect to presenting such streams and tracks is undefined. + +##### Invitees +The `invitee` field should be added whenever the call is intended for one +specific user, and should be set to the Matrix user ID of that user. Invites +without an `invitee` field are defined to be intended for any member of the +room other than the sender of the event. + +Clients should consider an incoming call if they see a non-expired invite event where the `invitee` field is either +absent or equal to their user's Matrix ID, however they should evaluate whether or not to ring based on their +user's trust relationship with the callers and/or where the call was placed. As a starting point, it is +suggested that clients ignore call invites from users in public rooms. It is strongly recommended that +when clients do not ring for an incoming call invite, they still display the call invite in the room and +annotate that it was ignored. + ##### Glare "Glare" is a problem which occurs when two users call each other at diff --git a/data/event-schemas/examples/m.call.answer.yaml b/data/event-schemas/examples/m.call.answer.yaml index aaa4da71..78b48878 100644 --- a/data/event-schemas/examples/m.call.answer.yaml +++ b/data/event-schemas/examples/m.call.answer.yaml @@ -2,7 +2,8 @@ "$ref": "core/room_event.json", "type": "m.call.answer", "content": { - "version" : 0, + "version" : "1", + "party_id": "67890", "call_id": "12345", "answer": { "type" : "answer", diff --git a/data/event-schemas/examples/m.call.candidates.yaml b/data/event-schemas/examples/m.call.candidates.yaml index 8f1f807a..23d0a178 100644 --- a/data/event-schemas/examples/m.call.candidates.yaml +++ b/data/event-schemas/examples/m.call.candidates.yaml @@ -2,7 +2,8 @@ "$ref": "core/room_event.json", "type": "m.call.candidates", "content": { - "version" : 0, + "version" : "1", + "party_id": "67890", "call_id": "12345", "candidates": [ { diff --git a/data/event-schemas/examples/m.call.hangup.yaml b/data/event-schemas/examples/m.call.hangup.yaml index 295f16e4..a505bc36 100644 --- a/data/event-schemas/examples/m.call.hangup.yaml +++ b/data/event-schemas/examples/m.call.hangup.yaml @@ -2,7 +2,9 @@ "$ref": "core/room_event.json", "type": "m.call.hangup", "content": { - "version" : 0, - "call_id": "12345" + "version" : "1", + "party_id": "67890", + "call_id": "12345", + "reason": "user_hangup" } } diff --git a/data/event-schemas/examples/m.call.invite.yaml b/data/event-schemas/examples/m.call.invite.yaml index fa482bd9..45600001 100644 --- a/data/event-schemas/examples/m.call.invite.yaml +++ b/data/event-schemas/examples/m.call.invite.yaml @@ -2,7 +2,8 @@ "$ref": "core/room_event.json", "type": "m.call.invite", "content": { - "version" : 0, + "version" : "1", + "party_id": "67890", "call_id": "12345", "lifetime": 60000, "offer": { diff --git a/data/event-schemas/examples/m.call.negotiate.yaml b/data/event-schemas/examples/m.call.negotiate.yaml new file mode 100644 index 00000000..f4ad8587 --- /dev/null +++ b/data/event-schemas/examples/m.call.negotiate.yaml @@ -0,0 +1,14 @@ +{ + "$ref": "core/room_event.json", + "type": "m.call.negotiate", + "content": { + "version" : "1", + "party_id": "67890", + "call_id": "12345", + "lifetime": 10000, + "offer": { + "type" : "offer", + "sdp" : "v=0\r\no=- 6584580628695956864 2 IN IP4 127.0.0.1[...]" + } + } +} diff --git a/data/event-schemas/examples/m.call.reject.yaml b/data/event-schemas/examples/m.call.reject.yaml new file mode 100644 index 00000000..2014566c --- /dev/null +++ b/data/event-schemas/examples/m.call.reject.yaml @@ -0,0 +1,9 @@ +{ + "$ref": "core/room_event.json", + "type": "m.call.reject", + "content": { + "version" : "1", + "party_id": "67890", + "call_id": "12345" + } +} diff --git a/data/event-schemas/examples/m.call.select_answer.yaml b/data/event-schemas/examples/m.call.select_answer.yaml new file mode 100644 index 00000000..fbd6ad16 --- /dev/null +++ b/data/event-schemas/examples/m.call.select_answer.yaml @@ -0,0 +1,10 @@ +{ + "$ref": "core/room_event.json", + "type": "m.call.select_answer", + "content": { + "version" : "1", + "call_id": "12345", + "party_id": "67890", + "selected_party_id": "111213" + } +} diff --git a/data/event-schemas/schema/core-event-schema/call_event.yaml b/data/event-schemas/schema/core-event-schema/call_event.yaml new file mode 100644 index 00000000..a8175fc8 --- /dev/null +++ b/data/event-schemas/schema/core-event-schema/call_event.yaml @@ -0,0 +1,25 @@ +description: "The content of all call events shares a set of common fields: those + of room events and some additional VoIP specific fields." +properties: + call_id: + type: string + description: The ID of the call this event relates to. + version: + type: string + description: The version of the VoIP specification this message adheres to. + This specification is version 1. This field is a string such that experimental + implementations can use non-integer versions. This field was an integer + in the previous spec version and implementations must accept an integer + 0. + party_id: + type: string + description: 'This identifies the party that sent this event. A client may + choose to re-use the device ID from end-to-end cryptography for the value + of this field.' + x-addedInMatrixVersion: "1.7" +required: +- call_id +- version +- party_id +title: CallEvent +type: object diff --git a/data/event-schemas/schema/m.call.answer.yaml b/data/event-schemas/schema/m.call.answer.yaml index e84cf6f8..163690be 100644 --- a/data/event-schemas/schema/m.call.answer.yaml +++ b/data/event-schemas/schema/m.call.answer.yaml @@ -7,11 +7,10 @@ "properties": { "content": { "type": "object", + "allOf": [{ + "$ref": "core-event-schema/call_event.yaml" + }], "properties": { - "call_id": { - "type": "string", - "description": "The ID of the call this event relates to." - }, "answer": { "type": "object", "title": "Answer", @@ -28,13 +27,9 @@ } }, "required": ["type", "sdp"] - }, - "version": { - "type": "number", - "description": "The version of the VoIP specification this messages adheres to. This specification is version 0." } }, - "required": ["call_id", "answer", "version"] + "required": ["answer"] }, "type": { "type": "string", diff --git a/data/event-schemas/schema/m.call.candidates.yaml b/data/event-schemas/schema/m.call.candidates.yaml index 7426717c..6aa16229 100644 --- a/data/event-schemas/schema/m.call.candidates.yaml +++ b/data/event-schemas/schema/m.call.candidates.yaml @@ -7,11 +7,10 @@ "properties": { "content": { "type": "object", + "allOf": [{ + "$ref": "core-event-schema/call_event.yaml" + }], "properties": { - "call_id": { - "type": "string", - "description": "The ID of the call this event relates to." - }, "candidates": { "type": "array", "description": "Array of objects describing the candidates.", @@ -34,13 +33,9 @@ }, "required": ["candidate", "sdpMLineIndex", "sdpMid"] } - }, - "version": { - "type": "integer", - "description": "The version of the VoIP specification this messages adheres to. This specification is version 0." } }, - "required": ["call_id", "candidates", "version"] + "required": ["candidates"] }, "type": { "type": "string", diff --git a/data/event-schemas/schema/m.call.hangup.yaml b/data/event-schemas/schema/m.call.hangup.yaml index 116d5af7..65d697ab 100644 --- a/data/event-schemas/schema/m.call.hangup.yaml +++ b/data/event-schemas/schema/m.call.hangup.yaml @@ -1,35 +1,54 @@ -{ - "type": "object", - "description": "Sent by either party to signal their termination of the call. This can be sent either once the call has has been established or before to abort the call.", - "allOf": [{ - "$ref": "core-event-schema/room_event.yaml" - }], - "properties": { - "content": { - "type": "object", - "properties": { - "call_id": { - "type": "string", - "description": "The ID of the call this event relates to." - }, - "version": { - "type": "integer", - "description": "The version of the VoIP specification this message adheres to. This specification is version 0." - }, - "reason": { - "type": "string", - "description": "Optional error reason for the hangup. This should not be provided when the user naturally ends or rejects the call. When there was an error in the call negotiation, this should be `ice_failed` for when ICE negotiation fails or `invite_timeout` for when the other party did not answer in time.", - "enum": [ - "ice_failed", - "invite_timeout" - ] - } - }, - "required": ["call_id", "version"] - }, - "type": { - "type": "string", - "enum": ["m.call.hangup"] - } - } -} +--- +type: object +description: | + Sent by either party to signal their termination of the call. This can + be sent either once the call has has been established or before to abort the call. + + The meanings of the `reason` field are as follows: + * `ice_failed`: ICE negotiation has failed and a media connection could not be established. + * `ice_timeout`: The connection failed after some media was exchanged (as opposed to `ice_failed` + which means no media connection could be established). Note that, in the case of an ICE + renegotiation, a client should be sure to send `ice_timeout` rather than `ice_failed` if media + had previously been received successfully, even if the ICE renegotiation itself failed. + * `invite_timeout`: The other party did not answer in time. + * `user_hangup`: Clients must now send this code when the user chooses to end the call, although + for backwards compatibility with version 0, a clients should treat an absence of the `reason` + field as `user_hangup`. + * `user_media_failed`: The client was unable to start capturing media in such a way that it is unable + to continue the call. + * `user_busy`: The user is busy. Note that this exists primarily for bridging to other networks such + as the PSTN. A Matrix client that receives a call whilst already in a call would not generally reject + the new call unless the user had specifically chosen to do so. + * `unknown_error`: Some other failure occurred that meant the client was unable to continue the call + rather than the user choosing to end it. +allOf: +- "$ref": core-event-schema/room_event.yaml +properties: + content: + type: object + allOf: + - "$ref": core-event-schema/call_event.yaml + properties: + reason: + type: string + description: Reason for the hangup. Note that this was optional in + previous previous versions of the spec, so a missing value should be + treated as `user_hangup`. + x-changedInMatrixVersion: + 1.7: |- + Additional values were added. + enum: + - ice_timeout + - ice_failed + - invite_timeout + - user_hangup + - user_media_failed + - user_busy + - unknown_error + required: + - reason + type: + type: string + enum: + - m.call.hangup + diff --git a/data/event-schemas/schema/m.call.invite.yaml b/data/event-schemas/schema/m.call.invite.yaml index 65796e1e..72020b26 100644 --- a/data/event-schemas/schema/m.call.invite.yaml +++ b/data/event-schemas/schema/m.call.invite.yaml @@ -7,11 +7,10 @@ "properties": { "content": { "type": "object", + "allOf": [{ + "$ref": "core-event-schema/call_event.yaml" + }], "properties": { - "call_id": { - "type": "string", - "description": "A unique identifier for the call." - }, "offer": { "type": "object", "title": "Offer", @@ -29,16 +28,17 @@ }, "required": ["type", "sdp"] }, - "version": { - "type": "integer", - "description": "The version of the VoIP specification this message adheres to. This specification is version 0." - }, "lifetime": { "type": "integer", "description": "The time in milliseconds that the invite is valid for. Once the invite age exceeds this value, clients should discard it. They should also no longer show the call as awaiting an answer in the UI." + }, + "invitee": { + "type": "string", + "description": "The ID of the user being called. If omitted, any user in the room can answer.", + "x-addedInMatrixVersion": "1.7", } }, - "required": ["call_id", "offer", "version", "lifetime"] + "required": ["offer", "lifetime"] }, "type": { "type": "string", diff --git a/data/event-schemas/schema/m.call.negotiate.yaml b/data/event-schemas/schema/m.call.negotiate.yaml new file mode 100644 index 00000000..abc5ef1d --- /dev/null +++ b/data/event-schemas/schema/m.call.negotiate.yaml @@ -0,0 +1,74 @@ +--- +type: object +description: | + Provides SDP negotiation semantics for media pause, hold/resume, ICE restarts + and voice/video call up/downgrading. Clients should implement and honour hold + functionality as per [WebRTC's recommendation](https://www.w3.org/TR/webrtc/#hold-functionality). + + If both the invite event and the accepted answer event have `version` equal + to `"1"`, either party may send `m.call.negotiate` with a `description` field + to offer new SDP to the other party. This event has `call_id` with the ID of + the call and `party_id` equal to the client's party ID for that call. The + caller ignores any negotiate events with `party_id` + `user_id` tuple not + equal to that of the answer it accepted and the callee ignores any negotiate + events with `party_id` + `user_id` tuple not equal to that of the caller. + Clients should use the `party_id` field to ignore the remote echo of their + own negotiate events. + + This has a `lifetime` field as in `m.call.invite`, after which the sender of + the negotiate event should consider the negotiation failed (timed out) and + the recipient should ignore it. + + The `description` field is the same as the `offer` field in `m.call.invite` + and `answer` field in `m.call.answer` and is an `RTCSessionDescriptionInit` + object as per https://www.w3.org/TR/webrtc/#dom-rtcsessiondescriptioninit. + + Once an `m.call.negotiate` event is received, the client must respond with + another `m.call.negotiate` event, with the SDP answer (with `"type": "answer"`) + in the `description` property. + + In the `m.call.invite` and `m.call.answer` events, the `offer` and `answer` + fields respectively are objects of type `RTCSessionDescriptionInit`. Hence + the `type` field, whilst redundant in these events, is included for ease of + working with the WebRTC API and is mandatory. Receiving clients should not + attempt to validate the `type` field, but simply pass the object into the + WebRTC API. +x-addedInMatrixVersion: "1.7" +allOf: +- "$ref": core-event-schema/room_event.yaml +properties: + content: + type: object + allOf: + - "$ref": core-event-schema/call_event.yaml + properties: + offer: + type: object + title: Offer + description: The session description object + properties: + type: + type: string + enum: + - offer + description: The type of session description. + sdp: + type: string + description: The SDP text of the session description. + required: + - type + - sdp + lifetime: + type: integer + description: The time in milliseconds that the invite is valid for. + Once the invite age exceeds this value, clients should discard it. + They should also no longer show the call as awaiting an answer in the + UI. + required: + - offer + - lifetime + type: + type: string + enum: + - m.call.negotiate + diff --git a/data/event-schemas/schema/m.call.reject.yaml b/data/event-schemas/schema/m.call.reject.yaml new file mode 100644 index 00000000..39726c1a --- /dev/null +++ b/data/event-schemas/schema/m.call.reject.yaml @@ -0,0 +1,28 @@ +--- +type: object +description: | + If the `m.call.invite` event has `version` `"1"`, a client wishing to + reject the call sends an `m.call.reject` event. This rejects the call on all devices, + but if the calling device sees an `answer` before the `reject`, it disregards the + reject event and carries on. The reject has a `party_id` just like an answer, and + the caller sends a `select_answer` for it just like an answer. If another client + had already sent an answer and sees the caller select the reject response instead + of its answer, it ends the call. If the `m.call.invite` event has `version` `0`, + the callee sends an `m.call.hangup` event. If the calling user chooses to end the + call before setup is complete, the client sends `m.call.hangup` as previously. + + Note that, unlike `m.call.hangup`, this event has no `reason` field: the rejection of + a call is always implicitly because the user chose not to answer it. +x-addedInMatrixVersion: "1.7" +allOf: +- "$ref": core-event-schema/room_event.yaml +properties: + content: + type: object + allOf: + - "$ref": core-event-schema/call_event.yaml + type: + type: string + enum: + - m.call.reject + diff --git a/data/event-schemas/schema/m.call.select_answer.yaml b/data/event-schemas/schema/m.call.select_answer.yaml new file mode 100644 index 00000000..b47c1352 --- /dev/null +++ b/data/event-schemas/schema/m.call.select_answer.yaml @@ -0,0 +1,27 @@ +{ + "type": "object", + "description": "This event is sent by the caller's client once it has decided which other client to talk to, by selecting one of multiple possible incoming `m.call.answer` events. Its `selected_party_id` field indicates the answer it's chosen. The `call_id` and `party_id` of the caller is also included. If the callee's client sees a `select_answer` for an answer with party ID other than the one it sent, it ends the call and informs the user the call was answered elsewhere. It does not send any events. Media can start flowing before this event is seen or even sent. Clients that implement previous versions of this specification will ignore this event and behave as they did before.", + "x-addedInMatrixVersion": "1.7", + "allOf": [{ + "$ref": "core-event-schema/room_event.yaml" + }], + "properties": { + "content": { + "type": "object", + "allOf": [{ + "$ref": "core-event-schema/call_event.yaml" + }], + "properties": { + "selected_party_id": { + "type": "string", + "description": "The `party_id` field from the answer event that the caller chose." + }, + }, + "required": ["selected_party_id"] + }, + "type": { + "type": "string", + "enum": ["m.call.select_answer"] + } + } +} From c94bebc98385ab2be1c37f7a2bb1ed7e86ace6af Mon Sep 17 00:00:00 2001 From: Michael Kohler Date: Tue, 23 May 2023 21:40:32 +0200 Subject: [PATCH 20/59] Add knock_restricted to m.room.join_rules enum (#1535) * Add knock_restricted to m.room.join_rules enum Signed-off-by: Michael Kohler Fixes #1491 * Add changelog --- changelogs/client_server/newsfragments/1535.clarification | 1 + data/event-schemas/schema/m.room.join_rules.yaml | 1 + 2 files changed, 2 insertions(+) create mode 100644 changelogs/client_server/newsfragments/1535.clarification diff --git a/changelogs/client_server/newsfragments/1535.clarification b/changelogs/client_server/newsfragments/1535.clarification new file mode 100644 index 00000000..805f6b56 --- /dev/null +++ b/changelogs/client_server/newsfragments/1535.clarification @@ -0,0 +1 @@ +Add missing `knock_restricted` join rule to the `m.room.join_rules` schema. diff --git a/data/event-schemas/schema/m.room.join_rules.yaml b/data/event-schemas/schema/m.room.join_rules.yaml index d5f8eb2d..b6a322c6 100644 --- a/data/event-schemas/schema/m.room.join_rules.yaml +++ b/data/event-schemas/schema/m.room.join_rules.yaml @@ -28,6 +28,7 @@ properties: - invite - private - restricted + - knock_restricted type: string allow: x-addedInMatrixVersion: "1.2" From c6348c9f78ac1a987f94dbed89e4f383117209f7 Mon Sep 17 00:00:00 2001 From: Michael Kohler Date: Tue, 23 May 2023 23:33:55 +0200 Subject: [PATCH 21/59] Remove age_ts from reference hash calculation (#1536) * Remove age_ts from reference hash calculation Signed-off-by: Michael Kohler * Add newsfragment * Fix newsfragment number * Update changelogs/server_server/newsfragments/1536.clarification Co-authored-by: Travis Ralston --------- Signed-off-by: Michael Kohler Co-authored-by: Travis Ralston --- changelogs/server_server/newsfragments/1536.clarification | 1 + content/server-server-api.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 changelogs/server_server/newsfragments/1536.clarification diff --git a/changelogs/server_server/newsfragments/1536.clarification b/changelogs/server_server/newsfragments/1536.clarification new file mode 100644 index 00000000..717dc43f --- /dev/null +++ b/changelogs/server_server/newsfragments/1536.clarification @@ -0,0 +1 @@ +Remove extraneous `age_ts` field from the reference hash calculation section. \ No newline at end of file diff --git a/content/server-server-api.md b/content/server-server-api.md index fabe7820..b8c78345 100644 --- a/content/server-server-api.md +++ b/content/server-server-api.md @@ -1270,7 +1270,7 @@ specification](/rooms) for more information. It is calculated as follows. 1. The event is put through the redaction algorithm. -2. The `signatures`, `age_ts`, and `unsigned` properties are removed +2. The `signatures` and `unsigned` properties are removed from the event, if present. 3. The event is converted into [Canonical JSON](/appendices#canonical-json). From d028dc4b826fb94a508ed487becbec9a1deaa9f0 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 23 May 2023 16:14:54 -0600 Subject: [PATCH 22/59] Normalize changelog for v1.7 --- changelogs/appendices/newsfragments/1468.clarification | 2 +- changelogs/appendices/newsfragments/1483.clarification | 2 +- changelogs/appendices/newsfragments/1484.clarification | 2 +- changelogs/application_service/newsfragments/1516.new | 1 - changelogs/application_service/newsfragments/1516.new.1 | 1 + changelogs/application_service/newsfragments/1516.new.2 | 1 + changelogs/client_server/newsfragments/1439.clarification | 2 +- changelogs/client_server/newsfragments/1442.clarification | 2 +- changelogs/client_server/newsfragments/1455.clarification | 2 +- changelogs/client_server/newsfragments/1464.clarification | 2 +- changelogs/client_server/newsfragments/1464.feature | 2 +- .../newsfragments/{1465.clarifications => 1465.clarification} | 0 changelogs/client_server/newsfragments/1485.clarification | 2 +- changelogs/client_server/newsfragments/1487.clarification | 2 +- changelogs/client_server/newsfragments/1495.clarification | 2 +- changelogs/client_server/newsfragments/1499.feature | 3 +-- changelogs/client_server/newsfragments/1499.new.1 | 1 + changelogs/client_server/newsfragments/1499.new.2 | 1 + changelogs/client_server/newsfragments/1501.clarification | 2 +- changelogs/client_server/newsfragments/1508.feature | 3 +-- changelogs/client_server/newsfragments/1510.feature | 3 +-- changelogs/client_server/newsfragments/1511.feature | 2 +- changelogs/client_server/newsfragments/1529.feature | 2 +- changelogs/client_server/newsfragments/1530.new | 2 +- changelogs/identity_service/newsfragments/1457.clarification | 1 - .../newsfragments/1457.clarification | 0 changelogs/internal/newsfragments/1488.clarification | 2 +- changelogs/server_server/newsfragments/1431.clarification | 2 +- changelogs/server_server/newsfragments/1454.clarification | 2 +- changelogs/server_server/newsfragments/1457.clarification | 1 - changelogs/server_server/newsfragments/1466.clarification | 2 +- changelogs/server_server/newsfragments/1518.clarification | 2 +- 32 files changed, 27 insertions(+), 29 deletions(-) delete mode 100644 changelogs/application_service/newsfragments/1516.new create mode 100644 changelogs/application_service/newsfragments/1516.new.1 create mode 100644 changelogs/application_service/newsfragments/1516.new.2 rename changelogs/client_server/newsfragments/{1465.clarifications => 1465.clarification} (100%) create mode 100644 changelogs/client_server/newsfragments/1499.new.1 create mode 100644 changelogs/client_server/newsfragments/1499.new.2 delete mode 100644 changelogs/identity_service/newsfragments/1457.clarification rename changelogs/{client_server => internal}/newsfragments/1457.clarification (100%) delete mode 100644 changelogs/server_server/newsfragments/1457.clarification diff --git a/changelogs/appendices/newsfragments/1468.clarification b/changelogs/appendices/newsfragments/1468.clarification index 6f8ab86f..b3bb0bf4 100644 --- a/changelogs/appendices/newsfragments/1468.clarification +++ b/changelogs/appendices/newsfragments/1468.clarification @@ -1 +1 @@ -Clarify that the term "Canonical JSON" is a specific thing within the matrix specification. +Clarify that the term "Canonical JSON" is a specific thing within the Matrix specification. diff --git a/changelogs/appendices/newsfragments/1483.clarification b/changelogs/appendices/newsfragments/1483.clarification index 4c2042e3..27a3b11d 100644 --- a/changelogs/appendices/newsfragments/1483.clarification +++ b/changelogs/appendices/newsfragments/1483.clarification @@ -1 +1 @@ -Remove references to groups +Remove references to groups. \ No newline at end of file diff --git a/changelogs/appendices/newsfragments/1484.clarification b/changelogs/appendices/newsfragments/1484.clarification index b29c7ad3..72edfa2f 100644 --- a/changelogs/appendices/newsfragments/1484.clarification +++ b/changelogs/appendices/newsfragments/1484.clarification @@ -1 +1 @@ -Clarifications of event ID formats in early room versions +Clarifications of event ID formats in early room versions. \ No newline at end of file diff --git a/changelogs/application_service/newsfragments/1516.new b/changelogs/application_service/newsfragments/1516.new deleted file mode 100644 index c6244075..00000000 --- a/changelogs/application_service/newsfragments/1516.new +++ /dev/null @@ -1 +0,0 @@ -Add `POST /_matrix/app/v1/ping` and `POST /_matrix/client/v1/appservice/{appserviceId}/ping` endpoints as per [MSC2659](https://github.com/matrix-org/matrix-spec-proposals/pull/2659). diff --git a/changelogs/application_service/newsfragments/1516.new.1 b/changelogs/application_service/newsfragments/1516.new.1 new file mode 100644 index 00000000..7290a87c --- /dev/null +++ b/changelogs/application_service/newsfragments/1516.new.1 @@ -0,0 +1 @@ +[`POST /_matrix/app/v1/ping`](/application-service-api/#post_matrixappv1ping) diff --git a/changelogs/application_service/newsfragments/1516.new.2 b/changelogs/application_service/newsfragments/1516.new.2 new file mode 100644 index 00000000..ccde9078 --- /dev/null +++ b/changelogs/application_service/newsfragments/1516.new.2 @@ -0,0 +1 @@ +[`POST /_matrix/client/v1/appservice/{appserviceId}/ping`](/application-service-api/#post_matrixclientv1appserviceappserviceidping) \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1439.clarification b/changelogs/client_server/newsfragments/1439.clarification index ed05216d..0323f6de 100644 --- a/changelogs/client_server/newsfragments/1439.clarification +++ b/changelogs/client_server/newsfragments/1439.clarification @@ -1 +1 @@ -Clarify that reply chain fallback for threads may not be present. +Clarify that reply chain fallback for threads might not be present. diff --git a/changelogs/client_server/newsfragments/1442.clarification b/changelogs/client_server/newsfragments/1442.clarification index 3ccb2333..ca5f3aea 100644 --- a/changelogs/client_server/newsfragments/1442.clarification +++ b/changelogs/client_server/newsfragments/1442.clarification @@ -1 +1 @@ -Fix various typos throughout the specification. +Fix various typos throughout the specification. \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1455.clarification b/changelogs/client_server/newsfragments/1455.clarification index 3ccb2333..ca5f3aea 100644 --- a/changelogs/client_server/newsfragments/1455.clarification +++ b/changelogs/client_server/newsfragments/1455.clarification @@ -1 +1 @@ -Fix various typos throughout the specification. +Fix various typos throughout the specification. \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1464.clarification b/changelogs/client_server/newsfragments/1464.clarification index f5bd822e..6096584f 100644 --- a/changelogs/client_server/newsfragments/1464.clarification +++ b/changelogs/client_server/newsfragments/1464.clarification @@ -1 +1 @@ -Disambiguate using property names with dots in them during push rule processing, per [MSC3873](https://github.com/matrix-org/matrix-spec-proposals/pull/3873) and [MSC3980](https://github.com/matrix-org/matrix-spec-proposals/pull/3980). +Disambiguate using property names with dots in them during push rule processing, as per [MSC3873](https://github.com/matrix-org/matrix-spec-proposals/pull/3873) and [MSC3980](https://github.com/matrix-org/matrix-spec-proposals/pull/3980). diff --git a/changelogs/client_server/newsfragments/1464.feature b/changelogs/client_server/newsfragments/1464.feature index 7c1c01ec..fa09a067 100644 --- a/changelogs/client_server/newsfragments/1464.feature +++ b/changelogs/client_server/newsfragments/1464.feature @@ -1 +1 @@ -Add new push rule conditions: `event_property_is` and `event_property_contains` from [MSC3758](https://github.com/matrix-org/matrix-spec-proposals/pull/3758) and [MSC3966](https://github.com/matrix-org/matrix-spec-proposals/pull/3966). +Add new push rule conditions `event_property_is` and `event_property_contains`, as per [MSC3758](https://github.com/matrix-org/matrix-spec-proposals/pull/3758) and [MSC3966](https://github.com/matrix-org/matrix-spec-proposals/pull/3966). diff --git a/changelogs/client_server/newsfragments/1465.clarifications b/changelogs/client_server/newsfragments/1465.clarification similarity index 100% rename from changelogs/client_server/newsfragments/1465.clarifications rename to changelogs/client_server/newsfragments/1465.clarification diff --git a/changelogs/client_server/newsfragments/1485.clarification b/changelogs/client_server/newsfragments/1485.clarification index 99e5fc79..0759c8cc 100644 --- a/changelogs/client_server/newsfragments/1485.clarification +++ b/changelogs/client_server/newsfragments/1485.clarification @@ -1 +1 @@ -Remove fictitious `token` parameter on `/keys/query` endpoint +Remove fictitious `token` parameter on `/keys/query` endpoint. diff --git a/changelogs/client_server/newsfragments/1487.clarification b/changelogs/client_server/newsfragments/1487.clarification index 44494576..f94a56f1 100644 --- a/changelogs/client_server/newsfragments/1487.clarification +++ b/changelogs/client_server/newsfragments/1487.clarification @@ -1 +1 @@ -Fix rendering of properties with a list of types +Fix rendering of properties with a list of types. diff --git a/changelogs/client_server/newsfragments/1495.clarification b/changelogs/client_server/newsfragments/1495.clarification index 8132e060..69672a4c 100644 --- a/changelogs/client_server/newsfragments/1495.clarification +++ b/changelogs/client_server/newsfragments/1495.clarification @@ -1 +1 @@ -Clarify parts of the end-to-end encryption sections. +Clarify parts of the cross-signing signature upload request. diff --git a/changelogs/client_server/newsfragments/1499.feature b/changelogs/client_server/newsfragments/1499.feature index efd70374..1532d281 100644 --- a/changelogs/client_server/newsfragments/1499.feature +++ b/changelogs/client_server/newsfragments/1499.feature @@ -1,2 +1 @@ -Add new endpoints `POST /_matrix/media/v1/create` and `PUT /_matrix/media/v3/upload/{serverName}/{mediaId}`, and other changes for asynchronous media upload, as per [MSC2246](https://github.com/matrix-org/matrix-spec-proposals/pull/2246). - +Support asynchronous media uploads, as per [MSC2246](https://github.com/matrix-org/matrix-spec-proposals/pull/2246). diff --git a/changelogs/client_server/newsfragments/1499.new.1 b/changelogs/client_server/newsfragments/1499.new.1 new file mode 100644 index 00000000..d7fbdbb6 --- /dev/null +++ b/changelogs/client_server/newsfragments/1499.new.1 @@ -0,0 +1 @@ +[`POST /_matrix/media/v1/create`](/client-server-api/#post_matrixmediav1create) \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1499.new.2 b/changelogs/client_server/newsfragments/1499.new.2 new file mode 100644 index 00000000..226cb2e4 --- /dev/null +++ b/changelogs/client_server/newsfragments/1499.new.2 @@ -0,0 +1 @@ +[`PUT /_matrix/media/v3/upload/{serverName}/{mediaId}`](/client-server-api/#put_matrixmediav3uploadservernamemediaid) \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1501.clarification b/changelogs/client_server/newsfragments/1501.clarification index 97fa837c..cdac3968 100644 --- a/changelogs/client_server/newsfragments/1501.clarification +++ b/changelogs/client_server/newsfragments/1501.clarification @@ -1 +1 @@ -Remove the `dont_notify` and `coalesce` push rule actions per [MSC3987](https://github.com/matrix-org/matrix-spec-proposals/pull/3987). +Remove the `dont_notify` and `coalesce` push rule actions, as per [MSC3987](https://github.com/matrix-org/matrix-spec-proposals/pull/3987). diff --git a/changelogs/client_server/newsfragments/1508.feature b/changelogs/client_server/newsfragments/1508.feature index 66e9670f..324ca9a8 100644 --- a/changelogs/client_server/newsfragments/1508.feature +++ b/changelogs/client_server/newsfragments/1508.feature @@ -1,2 +1 @@ -Document the `m.mentions` property; the `.m.rule.is_user_mention` and `.m.rule.is_room_mention` push rules; and other behaviour from [MSC3952](https://github.com/matrix-org/matrix-spec-proposals/pull/3952). - +Document the `m.mentions` property; the `.m.rule.is_user_mention` and `.m.rule.is_room_mention` push rules; and other notification behaviour, as per [MSC3952](https://github.com/matrix-org/matrix-spec-proposals/pull/3952). diff --git a/changelogs/client_server/newsfragments/1510.feature b/changelogs/client_server/newsfragments/1510.feature index efd70374..1532d281 100644 --- a/changelogs/client_server/newsfragments/1510.feature +++ b/changelogs/client_server/newsfragments/1510.feature @@ -1,2 +1 @@ -Add new endpoints `POST /_matrix/media/v1/create` and `PUT /_matrix/media/v3/upload/{serverName}/{mediaId}`, and other changes for asynchronous media upload, as per [MSC2246](https://github.com/matrix-org/matrix-spec-proposals/pull/2246). - +Support asynchronous media uploads, as per [MSC2246](https://github.com/matrix-org/matrix-spec-proposals/pull/2246). diff --git a/changelogs/client_server/newsfragments/1511.feature b/changelogs/client_server/newsfragments/1511.feature index d3526b8e..295a23da 100644 --- a/changelogs/client_server/newsfragments/1511.feature +++ b/changelogs/client_server/newsfragments/1511.feature @@ -1 +1 @@ -Update VoIP spec for [MSC2746](https://github.com/matrix-org/matrix-spec-proposals/pull/2746). +Improve VoIP signaling, as per [MSC2746](https://github.com/matrix-org/matrix-spec-proposals/pull/2746). diff --git a/changelogs/client_server/newsfragments/1529.feature b/changelogs/client_server/newsfragments/1529.feature index 48f1d90b..e53bdfd8 100644 --- a/changelogs/client_server/newsfragments/1529.feature +++ b/changelogs/client_server/newsfragments/1529.feature @@ -1 +1 @@ -Addition of redirect downloads, as per [MSC3860](https://github.com/matrix-org/matrix-spec-proposals/pull/3860). +Add an ability to redirect media downloads, as per [MSC3860](https://github.com/matrix-org/matrix-spec-proposals/pull/3860). diff --git a/changelogs/client_server/newsfragments/1530.new b/changelogs/client_server/newsfragments/1530.new index ffe9abd9..94cb6715 100644 --- a/changelogs/client_server/newsfragments/1530.new +++ b/changelogs/client_server/newsfragments/1530.new @@ -1 +1 @@ -[`POST /_matrix/client/v1/login/get_token`](/client-server-api/#post_matrixclientv1loginget_token). \ No newline at end of file +[`POST /_matrix/client/v1/login/get_token`](/client-server-api/#post_matrixclientv1loginget_token) \ No newline at end of file diff --git a/changelogs/identity_service/newsfragments/1457.clarification b/changelogs/identity_service/newsfragments/1457.clarification deleted file mode 100644 index 0abd9b6c..00000000 --- a/changelogs/identity_service/newsfragments/1457.clarification +++ /dev/null @@ -1 +0,0 @@ -Wrap $ref in allOf where other attributes are present, to improve OpenAPI compliance. diff --git a/changelogs/client_server/newsfragments/1457.clarification b/changelogs/internal/newsfragments/1457.clarification similarity index 100% rename from changelogs/client_server/newsfragments/1457.clarification rename to changelogs/internal/newsfragments/1457.clarification diff --git a/changelogs/internal/newsfragments/1488.clarification b/changelogs/internal/newsfragments/1488.clarification index d54557d9..6411f662 100644 --- a/changelogs/internal/newsfragments/1488.clarification +++ b/changelogs/internal/newsfragments/1488.clarification @@ -1 +1 @@ -Fix generation of anchors for additional properties +Fix generation of anchors for additional properties. \ No newline at end of file diff --git a/changelogs/server_server/newsfragments/1431.clarification b/changelogs/server_server/newsfragments/1431.clarification index 3ccb2333..ca5f3aea 100644 --- a/changelogs/server_server/newsfragments/1431.clarification +++ b/changelogs/server_server/newsfragments/1431.clarification @@ -1 +1 @@ -Fix various typos throughout the specification. +Fix various typos throughout the specification. \ No newline at end of file diff --git a/changelogs/server_server/newsfragments/1454.clarification b/changelogs/server_server/newsfragments/1454.clarification index 6d68b88a..559c1442 100644 --- a/changelogs/server_server/newsfragments/1454.clarification +++ b/changelogs/server_server/newsfragments/1454.clarification @@ -1 +1 @@ -Fix invalid OpenAPI specifications caused by overridden references to `examples/minimal_pdu.json`. +Fix PDU examples by removing invalid OpenAPI reference to `examples/minimal_pdu.json`. diff --git a/changelogs/server_server/newsfragments/1457.clarification b/changelogs/server_server/newsfragments/1457.clarification deleted file mode 100644 index 0abd9b6c..00000000 --- a/changelogs/server_server/newsfragments/1457.clarification +++ /dev/null @@ -1 +0,0 @@ -Wrap $ref in allOf where other attributes are present, to improve OpenAPI compliance. diff --git a/changelogs/server_server/newsfragments/1466.clarification b/changelogs/server_server/newsfragments/1466.clarification index 3ccb2333..ca5f3aea 100644 --- a/changelogs/server_server/newsfragments/1466.clarification +++ b/changelogs/server_server/newsfragments/1466.clarification @@ -1 +1 @@ -Fix various typos throughout the specification. +Fix various typos throughout the specification. \ No newline at end of file diff --git a/changelogs/server_server/newsfragments/1518.clarification b/changelogs/server_server/newsfragments/1518.clarification index 3ccb2333..ca5f3aea 100644 --- a/changelogs/server_server/newsfragments/1518.clarification +++ b/changelogs/server_server/newsfragments/1518.clarification @@ -1 +1 @@ -Fix various typos throughout the specification. +Fix various typos throughout the specification. \ No newline at end of file From db0fd307447edeb5724c9897e07e6c56d87123f6 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 23 May 2023 16:24:26 -0600 Subject: [PATCH 23/59] Fix stray localhost link --- data/api/client-server/content-repo.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/data/api/client-server/content-repo.yaml b/data/api/client-server/content-repo.yaml index e12c5612..57445027 100644 --- a/data/api/client-server/content-repo.yaml +++ b/data/api/client-server/content-repo.yaml @@ -201,7 +201,7 @@ paths: summary: Create a new `mxc://` URI without uploading the content. description: |- Creates a new `mxc://` URI, independently of the content being uploaded. The content must be provided later - via [`PUT /_matrix/media/v3/upload/{serverName}/{mediaId}`](http://localhost:1313/client-server-api/#put_matrixmediav3uploadservernamemediaid). + via [`PUT /_matrix/media/v3/upload/{serverName}/{mediaId}`](/client-server-api/#put_matrixmediav3uploadservernamemediaid). The server may optionally enforce a maximum age for unused IDs, and delete media IDs when the client doesn't start the upload in time, From bdf574eeb2e54a832502b6a6ea5f8fb6f4a985f1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Thu, 25 May 2023 00:00:38 +0200 Subject: [PATCH 24/59] Fix typo in VoIP module (#1540) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- changelogs/client_server/newsfragments/1540.feature | 1 + content/client-server-api/modules/voip_events.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 changelogs/client_server/newsfragments/1540.feature diff --git a/changelogs/client_server/newsfragments/1540.feature b/changelogs/client_server/newsfragments/1540.feature new file mode 100644 index 00000000..295a23da --- /dev/null +++ b/changelogs/client_server/newsfragments/1540.feature @@ -0,0 +1 @@ +Improve VoIP signaling, as per [MSC2746](https://github.com/matrix-org/matrix-spec-proposals/pull/2746). diff --git a/content/client-server-api/modules/voip_events.md b/content/client-server-api/modules/voip_events.md index 75cc7757..102e3dcd 100644 --- a/content/client-server-api/modules/voip_events.md +++ b/content/client-server-api/modules/voip_events.md @@ -44,7 +44,7 @@ A grammar for `party_id` is defined [below](#grammar-for-voip-ids). #### Politeness In line with [WebRTC perfect negotiation](https://w3c.github.io/webrtc-pc/#perfect-negotiation-example) there are rules to establish which party is polite in the process of renegotiation. The callee is -always the polite party. In a glare situation, the politenes of a party is therefore determined by +always the polite party. In a glare situation, the politeness of a party is therefore determined by whether the inbound or outbound call is used: if a client discards its outbound call in favour of an inbound call, it becomes the polite party. From 089d209047430f99fca747eed215469467b74289 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Thu, 25 May 2023 00:26:26 +0200 Subject: [PATCH 25/59] Mark the appservice ping response `duration_ms` field as required (#1541) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Mark the appservice ping response duration_ms field as required As intended in MSC2659. Signed-off-by: Kévin Commaille * Add changelog Signed-off-by: Kévin Commaille --------- Signed-off-by: Kévin Commaille --- changelogs/application_service/newsfragments/1541.feature | 1 + data/api/client-server/appservice_ping.yaml | 2 ++ 2 files changed, 3 insertions(+) create mode 100644 changelogs/application_service/newsfragments/1541.feature diff --git a/changelogs/application_service/newsfragments/1541.feature b/changelogs/application_service/newsfragments/1541.feature new file mode 100644 index 00000000..ee222fb0 --- /dev/null +++ b/changelogs/application_service/newsfragments/1541.feature @@ -0,0 +1 @@ +Add homeserver->appservice ping mechanism, as per [MSC2659](https://github.com/matrix-org/matrix-spec-proposals/pull/2659). Contributed by @tulir at @beeper. diff --git a/data/api/client-server/appservice_ping.yaml b/data/api/client-server/appservice_ping.yaml index 4075e901..13b7289f 100644 --- a/data/api/client-server/appservice_ping.yaml +++ b/data/api/client-server/appservice_ping.yaml @@ -82,6 +82,8 @@ paths: The duration in milliseconds that the [`/_matrix/app/v1/ping`](#post_matrixappv1ping) request took from the homeserver's point of view. + required: + - duration_ms examples: application/json: {"duration_ms": 123} 400: From fbb8a789f605a304e53b79e96b700b7f154aafcd Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 25 May 2023 09:35:38 -0600 Subject: [PATCH 26/59] Add release checklist issue template; Document some of our timelines around releases (#1538) * Add a spec release checklist issue template because I'm tired of copy/paste * Document a chunk of our release approach This should probably go elsewhere, but here is fine for now as a SCT-referenced doc/content. * changelog * Brief clarifications --- .github/ISSUE_TEMPLATE/release.md | 34 ++++++++++++++ .../internal/newsfragments/1538.clarification | 1 + meta/releasing.md | 45 +++++++++++++++++++ 3 files changed, 80 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/release.md create mode 100644 changelogs/internal/newsfragments/1538.clarification diff --git a/.github/ISSUE_TEMPLATE/release.md b/.github/ISSUE_TEMPLATE/release.md new file mode 100644 index 00000000..83701f14 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/release.md @@ -0,0 +1,34 @@ +--- +name: [SCT] Release checklist +about: Used by the Spec Core Team to create a new release. +title: 'Matrix 1.X' +labels: 'release-blocker' +assignees: '' + +--- + + + + + +Date: **Thursday, May 25, 2023** +Previous release: + +Preflight checklist ([release steps](https://github.com/matrix-org/matrix-spec/blob/main/meta/releasing.md)): + +* [ ] Blog post written +* [ ] Check for release blockers that may have been missed +* [ ] Review/fix the changelog + +Release checklist ([release steps](https://github.com/matrix-org/matrix-spec/blob/main/meta/releasing.md)): +* [ ] Branch stuffs +* [ ] Github release artifact +* [ ] Published to spec.matrix.org +* [ ] All links work +* [ ] Publish blog post +* [ ] Announce in #matrix-spec, client developers, HS developers, SCT office, and other rooms as warranted +* [ ] Post to Twitter/Mastodon +* [ ] Close this issue + +Known release blockers: +* [ ] diff --git a/changelogs/internal/newsfragments/1538.clarification b/changelogs/internal/newsfragments/1538.clarification new file mode 100644 index 00000000..3362118d --- /dev/null +++ b/changelogs/internal/newsfragments/1538.clarification @@ -0,0 +1 @@ +Document more of the spec release timeline/process. \ No newline at end of file diff --git a/meta/releasing.md b/meta/releasing.md index 7483c357..92dd9be8 100644 --- a/meta/releasing.md +++ b/meta/releasing.md @@ -4,6 +4,51 @@ The whole specification is now released as a single unit/artifact. This document the process for releasing the specification and a description of how the (public) machinery works. +## Timeline + +The spec is released each calendar quarter. The target release dates are within the +following ranges: + +* Q1: January 20-27 (critically, before FOSDEM). +* Q2: May 20-27. +* Q3: August 20-27. +* Q4: November 1-15 (before recurring November conflicts, like IETF). + +The SCT aims to have dates picked out by: + +* Q1: January 10. +* Q2: May 1. +* Q3: August 1. +* Q4: October 15. + +When a release date is picked, a [checklist](https://github.com/matrix-org/matrix-spec/issues/new?assignees=&labels=release-blocker&projects=&template=release.md&title=Matrix+1.X) +issue is created to track details of the release. Release blockers should continue to +be accepted up until 7 calendar days prior to the release date. + +**Release dates are not promises.** The SCT reserves the ability to change, cancel, +postpone, etc a release for any reason. Do not rely on a release happening on a given +day until the release has actually happened & blog post published. + +Once a release is scheduled, the SCT will begin planning what the next release is +expected to look like. The plan should be included in the spec release blog post, +and be ready for exeuction on spec release day. Plans are guides and not promises. + +A blog post for the SCT members to review should be ready at minimum 1 week before +the target release date. 1-2 days before the release itself, the prerequisite steps +below are executed to ensure the spec release can go ahead. + +## Release composition + +*This section is a work in progress.* + +Mentioned above, the SCT aims to have spec releases quarterly. Each quarter has a +slightly different theme to it: + +* Q1: Massive feature release, if possible. This generally happens thanks to FOSDEM. +* Q2: Regular feature release, if possible. +* Q3: Momentum-continuing feature release, if possible. +* Q4: Preferably a maintenance release, but will accept features per normal. + ## Prerequisites / preparation First, can we even release the spec? This stage is mostly preparation work needed From 65d70e90b82089dfc8971e8d1fd19f8cf449a8a0 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 25 May 2023 09:46:35 -0600 Subject: [PATCH 27/59] Tag Matrix 1.7 --- config.toml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/config.toml b/config.toml index d1749268..c36456cd 100644 --- a/config.toml +++ b/config.toml @@ -47,14 +47,14 @@ privacy_policy = "https://matrix.org/legal/privacy-notice" [params.version] # must be one of "unstable", "current", "historical" # this is used to decide whether to show a banner pointing to the current release -status = "unstable" +status = "stable" # A URL pointing to the latest, stable release of the spec. To be shown in the unstable version warning banner. current_version_url = "https://spec.matrix.org/latest" # The following is used when status = "stable", and is displayed in various UI elements on a released version # of the spec. CI will set these values here automatically when a release git tag (i.e `v1.5`) is created. -# major = "1" -# minor = "6" -# release_date = "February 14, 2023" +major = "1" +minor = "7" +release_date = "May 25, 2023" # User interface configuration [params.ui] From 8b51f1c0110384a970b777afdc11d76b17f4e97d Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 25 May 2023 09:47:33 -0600 Subject: [PATCH 28/59] Matrix 1.7 --- .../newsfragments/1468.clarification | 1 - .../newsfragments/1483.clarification | 1 - .../newsfragments/1484.clarification | 1 - .../newsfragments/1447.clarification | 1 - .../newsfragments/1516.feature | 1 - .../newsfragments/1516.new.1 | 1 - .../newsfragments/1516.new.2 | 1 - .../newsfragments/1541.feature | 1 - .../newsfragments/1424.clarification | 1 - .../newsfragments/1432.clarification | 1 - .../newsfragments/1439.clarification | 1 - .../client_server/newsfragments/1440.feature | 1 - .../newsfragments/1441.clarification | 1 - .../newsfragments/1442.clarification | 1 - .../newsfragments/1447.clarification | 1 - .../newsfragments/1449.clarification | 1 - .../newsfragments/1455.clarification | 1 - .../newsfragments/1461.clarification | 1 - .../newsfragments/1463.clarification | 1 - .../newsfragments/1464.clarification | 1 - .../client_server/newsfragments/1464.feature | 1 - .../newsfragments/1465.clarification | 1 - .../newsfragments/1474.clarification | 1 - .../client_server/newsfragments/1475.feature | 1 - .../newsfragments/1479.clarification | 1 - .../newsfragments/1485.clarification | 1 - .../newsfragments/1487.clarification | 1 - .../newsfragments/1495.clarification | 1 - .../client_server/newsfragments/1499.feature | 1 - .../client_server/newsfragments/1499.new.1 | 1 - .../client_server/newsfragments/1499.new.2 | 1 - .../newsfragments/1500.clarification | 1 - .../newsfragments/1501.clarification | 1 - .../newsfragments/1507.clarification | 1 - .../client_server/newsfragments/1508.feature | 1 - .../newsfragments/1509.clarification | 1 - .../client_server/newsfragments/1510.feature | 1 - .../client_server/newsfragments/1511.feature | 1 - .../client_server/newsfragments/1525.feature | 1 - .../client_server/newsfragments/1526.feature | 1 - .../client_server/newsfragments/1529.feature | 1 - .../client_server/newsfragments/1530.feature | 1 - .../client_server/newsfragments/1530.new | 1 - .../client_server/newsfragments/1531.feature | 1 - .../newsfragments/1535.clarification | 1 - .../client_server/newsfragments/1540.feature | 1 - .../newsfragments/1486.clarification | 1 - .../internal/newsfragments/1444.clarification | 1 - .../internal/newsfragments/1446.clarification | 1 - .../internal/newsfragments/1457.clarification | 1 - .../internal/newsfragments/1476.clarification | 1 - .../internal/newsfragments/1488.clarification | 1 - .../internal/newsfragments/1534.clarification | 1 - .../internal/newsfragments/1538.clarification | 1 - .../newsfragments/1484.clarification | 1 - .../newsfragments/1431.clarification | 1 - .../newsfragments/1447.clarification | 1 - .../newsfragments/1454.clarification | 1 - .../newsfragments/1466.clarification | 1 - .../newsfragments/1473.clarification | 1 - .../newsfragments/1518.clarification | 1 - .../newsfragments/1536.clarification | 1 - content/changelog/v1.7.md | 147 ++++++++++++++++++ 63 files changed, 147 insertions(+), 62 deletions(-) delete mode 100644 changelogs/appendices/newsfragments/1468.clarification delete mode 100644 changelogs/appendices/newsfragments/1483.clarification delete mode 100644 changelogs/appendices/newsfragments/1484.clarification delete mode 100644 changelogs/application_service/newsfragments/1447.clarification delete mode 100644 changelogs/application_service/newsfragments/1516.feature delete mode 100644 changelogs/application_service/newsfragments/1516.new.1 delete mode 100644 changelogs/application_service/newsfragments/1516.new.2 delete mode 100644 changelogs/application_service/newsfragments/1541.feature delete mode 100644 changelogs/client_server/newsfragments/1424.clarification delete mode 100644 changelogs/client_server/newsfragments/1432.clarification delete mode 100644 changelogs/client_server/newsfragments/1439.clarification delete mode 100644 changelogs/client_server/newsfragments/1440.feature delete mode 100644 changelogs/client_server/newsfragments/1441.clarification delete mode 100644 changelogs/client_server/newsfragments/1442.clarification delete mode 100644 changelogs/client_server/newsfragments/1447.clarification delete mode 100644 changelogs/client_server/newsfragments/1449.clarification delete mode 100644 changelogs/client_server/newsfragments/1455.clarification delete mode 100644 changelogs/client_server/newsfragments/1461.clarification delete mode 100644 changelogs/client_server/newsfragments/1463.clarification delete mode 100644 changelogs/client_server/newsfragments/1464.clarification delete mode 100644 changelogs/client_server/newsfragments/1464.feature delete mode 100644 changelogs/client_server/newsfragments/1465.clarification delete mode 100644 changelogs/client_server/newsfragments/1474.clarification delete mode 100644 changelogs/client_server/newsfragments/1475.feature delete mode 100644 changelogs/client_server/newsfragments/1479.clarification delete mode 100644 changelogs/client_server/newsfragments/1485.clarification delete mode 100644 changelogs/client_server/newsfragments/1487.clarification delete mode 100644 changelogs/client_server/newsfragments/1495.clarification delete mode 100644 changelogs/client_server/newsfragments/1499.feature delete mode 100644 changelogs/client_server/newsfragments/1499.new.1 delete mode 100644 changelogs/client_server/newsfragments/1499.new.2 delete mode 100644 changelogs/client_server/newsfragments/1500.clarification delete mode 100644 changelogs/client_server/newsfragments/1501.clarification delete mode 100644 changelogs/client_server/newsfragments/1507.clarification delete mode 100644 changelogs/client_server/newsfragments/1508.feature delete mode 100644 changelogs/client_server/newsfragments/1509.clarification delete mode 100644 changelogs/client_server/newsfragments/1510.feature delete mode 100644 changelogs/client_server/newsfragments/1511.feature delete mode 100644 changelogs/client_server/newsfragments/1525.feature delete mode 100644 changelogs/client_server/newsfragments/1526.feature delete mode 100644 changelogs/client_server/newsfragments/1529.feature delete mode 100644 changelogs/client_server/newsfragments/1530.feature delete mode 100644 changelogs/client_server/newsfragments/1530.new delete mode 100644 changelogs/client_server/newsfragments/1531.feature delete mode 100644 changelogs/client_server/newsfragments/1535.clarification delete mode 100644 changelogs/client_server/newsfragments/1540.feature delete mode 100644 changelogs/identity_service/newsfragments/1486.clarification delete mode 100644 changelogs/internal/newsfragments/1444.clarification delete mode 100644 changelogs/internal/newsfragments/1446.clarification delete mode 100644 changelogs/internal/newsfragments/1457.clarification delete mode 100644 changelogs/internal/newsfragments/1476.clarification delete mode 100644 changelogs/internal/newsfragments/1488.clarification delete mode 100644 changelogs/internal/newsfragments/1534.clarification delete mode 100644 changelogs/internal/newsfragments/1538.clarification delete mode 100644 changelogs/room_versions/newsfragments/1484.clarification delete mode 100644 changelogs/server_server/newsfragments/1431.clarification delete mode 100644 changelogs/server_server/newsfragments/1447.clarification delete mode 100644 changelogs/server_server/newsfragments/1454.clarification delete mode 100644 changelogs/server_server/newsfragments/1466.clarification delete mode 100644 changelogs/server_server/newsfragments/1473.clarification delete mode 100644 changelogs/server_server/newsfragments/1518.clarification delete mode 100644 changelogs/server_server/newsfragments/1536.clarification create mode 100644 content/changelog/v1.7.md diff --git a/changelogs/appendices/newsfragments/1468.clarification b/changelogs/appendices/newsfragments/1468.clarification deleted file mode 100644 index b3bb0bf4..00000000 --- a/changelogs/appendices/newsfragments/1468.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify that the term "Canonical JSON" is a specific thing within the Matrix specification. diff --git a/changelogs/appendices/newsfragments/1483.clarification b/changelogs/appendices/newsfragments/1483.clarification deleted file mode 100644 index 27a3b11d..00000000 --- a/changelogs/appendices/newsfragments/1483.clarification +++ /dev/null @@ -1 +0,0 @@ -Remove references to groups. \ No newline at end of file diff --git a/changelogs/appendices/newsfragments/1484.clarification b/changelogs/appendices/newsfragments/1484.clarification deleted file mode 100644 index 72edfa2f..00000000 --- a/changelogs/appendices/newsfragments/1484.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarifications of event ID formats in early room versions. \ No newline at end of file diff --git a/changelogs/application_service/newsfragments/1447.clarification b/changelogs/application_service/newsfragments/1447.clarification deleted file mode 100644 index ca5f3aea..00000000 --- a/changelogs/application_service/newsfragments/1447.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various typos throughout the specification. \ No newline at end of file diff --git a/changelogs/application_service/newsfragments/1516.feature b/changelogs/application_service/newsfragments/1516.feature deleted file mode 100644 index ee222fb0..00000000 --- a/changelogs/application_service/newsfragments/1516.feature +++ /dev/null @@ -1 +0,0 @@ -Add homeserver->appservice ping mechanism, as per [MSC2659](https://github.com/matrix-org/matrix-spec-proposals/pull/2659). Contributed by @tulir at @beeper. diff --git a/changelogs/application_service/newsfragments/1516.new.1 b/changelogs/application_service/newsfragments/1516.new.1 deleted file mode 100644 index 7290a87c..00000000 --- a/changelogs/application_service/newsfragments/1516.new.1 +++ /dev/null @@ -1 +0,0 @@ -[`POST /_matrix/app/v1/ping`](/application-service-api/#post_matrixappv1ping) diff --git a/changelogs/application_service/newsfragments/1516.new.2 b/changelogs/application_service/newsfragments/1516.new.2 deleted file mode 100644 index ccde9078..00000000 --- a/changelogs/application_service/newsfragments/1516.new.2 +++ /dev/null @@ -1 +0,0 @@ -[`POST /_matrix/client/v1/appservice/{appserviceId}/ping`](/application-service-api/#post_matrixclientv1appserviceappserviceidping) \ No newline at end of file diff --git a/changelogs/application_service/newsfragments/1541.feature b/changelogs/application_service/newsfragments/1541.feature deleted file mode 100644 index ee222fb0..00000000 --- a/changelogs/application_service/newsfragments/1541.feature +++ /dev/null @@ -1 +0,0 @@ -Add homeserver->appservice ping mechanism, as per [MSC2659](https://github.com/matrix-org/matrix-spec-proposals/pull/2659). Contributed by @tulir at @beeper. diff --git a/changelogs/client_server/newsfragments/1424.clarification b/changelogs/client_server/newsfragments/1424.clarification deleted file mode 100644 index 758d455f..00000000 --- a/changelogs/client_server/newsfragments/1424.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify the sections of the specification concerning aggregation of child events. diff --git a/changelogs/client_server/newsfragments/1432.clarification b/changelogs/client_server/newsfragments/1432.clarification deleted file mode 100644 index ca5f3aea..00000000 --- a/changelogs/client_server/newsfragments/1432.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various typos throughout the specification. \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1439.clarification b/changelogs/client_server/newsfragments/1439.clarification deleted file mode 100644 index 0323f6de..00000000 --- a/changelogs/client_server/newsfragments/1439.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify that reply chain fallback for threads might not be present. diff --git a/changelogs/client_server/newsfragments/1440.feature b/changelogs/client_server/newsfragments/1440.feature deleted file mode 100644 index 119ab2d6..00000000 --- a/changelogs/client_server/newsfragments/1440.feature +++ /dev/null @@ -1 +0,0 @@ -Changes to the server-side aggregation of `m.replace` (edit) events, as per [MSC3925](https://github.com/matrix-org/matrix-spec-proposals/pull/3925). diff --git a/changelogs/client_server/newsfragments/1441.clarification b/changelogs/client_server/newsfragments/1441.clarification deleted file mode 100644 index f03519b8..00000000 --- a/changelogs/client_server/newsfragments/1441.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify what event property the content-specific push rules match against. diff --git a/changelogs/client_server/newsfragments/1442.clarification b/changelogs/client_server/newsfragments/1442.clarification deleted file mode 100644 index ca5f3aea..00000000 --- a/changelogs/client_server/newsfragments/1442.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various typos throughout the specification. \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1447.clarification b/changelogs/client_server/newsfragments/1447.clarification deleted file mode 100644 index ca5f3aea..00000000 --- a/changelogs/client_server/newsfragments/1447.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various typos throughout the specification. \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1449.clarification b/changelogs/client_server/newsfragments/1449.clarification deleted file mode 100644 index 1c105229..00000000 --- a/changelogs/client_server/newsfragments/1449.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify the semantics that make requests idempotent. diff --git a/changelogs/client_server/newsfragments/1455.clarification b/changelogs/client_server/newsfragments/1455.clarification deleted file mode 100644 index ca5f3aea..00000000 --- a/changelogs/client_server/newsfragments/1455.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various typos throughout the specification. \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1461.clarification b/changelogs/client_server/newsfragments/1461.clarification deleted file mode 100644 index c205f380..00000000 --- a/changelogs/client_server/newsfragments/1461.clarification +++ /dev/null @@ -1 +0,0 @@ -Improve documentation of how clients use push rules. diff --git a/changelogs/client_server/newsfragments/1463.clarification b/changelogs/client_server/newsfragments/1463.clarification deleted file mode 100644 index 1cf431ee..00000000 --- a/changelogs/client_server/newsfragments/1463.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify that servers should enforce a default `limit` on a filter if one is not specified. diff --git a/changelogs/client_server/newsfragments/1464.clarification b/changelogs/client_server/newsfragments/1464.clarification deleted file mode 100644 index 6096584f..00000000 --- a/changelogs/client_server/newsfragments/1464.clarification +++ /dev/null @@ -1 +0,0 @@ -Disambiguate using property names with dots in them during push rule processing, as per [MSC3873](https://github.com/matrix-org/matrix-spec-proposals/pull/3873) and [MSC3980](https://github.com/matrix-org/matrix-spec-proposals/pull/3980). diff --git a/changelogs/client_server/newsfragments/1464.feature b/changelogs/client_server/newsfragments/1464.feature deleted file mode 100644 index fa09a067..00000000 --- a/changelogs/client_server/newsfragments/1464.feature +++ /dev/null @@ -1 +0,0 @@ -Add new push rule conditions `event_property_is` and `event_property_contains`, as per [MSC3758](https://github.com/matrix-org/matrix-spec-proposals/pull/3758) and [MSC3966](https://github.com/matrix-org/matrix-spec-proposals/pull/3966). diff --git a/changelogs/client_server/newsfragments/1465.clarification b/changelogs/client_server/newsfragments/1465.clarification deleted file mode 100644 index ca5f3aea..00000000 --- a/changelogs/client_server/newsfragments/1465.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various typos throughout the specification. \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1474.clarification b/changelogs/client_server/newsfragments/1474.clarification deleted file mode 100644 index 9b874821..00000000 --- a/changelogs/client_server/newsfragments/1474.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix phrasing & typography in the registration endpoint description. Contributed by @HarHarLinks. diff --git a/changelogs/client_server/newsfragments/1475.feature b/changelogs/client_server/newsfragments/1475.feature deleted file mode 100644 index a59c2177..00000000 --- a/changelogs/client_server/newsfragments/1475.feature +++ /dev/null @@ -1 +0,0 @@ -Add `m.annotation` relations (reactions), as per [MSC2677](https://github.com/matrix-org/matrix-spec-proposals/pull/2677). diff --git a/changelogs/client_server/newsfragments/1479.clarification b/changelogs/client_server/newsfragments/1479.clarification deleted file mode 100644 index f1c4b178..00000000 --- a/changelogs/client_server/newsfragments/1479.clarification +++ /dev/null @@ -1 +0,0 @@ -Remove outdated text saying that `state_default` is 0 if there is no `m.room.power_levels` event in a room. diff --git a/changelogs/client_server/newsfragments/1485.clarification b/changelogs/client_server/newsfragments/1485.clarification deleted file mode 100644 index 0759c8cc..00000000 --- a/changelogs/client_server/newsfragments/1485.clarification +++ /dev/null @@ -1 +0,0 @@ -Remove fictitious `token` parameter on `/keys/query` endpoint. diff --git a/changelogs/client_server/newsfragments/1487.clarification b/changelogs/client_server/newsfragments/1487.clarification deleted file mode 100644 index f94a56f1..00000000 --- a/changelogs/client_server/newsfragments/1487.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix rendering of properties with a list of types. diff --git a/changelogs/client_server/newsfragments/1495.clarification b/changelogs/client_server/newsfragments/1495.clarification deleted file mode 100644 index 69672a4c..00000000 --- a/changelogs/client_server/newsfragments/1495.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify parts of the cross-signing signature upload request. diff --git a/changelogs/client_server/newsfragments/1499.feature b/changelogs/client_server/newsfragments/1499.feature deleted file mode 100644 index 1532d281..00000000 --- a/changelogs/client_server/newsfragments/1499.feature +++ /dev/null @@ -1 +0,0 @@ -Support asynchronous media uploads, as per [MSC2246](https://github.com/matrix-org/matrix-spec-proposals/pull/2246). diff --git a/changelogs/client_server/newsfragments/1499.new.1 b/changelogs/client_server/newsfragments/1499.new.1 deleted file mode 100644 index d7fbdbb6..00000000 --- a/changelogs/client_server/newsfragments/1499.new.1 +++ /dev/null @@ -1 +0,0 @@ -[`POST /_matrix/media/v1/create`](/client-server-api/#post_matrixmediav1create) \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1499.new.2 b/changelogs/client_server/newsfragments/1499.new.2 deleted file mode 100644 index 226cb2e4..00000000 --- a/changelogs/client_server/newsfragments/1499.new.2 +++ /dev/null @@ -1 +0,0 @@ -[`PUT /_matrix/media/v3/upload/{serverName}/{mediaId}`](/client-server-api/#put_matrixmediav3uploadservernamemediaid) \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1500.clarification b/changelogs/client_server/newsfragments/1500.clarification deleted file mode 100644 index ca5f3aea..00000000 --- a/changelogs/client_server/newsfragments/1500.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various typos throughout the specification. \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1501.clarification b/changelogs/client_server/newsfragments/1501.clarification deleted file mode 100644 index cdac3968..00000000 --- a/changelogs/client_server/newsfragments/1501.clarification +++ /dev/null @@ -1 +0,0 @@ -Remove the `dont_notify` and `coalesce` push rule actions, as per [MSC3987](https://github.com/matrix-org/matrix-spec-proposals/pull/3987). diff --git a/changelogs/client_server/newsfragments/1507.clarification b/changelogs/client_server/newsfragments/1507.clarification deleted file mode 100644 index c810cc8c..00000000 --- a/changelogs/client_server/newsfragments/1507.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify `m.location` scheme by partially reverting [f1f32d3](https://github.com/matrix-org/matrix-spec/commit/f1f32d3a15c325ee8aa9d2c6bafd96c38069bb53). Contributed by @HarHarLinks. diff --git a/changelogs/client_server/newsfragments/1508.feature b/changelogs/client_server/newsfragments/1508.feature deleted file mode 100644 index 324ca9a8..00000000 --- a/changelogs/client_server/newsfragments/1508.feature +++ /dev/null @@ -1 +0,0 @@ -Document the `m.mentions` property; the `.m.rule.is_user_mention` and `.m.rule.is_room_mention` push rules; and other notification behaviour, as per [MSC3952](https://github.com/matrix-org/matrix-spec-proposals/pull/3952). diff --git a/changelogs/client_server/newsfragments/1509.clarification b/changelogs/client_server/newsfragments/1509.clarification deleted file mode 100644 index ca5f3aea..00000000 --- a/changelogs/client_server/newsfragments/1509.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various typos throughout the specification. \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1510.feature b/changelogs/client_server/newsfragments/1510.feature deleted file mode 100644 index 1532d281..00000000 --- a/changelogs/client_server/newsfragments/1510.feature +++ /dev/null @@ -1 +0,0 @@ -Support asynchronous media uploads, as per [MSC2246](https://github.com/matrix-org/matrix-spec-proposals/pull/2246). diff --git a/changelogs/client_server/newsfragments/1511.feature b/changelogs/client_server/newsfragments/1511.feature deleted file mode 100644 index 295a23da..00000000 --- a/changelogs/client_server/newsfragments/1511.feature +++ /dev/null @@ -1 +0,0 @@ -Improve VoIP signaling, as per [MSC2746](https://github.com/matrix-org/matrix-spec-proposals/pull/2746). diff --git a/changelogs/client_server/newsfragments/1525.feature b/changelogs/client_server/newsfragments/1525.feature deleted file mode 100644 index 119ab2d6..00000000 --- a/changelogs/client_server/newsfragments/1525.feature +++ /dev/null @@ -1 +0,0 @@ -Changes to the server-side aggregation of `m.replace` (edit) events, as per [MSC3925](https://github.com/matrix-org/matrix-spec-proposals/pull/3925). diff --git a/changelogs/client_server/newsfragments/1526.feature b/changelogs/client_server/newsfragments/1526.feature deleted file mode 100644 index f26f96eb..00000000 --- a/changelogs/client_server/newsfragments/1526.feature +++ /dev/null @@ -1 +0,0 @@ -Update the scope of transaction IDs, as per [MSC3970](https://github.com/matrix-org/matrix-spec-proposals/pull/3970). diff --git a/changelogs/client_server/newsfragments/1529.feature b/changelogs/client_server/newsfragments/1529.feature deleted file mode 100644 index e53bdfd8..00000000 --- a/changelogs/client_server/newsfragments/1529.feature +++ /dev/null @@ -1 +0,0 @@ -Add an ability to redirect media downloads, as per [MSC3860](https://github.com/matrix-org/matrix-spec-proposals/pull/3860). diff --git a/changelogs/client_server/newsfragments/1530.feature b/changelogs/client_server/newsfragments/1530.feature deleted file mode 100644 index 90121439..00000000 --- a/changelogs/client_server/newsfragments/1530.feature +++ /dev/null @@ -1 +0,0 @@ -Add an ability to use an existing session to log in another, as per [MSC3882](https://github.com/matrix-org/matrix-spec-proposals/pull/3882). \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1530.new b/changelogs/client_server/newsfragments/1530.new deleted file mode 100644 index 94cb6715..00000000 --- a/changelogs/client_server/newsfragments/1530.new +++ /dev/null @@ -1 +0,0 @@ -[`POST /_matrix/client/v1/login/get_token`](/client-server-api/#post_matrixclientv1loginget_token) \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1531.feature b/changelogs/client_server/newsfragments/1531.feature deleted file mode 100644 index a59c2177..00000000 --- a/changelogs/client_server/newsfragments/1531.feature +++ /dev/null @@ -1 +0,0 @@ -Add `m.annotation` relations (reactions), as per [MSC2677](https://github.com/matrix-org/matrix-spec-proposals/pull/2677). diff --git a/changelogs/client_server/newsfragments/1535.clarification b/changelogs/client_server/newsfragments/1535.clarification deleted file mode 100644 index 805f6b56..00000000 --- a/changelogs/client_server/newsfragments/1535.clarification +++ /dev/null @@ -1 +0,0 @@ -Add missing `knock_restricted` join rule to the `m.room.join_rules` schema. diff --git a/changelogs/client_server/newsfragments/1540.feature b/changelogs/client_server/newsfragments/1540.feature deleted file mode 100644 index 295a23da..00000000 --- a/changelogs/client_server/newsfragments/1540.feature +++ /dev/null @@ -1 +0,0 @@ -Improve VoIP signaling, as per [MSC2746](https://github.com/matrix-org/matrix-spec-proposals/pull/2746). diff --git a/changelogs/identity_service/newsfragments/1486.clarification b/changelogs/identity_service/newsfragments/1486.clarification deleted file mode 100644 index c7372cc4..00000000 --- a/changelogs/identity_service/newsfragments/1486.clarification +++ /dev/null @@ -1 +0,0 @@ -Corrections to the response format of `/_matrix/identity/v2/store-invite`. diff --git a/changelogs/internal/newsfragments/1444.clarification b/changelogs/internal/newsfragments/1444.clarification deleted file mode 100644 index 1bbaa905..00000000 --- a/changelogs/internal/newsfragments/1444.clarification +++ /dev/null @@ -1 +0,0 @@ -Update references to Inter font. diff --git a/changelogs/internal/newsfragments/1446.clarification b/changelogs/internal/newsfragments/1446.clarification deleted file mode 100644 index fdc3d1fc..00000000 --- a/changelogs/internal/newsfragments/1446.clarification +++ /dev/null @@ -1 +0,0 @@ -Endpoint disclosures now hide everything but the URL. diff --git a/changelogs/internal/newsfragments/1457.clarification b/changelogs/internal/newsfragments/1457.clarification deleted file mode 100644 index 0abd9b6c..00000000 --- a/changelogs/internal/newsfragments/1457.clarification +++ /dev/null @@ -1 +0,0 @@ -Wrap $ref in allOf where other attributes are present, to improve OpenAPI compliance. diff --git a/changelogs/internal/newsfragments/1476.clarification b/changelogs/internal/newsfragments/1476.clarification deleted file mode 100644 index 340826b1..00000000 --- a/changelogs/internal/newsfragments/1476.clarification +++ /dev/null @@ -1 +0,0 @@ -Minor cleanups to the GitHub Actions workflows diff --git a/changelogs/internal/newsfragments/1488.clarification b/changelogs/internal/newsfragments/1488.clarification deleted file mode 100644 index 6411f662..00000000 --- a/changelogs/internal/newsfragments/1488.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix generation of anchors for additional properties. \ No newline at end of file diff --git a/changelogs/internal/newsfragments/1534.clarification b/changelogs/internal/newsfragments/1534.clarification deleted file mode 100644 index ca5f3aea..00000000 --- a/changelogs/internal/newsfragments/1534.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various typos throughout the specification. \ No newline at end of file diff --git a/changelogs/internal/newsfragments/1538.clarification b/changelogs/internal/newsfragments/1538.clarification deleted file mode 100644 index 3362118d..00000000 --- a/changelogs/internal/newsfragments/1538.clarification +++ /dev/null @@ -1 +0,0 @@ -Document more of the spec release timeline/process. \ No newline at end of file diff --git a/changelogs/room_versions/newsfragments/1484.clarification b/changelogs/room_versions/newsfragments/1484.clarification deleted file mode 100644 index b29c7ad3..00000000 --- a/changelogs/room_versions/newsfragments/1484.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarifications of event ID formats in early room versions diff --git a/changelogs/server_server/newsfragments/1431.clarification b/changelogs/server_server/newsfragments/1431.clarification deleted file mode 100644 index ca5f3aea..00000000 --- a/changelogs/server_server/newsfragments/1431.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various typos throughout the specification. \ No newline at end of file diff --git a/changelogs/server_server/newsfragments/1447.clarification b/changelogs/server_server/newsfragments/1447.clarification deleted file mode 100644 index ca5f3aea..00000000 --- a/changelogs/server_server/newsfragments/1447.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various typos throughout the specification. \ No newline at end of file diff --git a/changelogs/server_server/newsfragments/1454.clarification b/changelogs/server_server/newsfragments/1454.clarification deleted file mode 100644 index 559c1442..00000000 --- a/changelogs/server_server/newsfragments/1454.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix PDU examples by removing invalid OpenAPI reference to `examples/minimal_pdu.json`. diff --git a/changelogs/server_server/newsfragments/1466.clarification b/changelogs/server_server/newsfragments/1466.clarification deleted file mode 100644 index ca5f3aea..00000000 --- a/changelogs/server_server/newsfragments/1466.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various typos throughout the specification. \ No newline at end of file diff --git a/changelogs/server_server/newsfragments/1473.clarification b/changelogs/server_server/newsfragments/1473.clarification deleted file mode 100644 index d67095d8..00000000 --- a/changelogs/server_server/newsfragments/1473.clarification +++ /dev/null @@ -1 +0,0 @@ -Remove leftover `{key_id}` from `/_matrix/key/v2/server/`. diff --git a/changelogs/server_server/newsfragments/1518.clarification b/changelogs/server_server/newsfragments/1518.clarification deleted file mode 100644 index ca5f3aea..00000000 --- a/changelogs/server_server/newsfragments/1518.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various typos throughout the specification. \ No newline at end of file diff --git a/changelogs/server_server/newsfragments/1536.clarification b/changelogs/server_server/newsfragments/1536.clarification deleted file mode 100644 index 717dc43f..00000000 --- a/changelogs/server_server/newsfragments/1536.clarification +++ /dev/null @@ -1 +0,0 @@ -Remove extraneous `age_ts` field from the reference hash calculation section. \ No newline at end of file diff --git a/content/changelog/v1.7.md b/content/changelog/v1.7.md new file mode 100644 index 00000000..61ade090 --- /dev/null +++ b/content/changelog/v1.7.md @@ -0,0 +1,147 @@ +--- +date: 2023-05-25T09:47:21-06:00 +--- + + +## v1.7 + + + + +
Git commithttps://github.com/matrix-org/matrix-spec/tree/v1.7
Release dateMay 25, 2023
+ + +### Client-Server API + + +New Endpoints + + +- [`POST /_matrix/media/v1/create`](/client-server-api/#post_matrixmediav1create) ([#1499](https://github.com/matrix-org/matrix-spec/issues/1499)) +- [`PUT /_matrix/media/v3/upload/{serverName}/{mediaId}`](/client-server-api/#put_matrixmediav3uploadservernamemediaid) ([#1499](https://github.com/matrix-org/matrix-spec/issues/1499)) +- [`POST /_matrix/client/v1/login/get_token`](/client-server-api/#post_matrixclientv1loginget_token) ([#1530](https://github.com/matrix-org/matrix-spec/issues/1530)) + + +Backwards Compatible Changes + + +- Changes to the server-side aggregation of `m.replace` (edit) events, as per [MSC3925](https://github.com/matrix-org/matrix-spec-proposals/pull/3925). ([#1440](https://github.com/matrix-org/matrix-spec/issues/1440), [#1525](https://github.com/matrix-org/matrix-spec/issues/1525)) +- Add new push rule conditions `event_property_is` and `event_property_contains`, as per [MSC3758](https://github.com/matrix-org/matrix-spec-proposals/pull/3758) and [MSC3966](https://github.com/matrix-org/matrix-spec-proposals/pull/3966). ([#1464](https://github.com/matrix-org/matrix-spec/issues/1464)) +- Add `m.annotation` relations (reactions), as per [MSC2677](https://github.com/matrix-org/matrix-spec-proposals/pull/2677). ([#1475](https://github.com/matrix-org/matrix-spec/issues/1475), [#1531](https://github.com/matrix-org/matrix-spec/issues/1531)) +- Support asynchronous media uploads, as per [MSC2246](https://github.com/matrix-org/matrix-spec-proposals/pull/2246). ([#1499](https://github.com/matrix-org/matrix-spec/issues/1499), [#1510](https://github.com/matrix-org/matrix-spec/issues/1510)) +- Document the `m.mentions` property; the `.m.rule.is_user_mention` and `.m.rule.is_room_mention` push rules; and other notification behaviour, as per [MSC3952](https://github.com/matrix-org/matrix-spec-proposals/pull/3952). ([#1508](https://github.com/matrix-org/matrix-spec/issues/1508)) +- Improve VoIP signaling, as per [MSC2746](https://github.com/matrix-org/matrix-spec-proposals/pull/2746). ([#1511](https://github.com/matrix-org/matrix-spec/issues/1511), [#1540](https://github.com/matrix-org/matrix-spec/issues/1540)) +- Update the scope of transaction IDs, as per [MSC3970](https://github.com/matrix-org/matrix-spec-proposals/pull/3970). ([#1526](https://github.com/matrix-org/matrix-spec/issues/1526)) +- Add an ability to redirect media downloads, as per [MSC3860](https://github.com/matrix-org/matrix-spec-proposals/pull/3860). ([#1529](https://github.com/matrix-org/matrix-spec/issues/1529)) +- Add an ability to use an existing session to log in another, as per [MSC3882](https://github.com/matrix-org/matrix-spec-proposals/pull/3882). ([#1530](https://github.com/matrix-org/matrix-spec/issues/1530)) + + +Spec Clarifications + + +- Clarify the sections of the specification concerning aggregation of child events. ([#1424](https://github.com/matrix-org/matrix-spec/issues/1424)) +- Fix various typos throughout the specification. ([#1432](https://github.com/matrix-org/matrix-spec/issues/1432), [#1442](https://github.com/matrix-org/matrix-spec/issues/1442), [#1447](https://github.com/matrix-org/matrix-spec/issues/1447), [#1455](https://github.com/matrix-org/matrix-spec/issues/1455), [#1465](https://github.com/matrix-org/matrix-spec/issues/1465), [#1500](https://github.com/matrix-org/matrix-spec/issues/1500), [#1509](https://github.com/matrix-org/matrix-spec/issues/1509)) +- Clarify that reply chain fallback for threads might not be present. ([#1439](https://github.com/matrix-org/matrix-spec/issues/1439)) +- Clarify what event property the content-specific push rules match against. ([#1441](https://github.com/matrix-org/matrix-spec/issues/1441)) +- Clarify the semantics that make requests idempotent. ([#1449](https://github.com/matrix-org/matrix-spec/issues/1449)) +- Improve documentation of how clients use push rules. ([#1461](https://github.com/matrix-org/matrix-spec/issues/1461)) +- Clarify that servers should enforce a default `limit` on a filter if one is not specified. ([#1463](https://github.com/matrix-org/matrix-spec/issues/1463)) +- Disambiguate using property names with dots in them during push rule processing, as per [MSC3873](https://github.com/matrix-org/matrix-spec-proposals/pull/3873) and [MSC3980](https://github.com/matrix-org/matrix-spec-proposals/pull/3980). ([#1464](https://github.com/matrix-org/matrix-spec/issues/1464)) +- Fix phrasing & typography in the registration endpoint description. Contributed by @HarHarLinks. ([#1474](https://github.com/matrix-org/matrix-spec/issues/1474)) +- Remove outdated text saying that `state_default` is 0 if there is no `m.room.power_levels` event in a room. ([#1479](https://github.com/matrix-org/matrix-spec/issues/1479)) +- Remove fictitious `token` parameter on `/keys/query` endpoint. ([#1485](https://github.com/matrix-org/matrix-spec/issues/1485)) +- Fix rendering of properties with a list of types. ([#1487](https://github.com/matrix-org/matrix-spec/issues/1487)) +- Clarify parts of the cross-signing signature upload request. ([#1495](https://github.com/matrix-org/matrix-spec/issues/1495)) +- Remove the `dont_notify` and `coalesce` push rule actions, as per [MSC3987](https://github.com/matrix-org/matrix-spec-proposals/pull/3987). ([#1501](https://github.com/matrix-org/matrix-spec/issues/1501)) +- Clarify `m.location` scheme by partially reverting [f1f32d3](https://github.com/matrix-org/matrix-spec/commit/f1f32d3a15c325ee8aa9d2c6bafd96c38069bb53). Contributed by @HarHarLinks. ([#1507](https://github.com/matrix-org/matrix-spec/issues/1507)) +- Add missing `knock_restricted` join rule to the `m.room.join_rules` schema. ([#1535](https://github.com/matrix-org/matrix-spec/issues/1535)) + + +### Server-Server API + + +Spec Clarifications + + +- Fix various typos throughout the specification. ([#1431](https://github.com/matrix-org/matrix-spec/issues/1431), [#1447](https://github.com/matrix-org/matrix-spec/issues/1447), [#1466](https://github.com/matrix-org/matrix-spec/issues/1466), [#1518](https://github.com/matrix-org/matrix-spec/issues/1518)) +- Fix PDU examples by removing invalid OpenAPI reference to `examples/minimal_pdu.json`. ([#1454](https://github.com/matrix-org/matrix-spec/issues/1454)) +- Remove leftover `{key_id}` from `/_matrix/key/v2/server/`. ([#1473](https://github.com/matrix-org/matrix-spec/issues/1473)) +- Remove extraneous `age_ts` field from the reference hash calculation section. ([#1536](https://github.com/matrix-org/matrix-spec/issues/1536)) + + +### Application Service API + + +New Endpoints + + +- [`POST /_matrix/app/v1/ping`](/application-service-api/#post_matrixappv1ping) ([#1516](https://github.com/matrix-org/matrix-spec/issues/1516)) +- [`POST /_matrix/client/v1/appservice/{appserviceId}/ping`](/application-service-api/#post_matrixclientv1appserviceappserviceidping) ([#1516](https://github.com/matrix-org/matrix-spec/issues/1516)) + + +Backwards Compatible Changes + + +- Add homeserver->appservice ping mechanism, as per [MSC2659](https://github.com/matrix-org/matrix-spec-proposals/pull/2659). Contributed by @tulir at @beeper. ([#1516](https://github.com/matrix-org/matrix-spec/issues/1516), [#1541](https://github.com/matrix-org/matrix-spec/issues/1541)) + + +Spec Clarifications + + +- Fix various typos throughout the specification. ([#1447](https://github.com/matrix-org/matrix-spec/issues/1447)) + + +### Identity Service API + + +Spec Clarifications + + +- Corrections to the response format of `/_matrix/identity/v2/store-invite`. ([#1486](https://github.com/matrix-org/matrix-spec/issues/1486)) + + +### Push Gateway API + + +No significant changes. + + +### Room Versions + + +Spec Clarifications + + +- Clarifications of event ID formats in early room versions ([#1484](https://github.com/matrix-org/matrix-spec/issues/1484)) + + +### Appendices + + +Spec Clarifications + + +- Clarify that the term "Canonical JSON" is a specific thing within the Matrix specification. ([#1468](https://github.com/matrix-org/matrix-spec/issues/1468)) +- Remove references to groups. ([#1483](https://github.com/matrix-org/matrix-spec/issues/1483)) +- Clarifications of event ID formats in early room versions. ([#1484](https://github.com/matrix-org/matrix-spec/issues/1484)) + + +### Internal Changes/Tooling + + +Spec Clarifications + + +- Update references to Inter font. ([#1444](https://github.com/matrix-org/matrix-spec/issues/1444)) +- Endpoint disclosures now hide everything but the URL. ([#1446](https://github.com/matrix-org/matrix-spec/issues/1446)) +- Wrap $ref in allOf where other attributes are present, to improve OpenAPI compliance. ([#1457](https://github.com/matrix-org/matrix-spec/issues/1457)) +- Minor cleanups to the GitHub Actions workflows ([#1476](https://github.com/matrix-org/matrix-spec/issues/1476)) +- Fix generation of anchors for additional properties. ([#1488](https://github.com/matrix-org/matrix-spec/issues/1488)) +- Fix various typos throughout the specification. ([#1534](https://github.com/matrix-org/matrix-spec/issues/1534)) +- Document more of the spec release timeline/process. ([#1538](https://github.com/matrix-org/matrix-spec/issues/1538)) From 48ee5074899e5e17e1113c07956ffcd75fd0d599 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 25 May 2023 10:29:58 -0600 Subject: [PATCH 29/59] Build unstable --- config.toml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/config.toml b/config.toml index c36456cd..00757bd5 100644 --- a/config.toml +++ b/config.toml @@ -47,14 +47,14 @@ privacy_policy = "https://matrix.org/legal/privacy-notice" [params.version] # must be one of "unstable", "current", "historical" # this is used to decide whether to show a banner pointing to the current release -status = "stable" +status = "unstable" # A URL pointing to the latest, stable release of the spec. To be shown in the unstable version warning banner. current_version_url = "https://spec.matrix.org/latest" # The following is used when status = "stable", and is displayed in various UI elements on a released version # of the spec. CI will set these values here automatically when a release git tag (i.e `v1.5`) is created. -major = "1" -minor = "7" -release_date = "May 25, 2023" +# major = "1" +# minor = "7" +# release_date = "May 25, 2023" # User interface configuration [params.ui] From 48459dee9b949be023cffe65c280ef172cc54868 Mon Sep 17 00:00:00 2001 From: David Robertson Date: Tue, 30 May 2023 13:22:30 +0100 Subject: [PATCH 30/59] Only include titles in summaries (#1549) I previously made this change for HTTP endpoints in #1446. It seems there are other places where we have over-sized `` elements. I would like to elimintate those too, as grumbled about in https://github.com/matrix-org/matrix-spec/issues/1358#issuecomment-1325220859 and https://github.com/matrix-org/matrix-spec/issues/1352#issuecomment-1439033334 --- changelogs/internal/newsfragments/1549.clarification | 1 + layouts/partials/events/render-event.html | 4 ++-- layouts/shortcodes/definition.html | 3 ++- layouts/shortcodes/event-fields.html | 2 +- 4 files changed, 6 insertions(+), 4 deletions(-) create mode 100644 changelogs/internal/newsfragments/1549.clarification diff --git a/changelogs/internal/newsfragments/1549.clarification b/changelogs/internal/newsfragments/1549.clarification new file mode 100644 index 00000000..67dbd67e --- /dev/null +++ b/changelogs/internal/newsfragments/1549.clarification @@ -0,0 +1 @@ +Disclosure sections now only display their title when collapsed. diff --git a/layouts/partials/events/render-event.html b/layouts/partials/events/render-event.html index 369a80db..0f4d543d 100644 --- a/layouts/partials/events/render-event.html +++ b/layouts/partials/events/render-event.html @@ -25,6 +25,8 @@ {{ with .title }}{{ . | markdownify }}{{ else }}{{ $event_name }}{{ end }} + +
{{ if (index $event_data "x-addedInMatrixVersion") }} @@ -36,8 +38,6 @@ {{ $event_data.description | markdownify }} - - {{ $state_key := index $event_data.properties "state_key" }} diff --git a/layouts/shortcodes/definition.html b/layouts/shortcodes/definition.html index 2d03179e..67cd63c0 100644 --- a/layouts/shortcodes/definition.html +++ b/layouts/shortcodes/definition.html @@ -39,6 +39,8 @@ {{ $definition.title }} + +
{{ if (index $definition "x-addedInMatrixVersion") }} @@ -47,7 +49,6 @@ {{ $definition.description | markdownify }} - {{ $additional_types := partial "json-schema/resolve-additional-types" (dict "schema" $definition "name" (printf "\"%s\"" $path)) }} {{ $additional_types = uniq $additional_types }} diff --git a/layouts/shortcodes/event-fields.html b/layouts/shortcodes/event-fields.html index 7120f87f..91e2faf2 100644 --- a/layouts/shortcodes/event-fields.html +++ b/layouts/shortcodes/event-fields.html @@ -26,12 +26,12 @@

{{ humanize $event.title }}

+
{{ $event.description | markdownify }} - {{ $event = merge $event (dict "title" "") }} From dd6af5bfb14ef4f385d1b2cc9d960042a2a7124e Mon Sep 17 00:00:00 2001 From: Eric Eastwood Date: Wed, 31 May 2023 04:50:21 -0500 Subject: [PATCH 31/59] Document why `/state_ids` can respond with a 404 (#1521) --- .../server_server/newsfragments/1521.clarification | 1 + data/api/server-server/events.yaml | 11 +++++++++++ 2 files changed, 12 insertions(+) create mode 100644 changelogs/server_server/newsfragments/1521.clarification diff --git a/changelogs/server_server/newsfragments/1521.clarification b/changelogs/server_server/newsfragments/1521.clarification new file mode 100644 index 00000000..6c1ebf9d --- /dev/null +++ b/changelogs/server_server/newsfragments/1521.clarification @@ -0,0 +1 @@ +Document why `/state_ids` can respond with a 404. diff --git a/data/api/server-server/events.yaml b/data/api/server-server/events.yaml index 427978fb..6d7ca45a 100644 --- a/data/api/server-server/events.yaml +++ b/data/api/server-server/events.yaml @@ -137,6 +137,17 @@ paths: type: string example: ["$an_event:example.org"] required: ['auth_chain_ids', 'pdu_ids'] + 404: + description: |- + The given `event_id` was not found or the server doesn't know about the state at + that event to return anything useful. + examples: + application/json: { + "errcode": "M_NOT_FOUND", + "error": "Could not find event $Rqnc-F-dvnEYJTyHq_iKxU2bZ1CI92-kuZq3a5lr5Zg" + } + schema: + "$ref": "../client-server/definitions/errors/error.yaml" "/event/{eventId}": get: summary: Get a single event From c64a616d54dc62030e7637582d3a58d14f13f118 Mon Sep 17 00:00:00 2001 From: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> Date: Wed, 31 May 2023 11:30:51 +0100 Subject: [PATCH 32/59] Update the changelog entry checker script to check newsfragment file extension (#1542) --- changelogs/internal/newsfragments/1542.clarification | 1 + scripts/check-newsfragments | 7 +++++++ 2 files changed, 8 insertions(+) create mode 100644 changelogs/internal/newsfragments/1542.clarification diff --git a/changelogs/internal/newsfragments/1542.clarification b/changelogs/internal/newsfragments/1542.clarification new file mode 100644 index 00000000..422a4eef --- /dev/null +++ b/changelogs/internal/newsfragments/1542.clarification @@ -0,0 +1 @@ +Update the CI to validate the file extension of changelog entries. \ No newline at end of file diff --git a/scripts/check-newsfragments b/scripts/check-newsfragments index ddba0d28..242b46d8 100755 --- a/scripts/check-newsfragments +++ b/scripts/check-newsfragments @@ -21,6 +21,12 @@ matched=0 while read f; do basename=$(basename $f) dirname=$(dirname $f) + extension="${f##*.}" + + # check that each changelog file has a known extension + if ! [[ "$extension" == "new" || "$extension" == "feature" || "$extension" == "clarification" || "$extension" == "breaking" || "$extension" == "deprecation" ]]; then + echo -e "\e[31mERROR: newsfragment $f does not have one of the required file extensions for a changelog entry: .new, .feature, .clarification, .breaking, .deprecation\e[39m" >&2 + fi # check that there is nothing that looks like a newsfile outside one of the # expected directories. @@ -31,6 +37,7 @@ while read f; do # see if this newsfile corresponds to the right PR [[ -n "$pr" && "$basename" == "$pr".* ]] && matched=1 fi +# find all files in the 'changelogs/*/' dirs that are in the form `.` done < <(find changelogs -regex '.*/[0-9]+\.[^/]+$') if [[ -n "$pr" && "$matched" -eq 0 ]]; then From 45b6aaf07ae119a0e284192d6de8a13cf668d06f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Wed, 7 Jun 2023 14:16:29 +0200 Subject: [PATCH 33/59] Upgrade Swagger data to OpenAPI 3.1 (#1310) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- .../internal/newsfragments/1310.feature | 1 + data/api/application-service/ping.yaml | 75 +- data/api/application-service/protocols.yaml | 397 +++-- data/api/application-service/query_room.yaml | 104 +- data/api/application-service/query_user.yaml | 104 +- .../api/application-service/transactions.yaml | 89 +- data/api/client-server/account-data.yaml | 395 +++-- data/api/client-server/admin.yaml | 156 +- .../client-server/administrative_contact.yaml | 735 +++++---- data/api/client-server/appservice_ping.yaml | 232 +-- .../appservice_room_directory.yaml | 92 +- data/api/client-server/banning.yaml | 186 ++- data/api/client-server/capabilities.yaml | 169 +- data/api/client-server/content-repo.yaml | 931 ++++++----- data/api/client-server/create_room.yaml | 379 ++--- data/api/client-server/cross_signing.yaml | 363 +++-- .../definitions/push_condition.yaml | 2 +- .../client-server/definitions/push_rule.yaml | 6 +- data/api/client-server/device_management.yaml | 297 ++-- data/api/client-server/directory.yaml | 344 ++-- data/api/client-server/event_context.yaml | 193 +-- data/api/client-server/filter.yaml | 267 ++-- data/api/client-server/inviting.yaml | 130 +- data/api/client-server/joining.yaml | 235 +-- data/api/client-server/key_backup.yaml | 1386 +++++++++-------- data/api/client-server/keys.yaml | 791 +++++----- data/api/client-server/kicking.yaml | 102 +- data/api/client-server/knocking.yaml | 146 +- data/api/client-server/leaving.yaml | 140 +- data/api/client-server/list_joined_rooms.yaml | 74 +- data/api/client-server/list_public_rooms.yaml | 281 ++-- data/api/client-server/login.yaml | 417 ++--- data/api/client-server/login_token.yaml | 132 +- data/api/client-server/logout.yaml | 56 +- .../api/client-server/message_pagination.yaml | 224 +-- data/api/client-server/notifications.yaml | 197 +-- data/api/client-server/old_sync.yaml | 493 +++--- data/api/client-server/openid.yaml | 81 +- data/api/client-server/peeking_events.yaml | 131 +- data/api/client-server/presence.yaml | 190 ++- data/api/client-server/profile.yaml | 286 ++-- data/api/client-server/pusher.yaml | 466 +++--- data/api/client-server/pushrules.yaml | 1080 +++++++------ data/api/client-server/read_markers.yaml | 119 +- data/api/client-server/receipts.yaml | 132 +- data/api/client-server/redaction.yaml | 94 +- data/api/client-server/refresh.yaml | 145 +- data/api/client-server/registration.yaml | 840 +++++----- .../client-server/registration_tokens.yaml | 97 +- data/api/client-server/relations.yaml | 463 +++--- data/api/client-server/report_content.yaml | 90 +- .../room_event_by_timestamp.yaml | 134 +- data/api/client-server/room_initial_sync.yaml | 271 ++-- data/api/client-server/room_send.yaml | 98 +- data/api/client-server/room_state.yaml | 131 +- data/api/client-server/room_upgrades.yaml | 133 +- data/api/client-server/rooms.yaml | 371 +++-- data/api/client-server/search.yaml | 610 ++++---- data/api/client-server/space_hierarchy.yaml | 269 ++-- .../api/client-server/sso_login_redirect.yaml | 50 +- data/api/client-server/sync.yaml | 817 +++++----- data/api/client-server/tags.yaml | 220 +-- .../api/client-server/third_party_lookup.yaml | 225 +-- .../client-server/third_party_membership.yaml | 131 +- data/api/client-server/threads_list.yaml | 176 ++- data/api/client-server/to_device.yaml | 104 +- data/api/client-server/typing.yaml | 98 +- data/api/client-server/users.yaml | 163 +- data/api/client-server/versions.yaml | 86 +- data/api/client-server/voip.yaml | 111 +- data/api/client-server/wellknown.yaml | 36 +- data/api/client-server/whoami.yaml | 149 +- data/api/identity/v2_associations.yaml | 512 +++--- data/api/identity/v2_auth.yaml | 186 ++- data/api/identity/v2_email_associations.yaml | 239 +-- data/api/identity/v2_invitation_signing.yaml | 184 ++- data/api/identity/v2_lookup.yaml | 231 +-- data/api/identity/v2_phone_associations.yaml | 236 +-- data/api/identity/v2_ping.yaml | 40 +- data/api/identity/v2_pubkey.yaml | 172 +- data/api/identity/v2_store_invite.yaml | 308 ++-- data/api/identity/v2_terms.yaml | 223 +-- data/api/identity/versions.yaml | 64 +- data/api/push-gateway/push_notifier.yaml | 378 ++--- data/api/server-server/backfill.yaml | 168 +- .../definitions/unsigned_pdu_base.yaml | 58 +- data/api/server-server/event_auth.yaml | 86 +- data/api/server-server/events.yaml | 302 ++-- data/api/server-server/invites-v1.yaml | 257 +-- data/api/server-server/invites-v2.yaml | 278 ++-- data/api/server-server/joins-v1.yaml | 560 +++---- data/api/server-server/joins-v2.yaml | 398 ++--- data/api/server-server/keys_query.yaml | 139 +- data/api/server-server/keys_server.yaml | 35 +- data/api/server-server/knocks.yaml | 493 +++--- data/api/server-server/leaving-v1.yaml | 360 +++-- data/api/server-server/leaving-v2.yaml | 181 ++- data/api/server-server/openid.yaml | 78 +- data/api/server-server/public_rooms.yaml | 281 ++-- data/api/server-server/query.yaml | 206 +-- data/api/server-server/space_hierarchy.yaml | 338 ++-- .../api/server-server/third_party_invite.yaml | 547 +++---- data/api/server-server/transactions.yaml | 137 +- data/api/server-server/user_devices.yaml | 176 ++- data/api/server-server/user_keys.yaml | 440 +++--- data/api/server-server/version.yaml | 72 +- data/api/server-server/wellknown.yaml | 72 +- .../json-schema/resolve-additional-types.html | 4 +- .../partials/openapi/render-object-table.html | 11 +- .../partials/openapi/render-operation.html | 2 +- .../partials/openapi/render-parameters.html | 8 +- layouts/partials/openapi/render-request.html | 52 +- .../partials/openapi/render-responses.html | 23 +- layouts/shortcodes/http-api.html | 2 +- scripts/dump-swagger.py | 22 +- scripts/package-lock.json | 294 ++-- scripts/package.json | 4 +- scripts/validator.js | 16 +- 118 files changed, 15064 insertions(+), 12727 deletions(-) create mode 100644 changelogs/internal/newsfragments/1310.feature diff --git a/changelogs/internal/newsfragments/1310.feature b/changelogs/internal/newsfragments/1310.feature new file mode 100644 index 00000000..9aaa18b6 --- /dev/null +++ b/changelogs/internal/newsfragments/1310.feature @@ -0,0 +1 @@ +Upgrade Swagger data to OpenAPI 3.1. diff --git a/data/api/application-service/ping.yaml b/data/api/application-service/ping.yaml index 18682f11..291f96fa 100644 --- a/data/api/application-service/ping.yaml +++ b/data/api/application-service/ping.yaml @@ -11,21 +11,12 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Application Service API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/app/v1 -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Application Service API + version: 1.0.0 paths: - "/ping": + /ping: post: x-addedInMatrixVersion: "1.7" summary: Ping the application service @@ -39,25 +30,43 @@ paths: operationId: ping security: - homeserverAccessToken: [] - parameters: - - in: body - name: body - description: Ping body with optional transaction ID. - schema: - type: object - example: { - "transaction_id": "mautrix-go_1683636478256400935_123" - } - properties: - transaction_id: - type: string - description: |- - A transaction ID for the ping, copied directly from the - `POST /_matrix/client/v1/appservice/{appserviceId}/ping` call. + requestBody: + content: + application/json: + schema: + type: object + example: { + "transaction_id": "mautrix-go_1683636478256400935_123" + } + properties: + transaction_id: + type: string + description: |- + A transaction ID for the ping, copied directly from the + `POST /_matrix/client/v1/appservice/{appserviceId}/ping` call. + description: Ping body with optional transaction ID. responses: - 200: + "200": description: The provided `hs_token` is valid and the ping request was successful. - examples: - application/json: {} - schema: - type: object + content: + application/json: + schema: + type: object + examples: + response: + value: {} +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/app/v1 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/application-service/protocols.yaml b/data/api/application-service/protocols.yaml index 47f62b8f..59dff5b0 100644 --- a/data/api/application-service/protocols.yaml +++ b/data/api/application-service/protocols.yaml @@ -11,25 +11,15 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Application Service API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/app/v1 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Application Service API + version: 1.0.0 paths: "/thirdparty/protocol/{protocol}": get: - summary: Retrieve metadata about a specific protocol that the application service supports. + summary: Retrieve metadata about a specific protocol that the application + service supports. description: |- This API is called by the homeserver when it wants to present clients with specific information about the various third-party networks that @@ -40,42 +30,53 @@ paths: parameters: - in: path name: protocol - type: string description: The protocol ID. required: true - x-example: "irc" - responses: - 200: - description: The protocol was found and metadata returned. + example: irc schema: - $ref: definitions/protocol.yaml - 401: + type: string + responses: + "200": + description: The protocol was found and metadata returned. + content: + application/json: + schema: + $ref: definitions/protocol.yaml + "401": description: |- The homeserver has not supplied credentials to the application service. Optional error information can be included in the body of this response. - examples: - application/json: { - "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" - } - schema: - $ref: ../client-server/definitions/errors/error.yaml - 403: - description: |- - The credentials supplied by the homeserver were rejected. - examples: - application/json: { - "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" - } - schema: - $ref: ../client-server/definitions/errors/error.yaml - 404: + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" + } + "403": + description: The credentials supplied by the homeserver were rejected. + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" + } + "404": description: No protocol was found with the given path. - examples: - application/json: { - "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" - } - schema: - $ref: ../client-server/definitions/errors/error.yaml + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" + } "/thirdparty/user/{protocol}": get: summary: Retrieve the Matrix User ID of a corresponding third-party user. @@ -89,102 +90,126 @@ paths: parameters: - in: path name: protocol - type: string description: The protocol ID. required: true - x-example: irc + example: irc + schema: + type: string - in: query name: fields... - type: string description: |- One or more custom fields that are passed to the application service to help identify the user. - responses: - 200: - description: The Matrix User IDs found with the given parameters. schema: - $ref: definitions/user_batch.yaml - 401: + type: string + responses: + "200": + description: The Matrix User IDs found with the given parameters. + content: + application/json: + schema: + $ref: definitions/user_batch.yaml + "401": description: |- The homeserver has not supplied credentials to the application service. Optional error information can be included in the body of this response. - examples: - application/json: { - "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" - } - schema: - $ref: ../client-server/definitions/errors/error.yaml - 403: - description: |- - The credentials supplied by the homeserver were rejected. - examples: - application/json: { - "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" - } - schema: - $ref: ../client-server/definitions/errors/error.yaml - 404: + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" + } + "403": + description: The credentials supplied by the homeserver were rejected. + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" + } + "404": description: No users were found with the given parameters. - examples: - application/json: { - "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" - } - schema: - $ref: ../client-server/definitions/errors/error.yaml + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" + } "/thirdparty/location/{protocol}": get: summary: Retrieve Matrix-side portal rooms leading to a third-party location. - description: |- - Retrieve a list of Matrix portal rooms that lead to the matched third-party location. + description: Retrieve a list of Matrix portal rooms that lead to the matched + third-party location. operationId: queryLocationByProtocol security: - homeserverAccessToken: [] parameters: - in: path name: protocol - type: string description: The protocol ID. required: true - x-example: irc + example: irc + schema: + type: string - in: query name: fields... - type: string description: |- One or more custom fields that are passed to the application service to help identify the third-party location. - responses: - 200: - description: At least one portal room was found. schema: - $ref: definitions/location_batch.yaml - 401: + type: string + responses: + "200": + description: At least one portal room was found. + content: + application/json: + schema: + $ref: definitions/location_batch.yaml + "401": description: |- The homeserver has not supplied credentials to the application service. Optional error information can be included in the body of this response. - examples: - application/json: { - "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" - } - schema: - $ref: ../client-server/definitions/errors/error.yaml - 403: - description: |- - The credentials supplied by the homeserver were rejected. - examples: - application/json: { - "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" - } - schema: - $ref: ../client-server/definitions/errors/error.yaml - 404: + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" + } + "403": + description: The credentials supplied by the homeserver were rejected. + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" + } + "404": description: No mappings were found with the given parameters. - examples: - application/json: { - "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" - } - schema: - $ref: ../client-server/definitions/errors/error.yaml - "/thirdparty/location": + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" + } + /thirdparty/location: get: summary: Reverse-lookup third-party locations given a Matrix room alias. description: |- @@ -196,84 +221,118 @@ paths: parameters: - in: query name: alias - type: string description: The Matrix room alias to look up. - responses: - 200: - description: |- - All found third-party locations. schema: - $ref: definitions/location_batch.yaml - 401: + type: string + responses: + "200": + description: All found third-party locations. + content: + application/json: + schema: + $ref: definitions/location_batch.yaml + "401": description: |- The homeserver has not supplied credentials to the application service. Optional error information can be included in the body of this response. - examples: - application/json: { - "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" - } - schema: - $ref: ../client-server/definitions/errors/error.yaml - 403: - description: |- - The credentials supplied by the homeserver were rejected. - examples: - application/json: { - "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" - } - schema: - $ref: ../client-server/definitions/errors/error.yaml - 404: + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" + } + "403": + description: The credentials supplied by the homeserver were rejected. + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" + } + "404": description: No mappings were found with the given parameters. - examples: - application/json: { - "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" - } - schema: - $ref: ../client-server/definitions/errors/error.yaml - "/thirdparty/user": + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" + } + /thirdparty/user: get: summary: Reverse-lookup third-party users given a Matrix User ID. - description: |- - Retrieve an array of third-party users from a Matrix User ID. + description: Retrieve an array of third-party users from a Matrix User ID. operationId: queryUserByID security: - homeserverAccessToken: [] parameters: - - in: query + - in: query name: userid - type: string description: The Matrix User ID to look up. - responses: - 200: - description: |- - An array of third-party users. schema: - $ref: definitions/user_batch.yaml - 401: + type: string + responses: + "200": + description: An array of third-party users. + content: + application/json: + schema: + $ref: definitions/user_batch.yaml + "401": description: |- The homeserver has not supplied credentials to the application service. Optional error information can be included in the body of this response. - examples: - application/json: { - "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" - } - schema: - $ref: ../client-server/definitions/errors/error.yaml - 403: - description: |- - The credentials supplied by the homeserver were rejected. - examples: - application/json: { - "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" - } - schema: - $ref: ../client-server/definitions/errors/error.yaml - 404: + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" + } + "403": + description: The credentials supplied by the homeserver were rejected. + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" + } + "404": description: No mappings were found with the given parameters. - examples: - application/json: { - "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" - } - schema: - $ref: ../client-server/definitions/errors/error.yaml + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" + } +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/app/v1 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/application-service/query_room.yaml b/data/api/application-service/query_room.yaml index 6ddc6234..b5280e39 100644 --- a/data/api/application-service/query_room.yaml +++ b/data/api/application-service/query_room.yaml @@ -12,21 +12,10 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Application Service API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/app/v1 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Application Service API + version: 1.0.0 paths: "/rooms/{roomAlias}": get: @@ -43,48 +32,75 @@ paths: parameters: - in: path name: roomAlias - type: string description: The room alias being queried. required: true - x-example: "#magicforest:example.com" + example: "#magicforest:example.com" + schema: + type: string responses: - 200: + "200": description: |- The application service indicates that this room alias exists. The application service MUST have created a room and associated it with the queried room alias using the client-server API. Additional information about the room such as its name and topic can be set before responding. - examples: - application/json: {} - schema: - type: object - 401: + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "401": description: |- The homeserver has not supplied credentials to the application service. Optional error information can be included in the body of this response. - examples: - application/json: { - "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" - } - schema: - $ref: ../client-server/definitions/errors/error.yaml - 403: - description: |- - The credentials supplied by the homeserver were rejected. - examples: - application/json: { - "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" - } - schema: - $ref: ../client-server/definitions/errors/error.yaml - 404: + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" + } + "403": + description: The credentials supplied by the homeserver were rejected. + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" + } + "404": description: |- The application service indicates that this room alias does not exist. Optional error information can be included in the body of this response. - examples: - application/json: { - "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" - } - schema: - $ref: ../client-server/definitions/errors/error.yaml + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" + } +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/app/v1 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/application-service/query_user.yaml b/data/api/application-service/query_user.yaml index f8fc4ef1..09503be1 100644 --- a/data/api/application-service/query_user.yaml +++ b/data/api/application-service/query_user.yaml @@ -12,21 +12,10 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Application Service API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/app/v1 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Application Service API + version: 1.0.0 paths: "/users/{userId}": get: @@ -43,45 +32,72 @@ paths: parameters: - in: path name: userId - type: string description: The user ID being queried. required: true - x-example: "@alice:example.com" + example: "@alice:example.com" + schema: + type: string responses: - 200: + "200": description: |- The application service indicates that this user exists. The application service MUST create the user using the client-server API. - examples: - application/json: {} - schema: - type: object - 401: + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "401": description: |- The homeserver has not supplied credentials to the application service. Optional error information can be included in the body of this response. - examples: - application/json: { - "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" - } - schema: - $ref: ../client-server/definitions/errors/error.yaml - 403: - description: |- - The credentials supplied by the homeserver were rejected. - examples: - application/json: { - "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" - } - schema: - $ref: ../client-server/definitions/errors/error.yaml - 404: + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" + } + "403": + description: The credentials supplied by the homeserver were rejected. + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" + } + "404": description: |- The application service indicates that this user does not exist. Optional error information can be included in the body of this response. - examples: - application/json: { - "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" - } - schema: - $ref: ../client-server/definitions/errors/error.yaml + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" + } +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/app/v1 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/application-service/transactions.yaml b/data/api/application-service/transactions.yaml index de082904..473def4b 100644 --- a/data/api/application-service/transactions.yaml +++ b/data/api/application-service/transactions.yaml @@ -12,19 +12,10 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Application Service API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/app/v1 -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Application Service API + version: 1.0.0 paths: "/transactions/{txnId}": put: @@ -42,35 +33,59 @@ paths: parameters: - in: path name: txnId - type: string description: |- The transaction ID for this set of events. Homeservers generate these IDs and they are used to ensure idempotency of requests. required: true - x-example: "35" - - in: body - name: body - description: Transaction information + example: "35" schema: - type: object - example: { - "events": [ - {"$ref": "../../event-schemas/examples/m.room.member.yaml"}, - {"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"} - ] - } - properties: - events: - type: array - description: |- - A list of events, formatted as per the Client-Server API. - items: - $ref: "../client-server/definitions/client_event.yaml" - required: ["events"] + type: string + requestBody: + content: + application/json: + schema: + type: object + example: { + "events": [ + { + "$ref": "../../event-schemas/examples/m.room.member.yaml" + }, + { + "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" + } + ] + } + properties: + events: + type: array + description: A list of events, formatted as per the Client-Server API. + items: + $ref: ../client-server/definitions/client_event.yaml + required: + - events + description: Transaction information responses: - 200: + "200": description: The transaction was processed successfully. - examples: - application/json: {} - schema: - type: object + content: + application/json: + schema: + type: object + examples: + response: + value: {} +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/app/v1 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/account-data.yaml b/data/api/client-server/account-data.yaml index 57e78c71..b4526198 100644 --- a/data/api/client-server/account-data.yaml +++ b/data/api/client-server/account-data.yaml @@ -11,21 +11,10 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server Client Config API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server Client Config API + version: 1.0.0 paths: "/user/{userId}/account_data/{type}": put: @@ -40,71 +29,85 @@ paths: - accessToken: [] parameters: - in: path - type: string name: userId required: true description: |- The ID of the user to set account data for. The access token must be authorized to make requests for this user ID. - x-example: "@alice:example.com" + example: "@alice:example.com" + schema: + type: string - in: path - type: string name: type required: true description: |- The event type of the account data to set. Custom types should be namespaced to avoid clashes. - x-example: "org.example.custom.config" - - in: body - name: content - required: true - description: |- - The content of the account data. + example: org.example.custom.config schema: - type: object - example: { - "custom_account_data_key": "custom_config_value"} + type: string + requestBody: + content: + application/json: + schema: + type: object + example: { + "custom_account_data_key": "custom_config_value" + } + description: The content of the account data. + required: true responses: - 200: - description: - The account data was successfully added. - examples: - application/json: {} - schema: - type: object - 400: + "200": + description: The account data was successfully added. + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "400": description: |- The request body is not a JSON object. Errcode: `M_BAD_JSON` or `M_NOT_JSON`. - examples: - application/json: { - "errcode": "M_NOT_JSON", - "error": "Content must be a JSON object." - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" - 403: + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_JSON", + "error": "Content must be a JSON object." + } + "403": description: |- The access token provided is not authorized to modify this user's account data. Errcode: `M_FORBIDDEN`. - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "Cannot add account data for other users." - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" - 405: - examples: - application/json: { - "errcode": "M_BAD_JSON", - "error": "Cannot set m.fully_read through this API." - } + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "Cannot add account data for other users." + } + "405": description: |- This `type` of account data is controlled by the server; it cannot be modified by clients. Errcode: `M_BAD_JSON`. - schema: - $ref: "../client-server/definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_BAD_JSON", + "error": "Cannot set m.fully_read through this API." + } tags: - User data get: @@ -117,51 +120,61 @@ paths: - accessToken: [] parameters: - in: path - type: string name: userId required: true description: |- The ID of the user to get account data for. The access token must be authorized to make requests for this user ID. - x-example: "@alice:example.com" + example: "@alice:example.com" + schema: + type: string - in: path - type: string name: type required: true description: |- The event type of the account data to get. Custom types should be namespaced to avoid clashes. - x-example: "org.example.custom.config" - responses: - 200: - description: - The account data content for the given type. + example: org.example.custom.config schema: - type: object - example: { - "custom_account_data_key": "custom_config_value"} - 403: + type: string + responses: + "200": + description: The account data content for the given type. + content: + application/json: + schema: + type: object + example: { + "custom_account_data_key": "custom_config_value" + } + "403": description: |- The access token provided is not authorized to retrieve this user's account data. Errcode: `M_FORBIDDEN`. - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "Cannot add account data for other users." - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" - 404: + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "Cannot add account data for other users." + } + "404": description: |- No account data has been provided for this user with the given `type`. Errcode: `M_NOT_FOUND`. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Account data not found." - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Account data not found." + } tags: - User data "/user/{userId}/rooms/{roomId}/account_data/{type}": @@ -176,79 +189,93 @@ paths: - accessToken: [] parameters: - in: path - type: string name: userId required: true description: |- The ID of the user to set account data for. The access token must be authorized to make requests for this user ID. - x-example: "@alice:example.com" + example: "@alice:example.com" + schema: + type: string - in: path - type: string name: roomId required: true - description: |- - The ID of the room to set account data on. - x-example: "!726s6s6q:example.com" + description: The ID of the room to set account data on. + example: "!726s6s6q:example.com" + schema: + type: string - in: path - type: string name: type required: true description: |- The event type of the account data to set. Custom types should be namespaced to avoid clashes. - x-example: "org.example.custom.room.config" - - in: body - name: content - required: true - description: |- - The content of the account data. + example: org.example.custom.room.config schema: - type: object - example: { - "custom_account_data_key": "custom_account_data_value"} + type: string + requestBody: + content: + application/json: + schema: + type: object + example: { + "custom_account_data_key": "custom_account_data_value" + } + description: The content of the account data. + required: true responses: - 200: - description: - The account data was successfully added. - examples: - application/json: {} - schema: - type: object - 400: + "200": + description: The account data was successfully added. + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "400": description: |- The request body is not a JSON object (errcode `M_BAD_JSON` or `M_NOT_JSON`), or the given `roomID` is not a valid room ID (errcode `M_INVALID_PARAM`). - examples: - application/json: { - "errcode": "M_NOT_JSON", - "error": "Content must be a JSON object." - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" - 403: + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_JSON", + "error": "Content must be a JSON object." + } + "403": description: |- The access token provided is not authorized to modify this user's account data. Errcode: `M_FORBIDDEN`. - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "Cannot add account data for other users." - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" - 405: + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "Cannot add account data for other users." + } + "405": description: |- This `type` of account data is controlled by the server; it cannot be modified by clients. Errcode: `M_BAD_JSON`. - examples: - application/json: { - "errcode": "M_BAD_JSON", - "error": "Cannot set m.fully_read through this API." - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_BAD_JSON", + "error": "Cannot set m.fully_read through this API." + } tags: - User data get: @@ -261,65 +288,93 @@ paths: - accessToken: [] parameters: - in: path - type: string name: userId required: true description: |- The ID of the user to get account data for. The access token must be authorized to make requests for this user ID. - x-example: "@alice:example.com" + example: "@alice:example.com" + schema: + type: string - in: path - type: string name: roomId required: true - description: |- - The ID of the room to get account data for. - x-example: "!726s6s6q:example.com" + description: The ID of the room to get account data for. + example: "!726s6s6q:example.com" + schema: + type: string - in: path - type: string name: type required: true description: |- The event type of the account data to get. Custom types should be namespaced to avoid clashes. - x-example: "org.example.custom.room.config" - responses: - 200: - description: - The account data content for the given type. + example: org.example.custom.room.config schema: - type: object - example: { - "custom_account_data_key": "custom_config_value"} - 400: - description: |- - The given `roomID` is not a valid room ID. Errcode: `M_INVALID_PARAM`. - examples: - application/json: { - "errcode": "M_INVALID_PARAM", - "error": "@notaroomid:example.org is not a valid room ID." - } - 403: + type: string + responses: + "200": + description: The account data content for the given type. + content: + application/json: + schema: + type: object + example: { + "custom_account_data_key": "custom_config_value" + } + "400": + description: "The given `roomID` is not a valid room ID. Errcode: + `M_INVALID_PARAM`." + content: + application/json: + examples: + response: + value: { + "errcode": "M_INVALID_PARAM", + "error": "@notaroomid:example.org is not a valid room ID." + } + "403": description: |- The access token provided is not authorized to retrieve this user's account data. Errcode: `M_FORBIDDEN`. - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "Cannot add account data for other users." - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" - 404: + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "Cannot add account data for other users." + } + "404": description: |- No account data has been provided for this user and this room with the given `type`. Errcode: `M_NOT_FOUND`. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Room account data not found." - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Room account data not found." + } tags: - User data +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/admin.yaml b/data/api/client-server/admin.yaml index 403be39f..ec92eadb 100644 --- a/data/api/client-server/admin.yaml +++ b/data/api/client-server/admin.yaml @@ -11,21 +11,10 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server Administration API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server Administration API + version: 1.0.0 paths: "/admin/whois/{userId}": get: @@ -41,75 +30,94 @@ paths: - accessToken: [] parameters: - in: path - type: string name: userId description: The user to look up. required: true - x-example: "@peter:rabbit.rocks" + example: "@peter:rabbit.rocks" + schema: + type: string responses: - 200: + "200": description: The lookup was successful. - examples: - application/json: { - "user_id": "@peter:rabbit.rocks", - "devices": { - "teapot": { - "sessions": [ - { - "connections": [ + content: + application/json: + schema: + type: object + properties: + user_id: + type: string + description: The Matrix user ID of the user. + devices: + type: object + description: Each key is an identifier for one of the user's devices. + additionalProperties: + type: object + title: DeviceInfo + properties: + sessions: + type: array + description: A user's sessions (i.e. what they did with an access token from one + login). + items: + type: object + title: SessionInfo + properties: + connections: + type: array + description: Information particular connections in the session. + items: + type: object + title: ConnectionInfo + properties: + ip: + type: string + description: Most recently seen IP address of the session. + last_seen: + type: integer + format: int64 + description: Unix timestamp that the session was last active. + user_agent: + type: string + description: User agent string last seen in the session. + examples: + response: + value: { + "user_id": "@peter:rabbit.rocks", + "devices": { + "teapot": { + "sessions": [ { - "ip": "127.0.0.1", - "last_seen": 1411996332123, - "user_agent": "curl/7.31.0-DEV" - }, - { - "ip": "10.0.0.2", - "last_seen": 1411996332123, - "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/37.0.2062.120 Safari/537.36" + "connections": [ + { + "ip": "127.0.0.1", + "last_seen": 1411996332123, + "user_agent": "curl/7.31.0-DEV" + }, + { + "ip": "10.0.0.2", + "last_seen": 1411996332123, + "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/37.0.2062.120 Safari/537.36" + } + ] } ] } - ] + } } - } - } - schema: - type: object - properties: - user_id: - type: string - description: The Matrix user ID of the user. - devices: - type: object - description: |- - Each key is an identifier for one of the user's devices. - additionalProperties: - type: object - title: DeviceInfo - properties: - sessions: - type: array - description: A user's sessions (i.e. what they did with an access token from one login). - items: - type: object - title: SessionInfo - properties: - connections: - type: array - description: Information particular connections in the session. - items: - type: object - title: ConnectionInfo - properties: - ip: - type: string - description: Most recently seen IP address of the session. - last_seen: - type: integer - format: int64 - description: Unix timestamp that the session was last active. - user_agent: - type: string - description: User agent string last seen in the session. tags: - Server administration +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/administrative_contact.yaml b/data/api/client-server/administrative_contact.yaml index fd6adc94..f2adefd1 100644 --- a/data/api/client-server/administrative_contact.yaml +++ b/data/api/client-server/administrative_contact.yaml @@ -12,23 +12,12 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server Account Administrative Contact API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server Account Administrative Contact API + version: 1.0.0 paths: - "/account/3pid": + /account/3pid: get: summary: Gets a list of a user's third-party identifiers. description: |- @@ -44,48 +33,56 @@ paths: security: - accessToken: [] responses: - 200: + "200": description: The lookup was successful. - examples: - application/json: { - "threepids": [ - { - "medium": "email", - "address": "monkey@banana.island", - "validated_at": 1535176800000, - "added_at": 1535336848756 - } - ] - } - schema: - type: object - properties: - threepids: - type: array - items: - type: object - title: Third-party identifier - properties: - medium: - type: string - description: The medium of the third-party identifier. - enum: ["email", "msisdn"] - address: - type: string - description: The third-party identifier address. - validated_at: - type: integer - format: int64 - description: |- - The timestamp, in milliseconds, when the identifier was - validated by the identity server. - added_at: - type: integer - format: int64 - description: - The timestamp, in milliseconds, when the homeserver - associated the third-party identifier with the user. - required: ['medium', 'address', 'validated_at', 'added_at'] + content: + application/json: + schema: + type: object + properties: + threepids: + type: array + items: + type: object + title: Third-party identifier + properties: + medium: + type: string + description: The medium of the third-party identifier. + enum: + - email + - msisdn + address: + type: string + description: The third-party identifier address. + validated_at: + type: integer + format: int64 + description: |- + The timestamp, in milliseconds, when the identifier was + validated by the identity server. + added_at: + type: integer + format: int64 + description: The timestamp, in milliseconds, when the homeserver associated the + third-party identifier with the user. + required: + - medium + - address + - validated_at + - added_at + examples: + response: + value: { + "threepids": [ + { + "medium": "email", + "address": "monkey@banana.island", + "validated_at": 1535176800000, + "added_at": 1535336848756 + } + ] + } tags: - Account management post: @@ -105,36 +102,40 @@ paths: deprecated: true security: - accessToken: [] - parameters: - - in: body - name: body - required: true - schema: - type: object - properties: - three_pid_creds: - title: "ThreePidCredentials" - type: object - description: The third-party credentials to associate with the account. - properties: - client_secret: - type: string - description: The client secret used in the session with the identity server. - id_server: - type: string - description: The identity server to use. - id_access_token: - type: string - description: |- - An access token previously registered with the identity server. Servers - can treat this as optional to distinguish between r0.5-compatible clients - and this specification version. - sid: - type: string - description: The session identifier given by the identity server. - required: ["client_secret", "id_server", "id_access_token", "sid"] - required: ["three_pid_creds"] - example: { + requestBody: + content: + application/json: + schema: + type: object + properties: + three_pid_creds: + title: ThreePidCredentials + type: object + description: The third-party credentials to associate with the account. + properties: + client_secret: + type: string + description: The client secret used in the session with the identity server. + id_server: + type: string + description: The identity server to use. + id_access_token: + type: string + description: |- + An access token previously registered with the identity server. Servers + can treat this as optional to distinguish between r0.5-compatible clients + and this specification version. + sid: + type: string + description: The session identifier given by the identity server. + required: + - client_secret + - id_server + - id_access_token + - sid + required: + - three_pid_creds + example: { "three_pid_creds": { "id_server": "matrix.org", "id_access_token": "abc123_OpaqueString", @@ -142,45 +143,52 @@ paths: "client_secret": "d0nt-T3ll" } } + required: true responses: - 200: + "200": description: The addition was successful. - examples: - application/json: { - "submit_url": "https://example.org/path/to/submitToken" - } - schema: - type: object - properties: - submit_url: - type: string - format: uri - description: |- - An optional field containing a URL where the client must - submit the validation token to, with identical parameters - to the Identity Service API's `POST - /validate/email/submitToken` endpoint (without the requirement - for an access token). The homeserver must send this token to the - user (if applicable), who should then be prompted to provide it - to the client. + content: + application/json: + schema: + type: object + properties: + submit_url: + type: string + format: uri + description: |- + An optional field containing a URL where the client must + submit the validation token to, with identical parameters + to the Identity Service API's `POST + /validate/email/submitToken` endpoint (without the requirement + for an access token). The homeserver must send this token to the + user (if applicable), who should then be prompted to provide it + to the client. - If this field is not present, the client can assume that - verification will happen without the client's involvement - provided the homeserver advertises this specification version - in the `/versions` response (ie: r0.5.0). - example: "https://example.org/path/to/submitToken" - 403: + If this field is not present, the client can assume that + verification will happen without the client's involvement + provided the homeserver advertises this specification version + in the `/versions` response (ie: r0.5.0). + example: https://example.org/path/to/submitToken + examples: + response: + value: { + "submit_url": "https://example.org/path/to/submitToken" + } + "403": description: The credentials could not be verified with the identity server. - examples: - application/json: { - "errcode": "M_THREEPID_AUTH_FAILED", - "error": "The third-party credentials could not be verified by the identity server." - } - schema: - "$ref": "definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_THREEPID_AUTH_FAILED", + "error": "The third-party credentials could not be verified by the identity server." + } tags: - Account management - "/account/3pid/add": + /account/3pid/add: post: summary: Adds contact information to the user's account. description: |- @@ -194,47 +202,55 @@ paths: operationId: add3PID security: - accessToken: [] - parameters: - - in: body - name: body - required: true - schema: - type: object - properties: - auth: - description: |- - Additional authentication information for the - user-interactive authentication API. - allOf: - - $ref: "definitions/auth_data.yaml" - client_secret: - type: string - description: The client secret used in the session with the homeserver. - example: "d0nt-T3ll" - sid: - type: string - description: The session identifier given by the homeserver. - example: "abc123987" - required: ["client_secret", "sid"] + requestBody: + content: + application/json: + schema: + type: object + properties: + auth: + description: |- + Additional authentication information for the + user-interactive authentication API. + allOf: + - $ref: definitions/auth_data.yaml + client_secret: + type: string + description: The client secret used in the session with the homeserver. + example: d0nt-T3ll + sid: + type: string + description: The session identifier given by the homeserver. + example: abc123987 + required: + - client_secret + - sid + required: true responses: - 200: + "200": description: The addition was successful. - examples: - application/json: {} - schema: - type: object - 401: - description: |- - The homeserver requires additional authentication information. - schema: - "$ref": "definitions/auth_response.yaml" - 429: + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "401": + description: The homeserver requires additional authentication information. + content: + application/json: + schema: + $ref: definitions/auth_response.yaml + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Account management - "/account/3pid/bind": + /account/3pid/bind: post: summary: Binds a 3PID to the user's account through an Identity Service. description: |- @@ -248,47 +264,55 @@ paths: operationId: bind3PID security: - accessToken: [] - parameters: - - in: body - name: body - required: true - schema: - type: object - properties: - client_secret: - type: string - description: The client secret used in the session with the identity server. - id_server: - type: string - description: The identity server to use. - id_access_token: - type: string - description: |- - An access token previously registered with the identity server. - sid: - type: string - description: The session identifier given by the identity server. - required: ["client_secret", "id_server", "id_access_token", "sid"] - example: { - "id_server": "example.org", - "id_access_token": "abc123_OpaqueString", - "sid": "abc123987", - "client_secret": "d0nt-T3ll" - } + requestBody: + content: + application/json: + schema: + type: object + properties: + client_secret: + type: string + description: The client secret used in the session with the identity server. + id_server: + type: string + description: The identity server to use. + id_access_token: + type: string + description: An access token previously registered with the identity server. + sid: + type: string + description: The session identifier given by the identity server. + required: + - client_secret + - id_server + - id_access_token + - sid + example: { + "id_server": "example.org", + "id_access_token": "abc123_OpaqueString", + "sid": "abc123987", + "client_secret": "d0nt-T3ll" + } + required: true responses: - 200: + "200": description: The addition was successful. - examples: - application/json: {} - schema: - type: object - 429: + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Account management - "/account/3pid/delete": + /account/3pid/delete: post: summary: Deletes a third-party identifier from the user's account description: |- @@ -301,59 +325,63 @@ paths: operationId: delete3pidFromAccount security: - accessToken: [] - parameters: - - in: body - name: body - required: true - schema: - type: object - properties: - id_server: - type: string - description: |- + requestBody: + content: + application/json: + schema: + type: object + properties: + id_server: + type: string + description: |- The identity server to unbind from. If not provided, the homeserver MUST use the `id_server` the identifier was added through. If the homeserver does not know the original `id_server`, it MUST return a `id_server_unbind_result` of `no-support`. - example: "example.org" - medium: - type: string - description: The medium of the third-party identifier being removed. - enum: ["email", "msisdn"] - example: "email" - address: - type: string - description: The third-party address being removed. - example: "example@example.org" - required: ['medium', 'address'] + example: example.org + medium: + type: string + description: The medium of the third-party identifier being removed. + enum: + - email + - msisdn + example: email + address: + type: string + description: The third-party address being removed. + example: example@example.org + required: + - medium + - address + required: true responses: - 200: + "200": description: |- The homeserver has disassociated the third-party identifier from the user. - schema: - type: object - properties: - id_server_unbind_result: - type: string - enum: - # XXX: I don't know why, but the order matters here so that "no-support" - # doesn't become "no- support" by the renderer. - - "no-support" - - "success" - description: |- - An indicator as to whether or not the homeserver was able to unbind - the 3PID from the identity server. `success` indicates that the - identity server has unbound the identifier whereas `no-support` - indicates that the identity server refuses to support the request - or the homeserver was not able to determine an identity server to - unbind from. - example: "success" - required: - - id_server_unbind_result + content: + application/json: + schema: + type: object + properties: + id_server_unbind_result: + type: string + enum: + - no-support + - success + description: |- + An indicator as to whether or not the homeserver was able to unbind + the 3PID from the identity server. `success` indicates that the + identity server has unbound the identifier whereas `no-support` + indicates that the identity server refuses to support the request + or the homeserver was not able to determine an identity server to + unbind from. + example: success + required: + - id_server_unbind_result tags: - Account management - "/account/3pid/unbind": + /account/3pid/unbind: post: summary: Removes a user's third-party identifier from an identity server. description: |- @@ -366,60 +394,65 @@ paths: operationId: unbind3pidFromAccount security: - accessToken: [] - parameters: - - in: body - name: body - required: true - schema: - type: object - properties: - id_server: - type: string - description: |- + requestBody: + content: + application/json: + schema: + type: object + properties: + id_server: + type: string + description: |- The identity server to unbind from. If not provided, the homeserver MUST use the `id_server` the identifier was added through. If the homeserver does not know the original `id_server`, it MUST return a `id_server_unbind_result` of `no-support`. - example: "example.org" - medium: - type: string - description: The medium of the third-party identifier being removed. - enum: ["email", "msisdn"] - example: "email" - address: - type: string - description: The third-party address being removed. - example: "example@example.org" - required: ['medium', 'address'] + example: example.org + medium: + type: string + description: The medium of the third-party identifier being removed. + enum: + - email + - msisdn + example: email + address: + type: string + description: The third-party address being removed. + example: example@example.org + required: + - medium + - address + required: true responses: - 200: + "200": description: |- The identity server has disassociated the third-party identifier from the user. - schema: - type: object - properties: - id_server_unbind_result: - type: string - enum: - # XXX: I don't know why, but the order matters here so that "no-support" - # doesn't become "no- support" by the renderer. - - "no-support" - - "success" - description: |- - An indicator as to whether or not the identity server was able to unbind - the 3PID. `success` indicates that the identity server has unbound the - identifier whereas `no-support` indicates that the identity server - refuses to support the request or the homeserver was not able to determine - an identity server to unbind from. - example: "success" - required: - - id_server_unbind_result + content: + application/json: + schema: + type: object + properties: + id_server_unbind_result: + type: string + enum: + - no-support + - success + description: |- + An indicator as to whether or not the identity server was able to unbind + the 3PID. `success` indicates that the identity server has unbound the + identifier whereas `no-support` indicates that the identity server + refuses to support the request or the homeserver was not able to determine + an identity server to unbind from. + example: success + required: + - id_server_unbind_result tags: - Account management - "/account/3pid/email/requestToken": + /account/3pid/email/requestToken: post: - summary: Begins the validation process for an email address for association with the user's account. + summary: Begins the validation process for an email address for association with + the user's account. description: |- The homeserver must check that the given email address is **not** already associated with an account on this homeserver. This API should @@ -430,49 +463,58 @@ paths: the email itself, either by sending a validation email itself or by using a service it has control over. operationId: requestTokenTo3PIDEmail - parameters: - - in: body - name: body - required: true - schema: - $ref: "definitions/request_email_validation.yaml" + requestBody: + content: + application/json: + schema: + $ref: definitions/request_email_validation.yaml + required: true responses: - 200: + "200": description: |- An email was sent to the given address. Note that this may be an email containing the validation token or it may be informing the user of an error. - schema: - $ref: "definitions/request_token_response.yaml" - 403: - description: |- - The homeserver does not allow the third-party identifier as a - contact option. - schema: - $ref: "definitions/errors/error.yaml" - examples: - application/json: { - "errcode": "M_THREEPID_DENIED", - "error": "Third-party identifier is not allowed" - } - 400: + content: + application/json: + schema: + $ref: definitions/request_token_response.yaml + "400": description: |- The third-party identifier is already in use on the homeserver, or the request was invalid. The error code `M_SERVER_NOT_TRUSTED` can be returned if the server does not trust/support the identity server provided in the request. - schema: - $ref: "definitions/errors/error.yaml" - examples: - application/json: { - "errcode": "M_THREEPID_IN_USE", - "error": "Third-party identifier already in use" - } + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_THREEPID_IN_USE", + "error": "Third-party identifier already in use" + } + "403": + description: |- + The homeserver does not allow the third-party identifier as a + contact option. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_THREEPID_DENIED", + "error": "Third-party identifier is not allowed" + } tags: - Account management - "/account/3pid/msisdn/requestToken": + /account/3pid/msisdn/requestToken: post: - summary: Begins the validation process for a phone number for association with the user's account. + summary: Begins the validation process for a phone number for association with + the user's account. description: |- The homeserver must check that the given phone number is **not** already associated with an account on this homeserver. This API should @@ -483,40 +525,63 @@ paths: the phone number itself, either by sending a validation message itself or by using a service it has control over. operationId: requestTokenTo3PIDMSISDN - parameters: - - in: body - name: body - required: true - schema: - $ref: "definitions/request_msisdn_validation.yaml" + requestBody: + content: + application/json: + schema: + $ref: definitions/request_msisdn_validation.yaml + required: true responses: - 200: + "200": description: An SMS message was sent to the given phone number. - schema: - $ref: "definitions/request_token_response.yaml" - 403: - description: |- - The homeserver does not allow the third-party identifier as a - contact option. - schema: - $ref: "definitions/errors/error.yaml" - examples: - application/json: { - "errcode": "M_THREEPID_DENIED", - "error": "Third-party identifier is not allowed" - } - 400: + content: + application/json: + schema: + $ref: definitions/request_token_response.yaml + "400": description: |- The third-party identifier is already in use on the homeserver, or the request was invalid. The error code `M_SERVER_NOT_TRUSTED` can be returned if the server does not trust/support the identity server provided in the request. - schema: - $ref: "definitions/errors/error.yaml" - examples: - application/json: { - "errcode": "M_THREEPID_IN_USE", - "error": "Third-party identifier already in use" - } + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_THREEPID_IN_USE", + "error": "Third-party identifier already in use" + } + "403": + description: |- + The homeserver does not allow the third-party identifier as a + contact option. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_THREEPID_DENIED", + "error": "Third-party identifier is not allowed" + } tags: - Account management +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/appservice_ping.yaml b/data/api/client-server/appservice_ping.yaml index 13b7289f..7102659e 100644 --- a/data/api/client-server/appservice_ping.yaml +++ b/data/api/client-server/appservice_ping.yaml @@ -11,29 +11,16 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server Application Service Ping API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v1 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - # Note: this is the same access_token definition used elsewhere in the client - # server API, however this expects an access token for an application service. - $ref: definitions/security.yaml + title: Matrix Client-Server Application Service Ping API + version: 1.0.0 paths: "/appservice/{appserviceId}/ping": post: x-addedInMatrixVersion: "1.7" - summary: |- - Ask the homeserver to ping the application service to ensure the connection works. + summary: Ask the homeserver to ping the application service to ensure the + connection works. description: |- This API asks the homeserver to call the [`/_matrix/app/v1/ping`](#post_matrixappv1ping) endpoint on the @@ -48,63 +35,79 @@ paths: operationId: pingAppservice parameters: - in: path - type: string name: appserviceId description: |- The appservice ID of the appservice to ping. This must be the same as the appservice whose `as_token` is being used to authenticate the request. required: true - x-example: "telegram" - - in: body - name: body - required: true + example: telegram schema: - type: object - properties: - transaction_id: - type: string - description: |- - An optional transaction ID that is passed through to the `/_matrix/app/v1/ping` call. - example: "mautrix-go_1683636478256400935_123" + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + transaction_id: + type: string + description: An optional transaction ID that is passed through to the + `/_matrix/app/v1/ping` call. + example: mautrix-go_1683636478256400935_123 + required: true security: # again, this is the appservice's token - not a typical client's - accessToken: [] responses: - 200: + "200": description: The ping was successful. - schema: - type: object - properties: - duration_ms: - type: integer - description: |- - The duration in milliseconds that the - [`/_matrix/app/v1/ping`](#post_matrixappv1ping) - request took from the homeserver's point of view. - required: - - duration_ms - examples: - application/json: {"duration_ms": 123} - 400: - description: The application service doesn't have a URL configured. The errcode is `M_URL_NOT_SET`. - schema: - $ref: "definitions/errors/error.yaml" - examples: - application/json: { - "errcode": "M_URL_NOT_SET", - "error": "Application service doesn't have a URL configured" - } - 403: - description: The access token used to authenticate the request doesn't belong to an appservice, or belongs to a different appservice than the one in the path. The errcode is `M_FORBIDDEN`. - schema: - $ref: "definitions/errors/error.yaml" - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "Provided access token is not the appservice's as_token" - } - 502: + content: + application/json: + schema: + type: object + properties: + duration_ms: + type: integer + description: |- + The duration in milliseconds that the + [`/_matrix/app/v1/ping`](#post_matrixappv1ping) + request took from the homeserver's point of view. + required: + - duration_ms + examples: + response: + value: { + "duration_ms": 123 + } + "400": + description: The application service doesn't have a URL configured. The errcode + is `M_URL_NOT_SET`. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_URL_NOT_SET", + "error": "Application service doesn't have a URL configured" + } + "403": + description: The access token used to authenticate the request doesn't belong to + an appservice, or belongs to a different appservice than the one in + the path. The errcode is `M_FORBIDDEN`. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "Provided access token is not the appservice's as_token" + } + "502": description: |- The application service returned a bad status, or the connection failed. The errcode is `M_BAD_STATUS` or `M_CONNECTION_FAILED`. @@ -112,41 +115,68 @@ paths: For bad statuses, the response may include `status` and `body` fields containing the HTTP status code and response body text respectively to aid with debugging. - schema: - type: object - title: Error - description: A Matrix-level Error - properties: - errcode: - type: string - description: An error code. - enum: [M_BAD_STATUS, M_CONNECTION_FAILED] - error: - type: string - description: A human-readable error message. - example: Ping returned status 401 - status: - type: integer - description: The HTTP status code returned by the appservice. - example: 401 - body: - type: string - description: The HTTP response body returned by the appservice. - example: "{\"errcode\": \"M_UNKNOWN_TOKEN\"}" - required: ["errcode"] - examples: - application/json: { - "errcode": "M_BAD_STATUS", - "error": "Ping returned status 401", - "status": 401, - "body": "{\"errcode\": \"M_UNKNOWN_TOKEN\"}" - } - 504: - description: The connection to the application service timed out. The errcode is `M_CONNECTION_TIMEOUT`. - schema: - $ref: "definitions/errors/error.yaml" - examples: - application/json: { - "errcode": "M_CONNECTION_TIMEOUT", - "error": "Connection to application service timed out" - } + content: + application/json: + schema: + type: object + title: Error + description: A Matrix-level Error + properties: + errcode: + type: string + description: An error code. + enum: + - M_BAD_STATUS + - M_CONNECTION_FAILED + error: + type: string + description: A human-readable error message. + example: Ping returned status 401 + status: + type: integer + description: The HTTP status code returned by the appservice. + example: 401 + body: + type: string + description: The HTTP response body returned by the appservice. + example: '{"errcode": "M_UNKNOWN_TOKEN"}' + required: + - errcode + examples: + response: + value: { + "errcode": "M_BAD_STATUS", + "error": "Ping returned status 401", + "status": 401, + "body": "{\"errcode\": \"M_UNKNOWN_TOKEN\"}" + } + "504": + description: The connection to the application service timed out. The errcode is + `M_CONNECTION_TIMEOUT`. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_CONNECTION_TIMEOUT", + "error": "Connection to application service timed out" + } +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v1 +components: + securitySchemes: + # Note: this is the same access_token definition used elsewhere in the client + # server API, however this expects an access token for an application service. + $ref: definitions/security.yaml diff --git a/data/api/client-server/appservice_room_directory.yaml b/data/api/client-server/appservice_room_directory.yaml index 233bf2bd..2af58a22 100644 --- a/data/api/client-server/appservice_room_directory.yaml +++ b/data/api/client-server/appservice_room_directory.yaml @@ -11,28 +11,14 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server Application Service Room Directory API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - # Note: this is the same access_token definition used elsewhere in the client - # server API, however this expects an access token for an application service. - $ref: definitions/security.yaml + title: Matrix Client-Server Application Service Room Directory API + version: 1.0.0 paths: "/directory/list/appservice/{networkId}/{roomId}": put: - summary: |- - Updates a room's visibility in the application service's room directory. + summary: Updates a room's visibility in the application service's room directory. description: |- Updates the visibility of a given room on the application service's room directory. @@ -46,43 +32,69 @@ paths: operationId: updateAppserviceRoomDirectoryVisibility parameters: - in: path - type: string name: networkId description: |- The protocol (network) ID to update the room list for. This would have been provided by the application service as being listed as a supported protocol. required: true - x-example: "irc" + example: irc + schema: + type: string - in: path - type: string name: roomId description: The room ID to add to the directory. required: true - x-example: "!somewhere:example.org" - - in: body - name: body - required: true + example: "!somewhere:example.org" schema: - type: object - properties: - visibility: - type: string - enum: ["public", "private"] - description: |- - Whether the room should be visible (public) in the directory - or not (private). - example: "public" - required: ['visibility'] + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + visibility: + type: string + enum: + - public + - private + description: |- + Whether the room should be visible (public) in the directory + or not (private). + example: public + required: + - visibility + required: true security: # again, this is the appservice's token - not a typical client's - accessToken: [] responses: - 200: + "200": description: The room's directory visibility has been updated. - schema: - type: object - examples: - application/json: {} + content: + application/json: + schema: + type: object + examples: + response: + value: {} tags: - Application service room directory management +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 +components: + securitySchemes: + # Note: this is the same access_token definition used elsewhere in the client + # server API, however this expects an access token for an application service. + $ref: definitions/security.yaml diff --git a/data/api/client-server/banning.yaml b/data/api/client-server/banning.yaml index b1ba4d02..5185d89b 100644 --- a/data/api/client-server/banning.yaml +++ b/data/api/client-server/banning.yaml @@ -11,21 +11,10 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server Room Banning API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server Room Banning API + version: 1.0.0 paths: "/rooms/{roomId}/ban": post: @@ -41,51 +30,60 @@ paths: - accessToken: [] parameters: - in: path - type: string name: roomId description: The room identifier (not alias) from which the user should be banned. required: true - x-example: "!e42d8c:matrix.org" - - in: body - name: body - required: true + example: "!e42d8c:matrix.org" schema: - type: object - example: { + type: string + requestBody: + content: + application/json: + schema: + type: object + example: { "reason": "Telling unfunny jokes", "user_id": "@cheeky_monkey:matrix.org" } - properties: - user_id: - type: string - description: The fully qualified user ID of the user being banned. - reason: - x-addedInMatrixVersion: "1.1" - type: string - description: The reason the user has been banned. This will be supplied as the - `reason` on the target's updated [`m.room.member`](/client-server-api/#mroommember) event. - required: ["user_id"] + properties: + user_id: + type: string + description: The fully qualified user ID of the user being banned. + reason: + x-addedInMatrixVersion: "1.1" + type: string + description: The reason the user has been banned. This will be supplied as the + `reason` on the target's updated + [`m.room.member`](/client-server-api/#mroommember) event. + required: + - user_id + required: true responses: - 200: + "200": description: The user has been kicked and banned from the room. - examples: - application/json: { - } - schema: - type: object - 403: + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "403": description: |- You do not have permission to ban the user from the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are: - The banner is not currently in the room. - The banner's power level is insufficient to ban users from the room. - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "You do not have a high enough power level to ban from this room." - } - schema: - "$ref": "definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "You do not have a high enough power level to ban from this room." + } tags: - Room membership "/rooms/{roomId}/unban": @@ -101,50 +99,74 @@ paths: - accessToken: [] parameters: - in: path - type: string name: roomId - description: The room identifier (not alias) from which the user should be unbanned. - required: true - x-example: "!e42d8c:matrix.org" - - in: body - name: body + description: The room identifier (not alias) from which the user should be + unbanned. required: true + example: "!e42d8c:matrix.org" schema: - type: object - example: { - "user_id": "@cheeky_monkey:matrix.org", - "reason": "They've been banned long enough" - } - properties: - user_id: - type: string - description: The fully qualified user ID of the user being unbanned. - reason: - x-addedInMatrixVersion: "1.1" - type: string - description: |- - Optional reason to be included as the `reason` on the subsequent - membership event. - required: ["user_id"] - responses: - 200: - description: The user has been unbanned from the room. - examples: - application/json: { + type: string + requestBody: + content: + application/json: + schema: + type: object + example: { + "user_id": "@cheeky_monkey:matrix.org", + "reason": "They've been banned long enough" } - schema: - type: object - 403: + properties: + user_id: + type: string + description: The fully qualified user ID of the user being unbanned. + reason: + x-addedInMatrixVersion: "1.1" + type: string + description: |- + Optional reason to be included as the `reason` on the subsequent + membership event. + required: + - user_id + required: true + responses: + "200": + description: The user has been unbanned from the room. + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "403": description: |- You do not have permission to unban the user from the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are: - The unbanner's power level is insufficient to unban users from the room. - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "You do not have a high enough power level to unban from this room." - } - schema: - "$ref": "definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "You do not have a high enough power level to unban from this room." + } tags: - Room membership +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/capabilities.yaml b/data/api/client-server/capabilities.yaml index d31d01d7..96fdfb56 100644 --- a/data/api/client-server/capabilities.yaml +++ b/data/api/client-server/capabilities.yaml @@ -11,21 +11,12 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server Capabilities API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server Capabilities API + version: 1.0.0 paths: - "/capabilities": + /capabilities: get: summary: Gets information about the server's capabilities. description: |- @@ -34,79 +25,99 @@ paths: operationId: getCapabilities security: - accessToken: [] - parameters: [] responses: - 200: - description: - The capabilities of the server. - examples: - application/json: { - "capabilities": { - "m.change_password": { - "enabled": false - }, - "m.room_versions": { - "default": "1", - "available": { - "1": "stable", - "2": "stable", - "3": "unstable", - "test-version": "unstable" - } - }, - "com.example.custom.ratelimit": { - "max_requests_per_hour": 600 - } - } - } - schema: - type: object - required: ["capabilities"] - properties: - capabilities: + "200": + description: The capabilities of the server. + content: + application/json: + schema: type: object - title: Capabilities - description: |- - The custom capabilities the server supports, using the - Java package naming convention. - additionalProperties: - type: object + required: + - capabilities properties: - "m.change_password": + capabilities: type: object + title: Capabilities description: |- - Capability to indicate if the user can change their password. - title: ChangePasswordCapability + The custom capabilities the server supports, using the + Java package naming convention. + additionalProperties: + type: object properties: - enabled: - type: boolean - description: |- - True if the user can change their password, false otherwise. - example: false - required: ['enabled'] - "m.room_versions": - type: object - description: The room versions the server supports. - title: RoomVersionsCapability - properties: - default: - type: string - description: |- - The default room version the server is using for new rooms. - example: "1" - available: + m.change_password: type: object - description: |- - A detailed description of the room versions the server supports. - additionalProperties: - type: string - title: RoomVersionStability - enum: [stable, unstable] - description: The stability of the room version. - required: ['default', 'available'] - 429: + description: Capability to indicate if the user can change their password. + title: ChangePasswordCapability + properties: + enabled: + type: boolean + description: True if the user can change their password, false otherwise. + example: false + required: + - enabled + m.room_versions: + type: object + description: The room versions the server supports. + title: RoomVersionsCapability + properties: + default: + type: string + description: The default room version the server is using for new rooms. + example: "1" + available: + type: object + description: A detailed description of the room versions the server supports. + additionalProperties: + type: string + title: RoomVersionStability + enum: + - stable + - unstable + description: The stability of the room version. + required: + - default + - available + examples: + response: + value: { + "capabilities": { + "m.change_password": { + "enabled": false + }, + "m.room_versions": { + "default": "1", + "available": { + "1": "stable", + "2": "stable", + "3": "unstable", + "test-version": "unstable" + } + }, + "com.example.custom.ratelimit": { + "max_requests_per_hour": 600 + } + } + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Capabilities +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/content-repo.yaml b/data/api/client-server/content-repo.yaml index 57445027..7792b2a9 100644 --- a/data/api/client-server/content-repo.yaml +++ b/data/api/client-server/content-repo.yaml @@ -12,93 +12,94 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server Content Repository API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix -consumes: - - application/json - - "*/*" -produces: - - application/json - - "*/*" -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server Content Repository API + version: 1.0.0 paths: - "/media/v3/upload": + /media/v3/upload: post: summary: Upload some content to the content repository. operationId: uploadContent - produces: ["application/json"] security: - accessToken: [] parameters: - in: header name: Content-Type - type: string description: The content type of the file being uploaded - x-example: "application/pdf" - - in: query - type: string - x-example: "War and Peace.pdf" - name: filename - description: The name of the file being uploaded - - in: body - name: "content" - description: The content to be uploaded. - required: true - x-example: "" # so the spec shows "" without quotes. + example: application/pdf schema: type: string - example: "" - format: byte - responses: - 200: - description: The [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris) for the uploaded content. + - in: query + name: filename + description: The name of the file being uploaded + example: War and Peace.pdf schema: - type: object - required: ["content_uri"] - properties: - content_uri: - type: string - format: uri - description: "The [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris) to the uploaded content." - examples: - application/json: { - "content_uri": "mxc://example.com/AQwafuaFswefuhsfAFAgsw" - } - 403: + type: string + requestBody: + content: + application/octet-stream: + schema: + type: string + example: + format: byte + description: The content to be uploaded. + required: true + responses: + "200": + description: The [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris) for + the uploaded content. + content: + application/json: + schema: + type: object + required: + - content_uri + properties: + content_uri: + type: string + format: uri + description: The [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris) to + the uploaded content. + examples: + response: + value: { + "content_uri": "mxc://example.com/AQwafuaFswefuhsfAFAgsw" + } + "403": description: |- The user does not have permission to upload the content. Some reasons for this error include: - The server does not permit the file type. - The user has reached a quota for uploaded content. - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "Cannot upload this content" - } - schema: - "$ref": "definitions/errors/error.yaml" - 413: - description: |- - The uploaded content is too large for the server. - examples: - application/json: { - "errcode": "M_TOO_LARGE", - "error": "Cannot upload files larger than 100mb" - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "Cannot upload this content" + } + "413": + description: The uploaded content is too large for the server. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_TOO_LARGE", + "error": "Cannot upload files larger than 100mb" + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Media "/media/v3/upload/{serverName}/{mediaId}": @@ -111,46 +112,53 @@ paths: x-addedInMatrixVersion: "1.7" parameters: - in: path - type: string name: serverName - x-example: matrix.org required: true description: | The server name from the `mxc://` URI returned by `POST /_matrix/media/v1/create` (the authoritory component). + example: matrix.org + schema: + type: string - in: path - type: string name: mediaId - x-example: ascERGshawAWawugaAcauga required: true description: | The media ID from the `mxc://` URI returned by `POST /_matrix/media/v1/create` (the path component). - - in: header - name: Content-Type - type: string - description: The content type of the file being uploaded - x-example: "application/pdf" - - in: query - type: string - x-example: "War and Peace.pdf" - name: filename - description: The name of the file being uploaded - - in: body - name: "content" - description: The content to be uploaded. - required: true - x-example: "" # so the spec shows "" without quotes. + example: ascERGshawAWawugaAcauga schema: type: string - example: "" - format: byte - responses: - 200: - description: The upload was successful. + - in: header + name: Content-Type + description: The content type of the file being uploaded + example: application/pdf schema: - type: object - examples: - application/json: {} - 403: + type: string + - in: query + name: filename + description: The name of the file being uploaded + example: War and Peace.pdf + schema: + type: string + requestBody: + content: + application/octet-stream: + schema: + type: string + example: + format: byte + description: The content to be uploaded. + required: true + responses: + "200": + description: The upload was successful. + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "403": description: |- The user does not have permission to upload the content. Some reasons for this error include: @@ -161,42 +169,52 @@ paths: A [standard error response](/client-server-api/#standard-error-response) will be returned with the `errcode` `M_FORBIDDEN`. - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "Cannot upload this content" - } - schema: - "$ref": "definitions/errors/error.yaml" - 409: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "Cannot upload this content" + } + "409": description: |- The endpoint was called with a media ID that already has content. A [standard error response](/client-server-api/#standard-error-response) will be returned with the `errcode` `M_CANNOT_OVERWRITE_MEDIA`. - examples: - application/json: { - "errcode": "M_CANNOT_OVERWRITE_MEDIA", - "error": "Media already uploaded" - } - schema: - "$ref": "definitions/errors/error.yaml" - 413: - description: |- - The uploaded content is too large for the server. - examples: - application/json: { - "errcode": "M_TOO_LARGE", - "error": "Cannot upload files larger than 100mb" - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_CANNOT_OVERWRITE_MEDIA", + "error": "Media already uploaded" + } + "413": + description: The uploaded content is too large for the server. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_TOO_LARGE", + "error": "Cannot upload files larger than 100mb" + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Media - "/media/v1/create": + /media/v1/create: post: summary: Create a new `mxc://` URI without uploading the content. description: |- @@ -220,87 +238,90 @@ paths: server should respond with an HTTP 429 error with an errcode of `M_LIMIT_EXCEEDED`. operationId: createContent - consumes: ["application/json"] - produces: ["application/json"] x-addedInMatrixVersion: "1.7" security: - accessToken: [] # empty json object - parameters: [] responses: - 200: - description: The [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris) for the uploaded content. - schema: - type: object - required: ["content_uri"] - properties: - content_uri: - type: string - format: uri - description: |- - The [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris) at - which the content will be available, once it is uploaded. - example: "mxc://example.com/AQwafuaFswefuhsfAFAgsw" - unused_expires_at: - type: integer - format: int64 - description: |- - The timestamp (in milliseconds since the unix epoch) when the - generated media id will expire, if media is not uploaded. - example: 1647257217083 - 403: - description: |- - The user does not have permission to upload the content. - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "Cannot upload this content" - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + "200": + description: The [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris) for + the uploaded content. + content: + application/json: + schema: + type: object + required: + - content_uri + properties: + content_uri: + type: string + format: uri + description: |- + The [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris) at + which the content will be available, once it is uploaded. + example: mxc://example.com/AQwafuaFswefuhsfAFAgsw + unused_expires_at: + type: integer + format: int64 + description: |- + The timestamp (in milliseconds since the unix epoch) when the + generated media id will expire, if media is not uploaded. + example: 1647257217083 + "403": + description: The user does not have permission to upload the content. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "Cannot upload this content" + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Media "/media/v3/download/{serverName}/{mediaId}": get: - summary: "Download content from the content repository." + summary: Download content from the content repository. operationId: getContent - produces: ["*/*"] parameters: - in: path - type: string name: serverName - x-example: matrix.org required: true description: | The server name from the `mxc://` URI (the authoritory component) + example: matrix.org + schema: + type: string - in: path - type: string name: mediaId - x-example: ascERGshawAWawugaAcauga required: true description: | The media ID from the `mxc://` URI (the path component) + example: ascERGshawAWawugaAcauga + schema: + type: string - in: query - type: boolean name: allow_remote - x-example: false required: false - default: true description: | Indicates to the server that it should not attempt to fetch the media if it is deemed remote. This is to prevent routing loops where the server contacts itself. Defaults to true if not provided. + example: false + schema: + type: boolean + default: true - in: query - type: integer - format: int64 name: timeout_ms - x-example: 5000 x-addedInMatrixVersion: "1.7" - default: 20000 description: | The maximum number of milliseconds that the client is willing to wait to start receiving data, in the case that the content has not @@ -308,69 +329,88 @@ paths: content repository can and should impose a maximum value for this parameter. The content repository may also choose to respond before the timeout. + example: 5000 + schema: + type: integer + format: int64 + default: 20000 - in: query - type: boolean name: allow_redirect x-addedInMatrixVersion: "1.7" - x-example: false required: false - default: false description: | Indicates to the server that it may return a 307 or 308 redirect response that points at the relevant media content. When not explicitly set to true the server must return the media content itself. + example: false + schema: + type: boolean + default: false responses: - 200: - description: "The content that was previously uploaded." + "200": + description: The content that was previously uploaded. headers: Content-Type: - description: "The content type of the file that was previously uploaded." - type: "string" + description: The content type of the file that was previously uploaded. + schema: + type: string Content-Disposition: - description: |- - The name of the file that was previously uploaded, if set. - type: "string" - schema: - type: file - # This is a workaround for us not being able to say the response is required. - description: "**Required.** The bytes for the uploaded file." - 307: - description: "A redirect to the thumbnail of the requested content." + description: The name of the file that was previously uploaded, if set. + schema: + type: string + content: + application/octet-stream: + schema: + type: string + # This is a workaround for us not being able to say the response is required. + description: "**Required.** The bytes for the uploaded file." + format: binary + "307": + description: A redirect to the thumbnail of the requested content. headers: Location: - description: "The URL of the thumbnail content." - type: "string" - 308: - description: "A redirect to the thumbnail of the requested content." + description: The URL of the thumbnail content. + schema: + type: string + "308": + description: A redirect to the thumbnail of the requested content. headers: Location: - description: "The URL of the thumbnail content." - type: "string" - 429: + description: The URL of the thumbnail content. + schema: + type: string + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" - 502: - description: |- - The content is too large for the server to serve. - examples: - application/json: { - "errcode": "M_TOO_LARGE", - "error": "Content is too large to serve" - } - schema: - "$ref": "definitions/errors/error.yaml" - 504: + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml + "502": + description: The content is too large for the server to serve. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_TOO_LARGE", + "error": "Content is too large to serve" + } + "504": description: |- The content is not yet available. A [standard error response](/client-server-api/#standard-error-response) will be returned with the `errcode` `M_NOT_YET_UPLOADED`. - examples: - application/json: { - "errcode": "M_NOT_YET_UPLOADED", - "error": "Content has not yet been uploaded" - } - schema: - "$ref": "definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_YET_UPLOADED", + "error": "Content has not yet been uploaded" + } tags: - Media "/media/v3/download/{serverName}/{mediaId}/{fileName}": @@ -381,45 +421,44 @@ paths: the previous endpoint) but replace the target file name with the one provided by the caller. operationId: getContentOverrideName - produces: ["*/*"] parameters: - in: path - type: string name: serverName - x-example: matrix.org required: true description: | The server name from the `mxc://` URI (the authoritory component) + example: matrix.org + schema: + type: string - in: path - type: string name: mediaId - x-example: ascERGshawAWawugaAcauga required: true description: | The media ID from the `mxc://` URI (the path component) + example: ascERGshawAWawugaAcauga + schema: + type: string - in: path - type: string name: fileName - x-example: filename.jpg required: true description: A filename to give in the `Content-Disposition` header. + example: filename.jpg + schema: + type: string - in: query - type: boolean name: allow_remote - x-example: false required: false - default: true description: | Indicates to the server that it should not attempt to fetch the media if it is deemed remote. This is to prevent routing loops where the server contacts itself. Defaults to true if not provided. + example: false + schema: + type: boolean + default: true - in: query - type: integer - format: int64 name: timeout_ms - x-example: 5000 x-addedInMatrixVersion: "1.7" - default: 20000 description: | The maximum number of milliseconds that the client is willing to wait to start receiving data, in the case that the content has not @@ -427,70 +466,90 @@ paths: content repository can and should impose a maximum value for this parameter. The content repository may also choose to respond before the timeout. + example: 5000 + schema: + type: integer + format: int64 + default: 20000 - in: query - type: boolean name: allow_redirect x-addedInMatrixVersion: "1.7" - x-example: false required: false - default: false description: | Indicates to the server that it may return a 307 or 308 redirect response that points at the relevant media content. When not explicitly set to true the server must return the media content itself. + example: false + schema: + type: boolean + default: false responses: - 200: - description: "The content that was previously uploaded." + "200": + description: The content that was previously uploaded. headers: Content-Type: - description: "The content type of the file that was previously uploaded." - type: "string" + description: The content type of the file that was previously uploaded. + schema: + type: string Content-Disposition: description: |- The `fileName` requested or the name of the file that was previously uploaded, if set. - type: "string" - schema: - type: file - # This is a workaround for us not being able to say the response is required. - description: "**Required.** The bytes for the uploaded file." - 307: - description: "A redirect to the thumbnail of the requested content." + schema: + type: string + content: + application/octet-stream: + schema: + type: string + # This is a workaround for us not being able to say the response is required. + description: "**Required.** The bytes for the uploaded file." + format: binary + "307": + description: A redirect to the thumbnail of the requested content. headers: Location: - description: "The URL of the thumbnail content." - type: "string" - 308: - description: "A redirect to the thumbnail of the requested content." + description: The URL of the thumbnail content. + schema: + type: string + "308": + description: A redirect to the thumbnail of the requested content. headers: Location: - description: "The URL of the thumbnail content." - type: "string" - 429: + description: The URL of the thumbnail content. + schema: + type: string + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" - 502: - description: |- - The content is too large for the server to serve. - examples: - application/json: { - "errcode": "M_TOO_LARGE", - "error": "Content is too large to serve" - } - schema: - "$ref": "definitions/errors/error.yaml" - 504: + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml + "502": + description: The content is too large for the server to serve. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_TOO_LARGE", + "error": "Content is too large to serve" + } + "504": description: |- The content is not yet available. A [standard error response](/client-server-api/#standard-error-response) will be returned with the `errcode` `M_NOT_YET_UPLOADED`. - examples: - application/json: { - "errcode": "M_NOT_YET_UPLOADED", - "error": "Content has not yet been uploaded" - } - schema: - "$ref": "definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_YET_UPLOADED", + "error": "Content has not yet been uploaded" + } tags: - Media "/media/v3/thumbnail/{serverName}/{mediaId}": @@ -500,63 +559,66 @@ paths: Download a thumbnail of content from the content repository. See the [Thumbnails](/client-server-api/#thumbnails) section for more information. operationId: getContentThumbnail - produces: ["image/jpeg", "image/png"] parameters: - in: path - type: string name: serverName required: true - x-example: example.org description: | The server name from the `mxc://` URI (the authoritory component) + example: example.org + schema: + type: string - in: path - type: string name: mediaId - x-example: ascERGshawAWawugaAcauga required: true description: | The media ID from the `mxc://` URI (the path component) + example: ascERGshawAWawugaAcauga + schema: + type: string - in: query - type: integer - x-example: 64 name: width required: true description: |- The *desired* width of the thumbnail. The actual thumbnail may be larger than the size specified. + example: 64 + schema: + type: integer - in: query - type: integer - x-example: 64 name: height required: true description: |- The *desired* height of the thumbnail. The actual thumbnail may be larger than the size specified. + example: 64 + schema: + type: integer - in: query - type: string - enum: ["crop", "scale"] name: method - x-example: "scale" description: |- The desired resizing method. See the [Thumbnails](/client-server-api/#thumbnails) section for more information. + example: scale + schema: + type: string + enum: + - crop + - scale - in: query - type: boolean name: allow_remote - x-example: false required: false - default: true description: |- Indicates to the server that it should not attempt to fetch the media if it is deemed remote. This is to prevent routing loops where the server contacts itself. Defaults to true if not provided. + example: false + schema: + type: boolean + default: true - in: query - type: integer - format: int64 name: timeout_ms - x-example: 5000 x-addedInMatrixVersion: "1.7" - default: 20000 description: | The maximum number of milliseconds that the client is willing to wait to start receiving data, in the case that the content has not @@ -564,93 +626,124 @@ paths: content repository can and should impose a maximum value for this parameter. The content repository may also choose to respond before the timeout. + example: 5000 + schema: + type: integer + format: int64 + default: 20000 - in: query - type: boolean name: allow_redirect x-addedInMatrixVersion: "1.7" - x-example: false required: false - default: false description: | Indicates to the server that it may return a 307 or 308 redirect response that points at the relevant media content. When not explicitly set to true the server must return the media content itself. + example: false + schema: + type: boolean + default: false responses: - 200: - description: "A thumbnail of the requested content." + "200": + description: A thumbnail of the requested content. headers: Content-Type: - description: "The content type of the thumbnail." - type: "string" - enum: ["image/jpeg", "image/png"] - schema: - type: file - # This is a workaround for us not being able to say the response is required. - description: "**Required.** The bytes for the thumbnail." - 307: - description: "A redirect to the thumbnail of the requested content." + description: The content type of the thumbnail. + schema: + type: string + enum: + - image/jpeg + - image/png + content: + image/jpeg: + schema: + type: string + # This is a workaround for us not being able to say the response is required. + description: "**Required.** The bytes for the thumbnail." + format: binary + image/png: + schema: + type: string + description: "**Required.** The bytes for the thumbnail." + format: binary + "307": + description: A redirect to the thumbnail of the requested content. headers: Location: - description: "The URL of the thumbnail content." - type: "string" - 308: - description: "A redirect to the thumbnail of the requested content." + description: The URL of the thumbnail content. + schema: + type: string + "308": + description: A redirect to the thumbnail of the requested content. headers: Location: - description: "The URL of the thumbnail content." - type: "string" - 400: + description: The URL of the thumbnail content. + schema: + type: string + "400": description: |- The request does not make sense to the server, or the server cannot thumbnail the content. For example, the client requested non-integer dimensions or asked for negatively-sized images. - examples: - application/json: { - "errcode": "M_UNKNOWN", - "error": "Cannot generate thumbnails for the requested content" - } - schema: - "$ref": "definitions/errors/error.yaml" - 413: - description: |- - The local content is too large for the server to thumbnail. - examples: - application/json: { - "errcode": "M_TOO_LARGE", - "error": "Content is too large to thumbnail" - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_UNKNOWN", + "error": "Cannot generate thumbnails for the requested content" + } + "413": + description: The local content is too large for the server to thumbnail. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_TOO_LARGE", + "error": "Content is too large to thumbnail" + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" - 502: - description: |- - The remote content is too large for the server to thumbnail. - examples: - application/json: { - "errcode": "M_TOO_LARGE", - "error": "Content is too large to thumbnail" - } - schema: - "$ref": "definitions/errors/error.yaml" - 504: + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml + "502": + description: The remote content is too large for the server to thumbnail. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_TOO_LARGE", + "error": "Content is too large to thumbnail" + } + "504": description: |- The content is not yet available. A [standard error response](/client-server-api/#standard-error-response) will be returned with the `errcode` `M_NOT_YET_UPLOADED`. - examples: - application/json: { - "errcode": "M_NOT_YET_UPLOADED", - "error": "Content has not yet been uploaded" - } - schema: - "$ref": "definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_YET_UPLOADED", + "error": "Content has not yet been uploaded" + } tags: - Media - "/media/v3/preview_url": + /media/v3/preview_url: get: - summary: "Get information about a URL for a client" + summary: Get information about a URL for a client description: |- Get information about a URL for the client. Typically this is called when a client sees a URL in a message and wants to render a preview for the user. @@ -660,64 +753,68 @@ paths: rooms. Encrypted rooms often contain more sensitive information the users do not want to share with the homeserver, and this can mean that the URLs being shared should also not be shared with the homeserver. - operationId: getUrlPreview - produces: ["application/json"] security: - accessToken: [] parameters: - in: query - type: string - format: uri - x-example: "https://matrix.org" name: url - description: "The URL to get a preview of." + description: The URL to get a preview of. required: true + example: https://matrix.org + schema: + type: string + format: uri - in: query - type: integer - format: int64 - x-example: 1510610716656 name: ts description: |- The preferred point in time to return a preview for. The server may return a newer version if it does not have the requested version available. + example: 1510610716656 + schema: + type: integer + format: int64 responses: - 200: + "200": description: |- The OpenGraph data for the URL, which may be empty. Some values are replaced with matrix equivalents if they are provided in the response. The differences from the OpenGraph protocol are described here. - schema: - type: object - properties: - "matrix:image:size": - type: integer - format: int64 - description: |- - The byte-size of the image. Omitted if there is no image attached. - "og:image": - type: string - format: uri - description: |- - An [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris) to the image. Omitted if there is no image. - examples: - application/json: { - "og:title": "Matrix Blog Post", - "og:description": "This is a really cool blog post from matrix.org", - "og:image": "mxc://example.com/ascERGshawAWawugaAcauga", - "og:image:type": "image/png", - "og:image:height": 48, - "og:image:width": 48, - "matrix:image:size": 102400 - } - 429: + content: + application/json: + schema: + type: object + properties: + matrix:image:size: + type: integer + format: int64 + description: The byte-size of the image. Omitted if there is no image attached. + og:image: + type: string + format: uri + description: An [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris) to + the image. Omitted if there is no image. + examples: + response: + value: { + "og:title": "Matrix Blog Post", + "og:description": "This is a really cool blog post from matrix.org", + "og:image": "mxc://example.com/ascERGshawAWawugaAcauga", + "og:image:type": "image/png", + "og:image:height": 48, + "og:image:width": 48, + "matrix:image:size": 102400 + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Media - "/media/v3/config": + /media/v3/config: get: summary: Get the configuration for the content repository. description: |- @@ -732,30 +829,48 @@ paths: repository APIs, for example, proxies may enforce a lower upload size limit than is advertised by the server on this endpoint. operationId: getConfig - produces: ["application/json"] security: - accessToken: [] responses: - 200: + "200": description: The public content repository configuration for the matrix server. - schema: - type: object - properties: - m.upload.size: - type: integer - format: int64 - description: |- - The maximum size an upload can be in bytes. - Clients SHOULD use this as a guide when uploading content. - If not listed or null, the size limit should be treated as unknown. - examples: - application/json: { - "m.upload.size": 50000000 - } - 429: + content: + application/json: + schema: + type: object + properties: + m.upload.size: + type: integer + format: int64 + description: |- + The maximum size an upload can be in bytes. + Clients SHOULD use this as a guide when uploading content. + If not listed or null, the size limit should be treated as unknown. + examples: + response: + value: { + "m.upload.size": 50000000 + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/error.yaml" - + content: + application/json: + schema: + $ref: definitions/errors/error.yaml tags: - Media +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/create_room.yaml b/data/api/client-server/create_room.yaml index a39cc4f5..2188a370 100644 --- a/data/api/client-server/create_room.yaml +++ b/data/api/client-server/create_room.yaml @@ -12,23 +12,12 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server Room Creation API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server Room Creation API + version: 1.0.0 paths: - "/createRoom": + /createRoom: post: summary: Create a new room description: |- @@ -76,177 +65,192 @@ paths: operationId: createRoom security: - accessToken: [] - parameters: - - in: body - name: body - description: The desired room configuration. - required: true - schema: - type: object - example: { - "preset": "public_chat", - "room_alias_name": "thepub", - "name": "The Grand Duke Pub", - "topic": "All about happy hour", - "creation_content": { + requestBody: + content: + application/json: + schema: + type: object + example: { + "preset": "public_chat", + "room_alias_name": "thepub", + "name": "The Grand Duke Pub", + "topic": "All about happy hour", + "creation_content": { "m.federate": false + } } - } - properties: - visibility: - type: string - enum: ["public", "private"] - description: |- - A `public` visibility indicates that the room will be shown - in the published room list. A `private` visibility will hide - the room from the published room list. Rooms default to - `private` visibility if this key is not included. NB: This - should not be confused with `join_rules` which also uses the - word `public`. - room_alias_name: - type: string - description: |- - The desired room alias **local part**. If this is included, a - room alias will be created and mapped to the newly created - room. The alias will belong on the *same* homeserver which - created the room. For example, if this was set to "foo" and - sent to the homeserver "example.com" the complete room alias - would be `#foo:example.com`. - - The complete room alias will become the canonical alias for - the room and an `m.room.canonical_alias` event will be sent - into the room. - name: - type: string - description: |- - If this is included, an `m.room.name` event will be sent - into the room to indicate the name of the room. See Room - Events for more information on `m.room.name`. - topic: - type: string - description: |- - If this is included, an `m.room.topic` event will be sent - into the room to indicate the topic for the room. See Room - Events for more information on `m.room.topic`. - invite: - type: array - description: |- - A list of user IDs to invite to the room. This will tell the - server to invite everyone in the list to the newly created room. - items: + properties: + visibility: type: string - invite_3pid: - type: array - description: |- - A list of objects representing third-party IDs to invite into - the room. - items: - type: object - title: Invite3pid - properties: - id_server: - type: string - description: The hostname+port of the identity server which should be used for third-party identifier lookups. - id_access_token: - type: string - description: |- - An access token previously registered with the identity server. Servers - can treat this as optional to distinguish between r0.5-compatible clients - and this specification version. - medium: - type: string - description: |- - The kind of address being passed in the address field, for example `email` - (see [the list of recognised values](/appendices/#3pid-types)). - address: - type: string - description: The invitee's third-party identifier. - required: ["id_server", "id_access_token", "medium", "address"] - room_version: - type: string - description: |- - The room version to set for the room. If not provided, the homeserver is - to use its configured default. If provided, the homeserver will return a - 400 error with the errcode `M_UNSUPPORTED_ROOM_VERSION` if it does not - support the room version. - example: "1" - creation_content: - title: CreationContent - type: object - description: |- - Extra keys, such as `m.federate`, to be added to the content - of the [`m.room.create`](/client-server-api/#mroomcreate) event. The server will overwrite the following - keys: `creator`, `room_version`. Future versions of the specification - may allow the server to overwrite other keys. - initial_state: - type: array - description: |- - A list of state events to set in the new room. This allows - the user to override the default state events set in the new - room. The expected format of the state events are an object - with type, state_key and content keys set. + enum: + - public + - private + description: |- + A `public` visibility indicates that the room will be shown + in the published room list. A `private` visibility will hide + the room from the published room list. Rooms default to + `private` visibility if this key is not included. NB: This + should not be confused with `join_rules` which also uses the + word `public`. + room_alias_name: + type: string + description: |- + The desired room alias **local part**. If this is included, a + room alias will be created and mapped to the newly created + room. The alias will belong on the *same* homeserver which + created the room. For example, if this was set to "foo" and + sent to the homeserver "example.com" the complete room alias + would be `#foo:example.com`. - Takes precedence over events set by `preset`, but gets - overridden by `name` and `topic` keys. - items: + The complete room alias will become the canonical alias for + the room and an `m.room.canonical_alias` event will be sent + into the room. + name: + type: string + description: |- + If this is included, an `m.room.name` event will be sent + into the room to indicate the name of the room. See Room + Events for more information on `m.room.name`. + topic: + type: string + description: |- + If this is included, an `m.room.topic` event will be sent + into the room to indicate the topic for the room. See Room + Events for more information on `m.room.topic`. + invite: + type: array + description: |- + A list of user IDs to invite to the room. This will tell the + server to invite everyone in the list to the newly created room. + items: + type: string + invite_3pid: + type: array + description: |- + A list of objects representing third-party IDs to invite into + the room. + items: + type: object + title: Invite3pid + properties: + id_server: + type: string + description: The hostname+port of the identity server which should be used for + third-party identifier lookups. + id_access_token: + type: string + description: |- + An access token previously registered with the identity server. Servers + can treat this as optional to distinguish between r0.5-compatible clients + and this specification version. + medium: + type: string + description: |- + The kind of address being passed in the address field, for example `email` + (see [the list of recognised values](/appendices/#3pid-types)). + address: + type: string + description: The invitee's third-party identifier. + required: + - id_server + - id_access_token + - medium + - address + room_version: + type: string + description: |- + The room version to set for the room. If not provided, the homeserver is + to use its configured default. If provided, the homeserver will return a + 400 error with the errcode `M_UNSUPPORTED_ROOM_VERSION` if it does not + support the room version. + example: "1" + creation_content: + title: CreationContent type: object - title: StateEvent - properties: - type: - type: string - description: The type of event to send. - state_key: - type: string - description: The state_key of the state event. Defaults to an empty string. - content: - type: object - description: The content of the event. - required: ["type", "content"] - preset: - type: string - enum: ["private_chat", "public_chat", "trusted_private_chat"] - description: |- - Convenience parameter for setting various default state events - based on a preset. + description: |- + Extra keys, such as `m.federate`, to be added to the content + of the [`m.room.create`](/client-server-api/#mroomcreate) event. The server will overwrite the following + keys: `creator`, `room_version`. Future versions of the specification + may allow the server to overwrite other keys. + initial_state: + type: array + description: |- + A list of state events to set in the new room. This allows + the user to override the default state events set in the new + room. The expected format of the state events are an object + with type, state_key and content keys set. - If unspecified, the server should use the `visibility` to determine - which preset to use. A visbility of `public` equates to a preset of - `public_chat` and `private` visibility equates to a preset of - `private_chat`. - is_direct: - type: boolean - description: |- - This flag makes the server set the `is_direct` flag on the - `m.room.member` events sent to the users in `invite` and - `invite_3pid`. See [Direct Messaging](/client-server-api/#direct-messaging) for more information. - power_level_content_override: - title: Power Level Event Content - type: object - description: |- - The power level content to override in the default power level - event. This object is applied on top of the generated - [`m.room.power_levels`](/client-server-api/#mroompower_levels) - event content prior to it being sent to the room. Defaults to - overriding nothing. + Takes precedence over events set by `preset`, but gets + overridden by `name` and `topic` keys. + items: + type: object + title: StateEvent + properties: + type: + type: string + description: The type of event to send. + state_key: + type: string + description: The state_key of the state event. Defaults to an empty string. + content: + type: object + description: The content of the event. + required: + - type + - content + preset: + type: string + enum: + - private_chat + - public_chat + - trusted_private_chat + description: |- + Convenience parameter for setting various default state events + based on a preset. + + If unspecified, the server should use the `visibility` to determine + which preset to use. A visbility of `public` equates to a preset of + `public_chat` and `private` visibility equates to a preset of + `private_chat`. + is_direct: + type: boolean + description: |- + This flag makes the server set the `is_direct` flag on the + `m.room.member` events sent to the users in `invite` and + `invite_3pid`. See [Direct Messaging](/client-server-api/#direct-messaging) for more information. + power_level_content_override: + title: Power Level Event Content + type: object + description: |- + The power level content to override in the default power level + event. This object is applied on top of the generated + [`m.room.power_levels`](/client-server-api/#mroompower_levels) + event content prior to it being sent to the room. Defaults to + overriding nothing. + description: The desired room configuration. + required: true responses: - 200: + "200": description: Information about the newly created room. - schema: - type: object - description: Information about the newly created room. - properties: - room_id: - type: string - description: |- - The created room's ID. - required: ['room_id'] - examples: - application/json: { - "room_id": "!sefiuhWgwghwWgh:example.com" - } - 400: + content: + application/json: + schema: + type: object + description: Information about the newly created room. + properties: + room_id: + type: string + description: The created room's ID. + required: + - room_id + examples: + response: + value: { + "room_id": "!sefiuhWgwghwWgh:example.com" + } + "400": description: |- - + The request is invalid. A meaningful `errcode` and description error text will be returned. Example reasons for rejection include: @@ -266,7 +270,24 @@ paths: of a homeserver which does not support the requested room version. The `errcode` will be `M_UNSUPPORTED_ROOM_VERSION` in these cases. - schema: - "$ref": "definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: definitions/errors/error.yaml tags: - Room creation +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/cross_signing.yaml b/data/api/client-server/cross_signing.yaml index 817aeca9..2f038e80 100644 --- a/data/api/client-server/cross_signing.yaml +++ b/data/api/client-server/cross_signing.yaml @@ -11,23 +11,12 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server Cross Signing API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server Cross Signing API + version: 1.0.0 paths: - "/keys/device_signing/upload": + /keys/device_signing/upload: post: x-addedInMatrixVersion: "1.1" summary: Upload cross-signing keys. @@ -38,87 +27,93 @@ paths: operationId: uploadCrossSigningKeys security: - accessToken: [] - parameters: - - in: body - name: keys - description: |- - The keys to be published. - required: true - schema: - type: object - properties: - master_key: - description: |- - Optional. The user\'s master key. - allOf: - - $ref: definitions/cross_signing_key.yaml - self_signing_key: - description: |- - Optional. The user\'s self-signing key. Must be signed by - the accompanying master key, or by the user\'s most recently - uploaded master key if no master key is included in the - request. - allOf: - - $ref: definitions/cross_signing_key.yaml - user_signing_key: - description: |- - Optional. The user\'s user-signing key. Must be signed by - the accompanying master key, or by the user\'s most recently - uploaded master key if no master key is included in the - request. - allOf: - - $ref: definitions/cross_signing_key.yaml - auth: - description: |- - Additional authentication information for the - user-interactive authentication API. - allOf: - - $ref: "definitions/auth_data.yaml" - example: { - "auth": { - "type": "example.type.foo", - "session": "xxxxx", - "example_credential": "verypoorsharedsecret" - }, - "master_key": { - "user_id": "@alice:example.com", - "usage": ["master"], - "keys": { - "ed25519:base64+master+public+key": "base64+master+public+key", - } - }, - "self_signing_key": { - "user_id": "@alice:example.com", - "usage": ["self_signing"], - "keys": { - "ed25519:base64+self+signing+public+key": "base64+self+signing+master+public+key", + requestBody: + content: + application/json: + schema: + type: object + properties: + master_key: + description: Optional. The user\'s master key. + allOf: + - $ref: definitions/cross_signing_key.yaml + self_signing_key: + description: |- + Optional. The user\'s self-signing key. Must be signed by + the accompanying master key, or by the user\'s most recently + uploaded master key if no master key is included in the + request. + allOf: + - $ref: definitions/cross_signing_key.yaml + user_signing_key: + description: |- + Optional. The user\'s user-signing key. Must be signed by + the accompanying master key, or by the user\'s most recently + uploaded master key if no master key is included in the + request. + allOf: + - $ref: definitions/cross_signing_key.yaml + auth: + description: |- + Additional authentication information for the + user-interactive authentication API. + allOf: + - $ref: definitions/auth_data.yaml + example: { + "auth": { + "type": "example.type.foo", + "session": "xxxxx", + "example_credential": "verypoorsharedsecret" }, - "signatures": { - "@alice:example.com": { - "ed25519:base64+master+public+key": "signature+of+self+signing+key" + "master_key": { + "user_id": "@alice:example.com", + "usage": [ + "master" + ], + "keys": { + "ed25519:base64+master+public+key": "base64+master+public+key" } - } - }, - "user_signing_key": { - "user_id": "@alice:example.com", - "usage": ["user_signing"], - "keys": { - "ed25519:base64+user+signing+public+key": "base64+user+signing+master+public+key", }, - "signatures": { - "@alice:example.com": { - "ed25519:base64+master+public+key": "signature+of+user+signing+key" + "self_signing_key": { + "user_id": "@alice:example.com", + "usage": [ + "self_signing" + ], + "keys": { + "ed25519:base64+self+signing+public+key": "base64+self+signing+master+public+key" + }, + "signatures": { + "@alice:example.com": { + "ed25519:base64+master+public+key": "signature+of+self+signing+key" + } + } + }, + "user_signing_key": { + "user_id": "@alice:example.com", + "usage": [ + "user_signing" + ], + "keys": { + "ed25519:base64+user+signing+public+key": "base64+user+signing+master+public+key" + }, + "signatures": { + "@alice:example.com": { + "ed25519:base64+master+public+key": "signature+of+user+signing+key" + } } } } - } + description: The keys to be published. + required: true responses: - 200: + "200": description: The provided keys were successfully uploaded. - schema: - type: object - example: {} - 400: + content: + application/json: + schema: + type: object + example: {} + "400": description: |- The input was invalid in some way. This can include one of the following error codes: @@ -126,25 +121,29 @@ paths: * `M_INVALID_SIGNATURE`: For example, the self-signing or user-signing key had an incorrect signature. * `M_MISSING_PARAM`: No master key is available. - schema: - type: object - example: { - "errcode": "M_INVALID_SIGNATURE", - "error": "Invalid signature" - } - 403: + content: + application/json: + schema: + type: object + example: { + "errcode": "M_INVALID_SIGNATURE", + "error": "Invalid signature" + } + "403": description: |- The public key of one of the keys is the same as one of the user\'s device IDs, or the request is not authorized for any other reason. - schema: - type: object - example: { - "errcode": "M_FORBIDDEN", - "error": "Key ID in use" - } + content: + application/json: + schema: + type: object + example: { + "errcode": "M_FORBIDDEN", + "error": "Key ID in use" + } tags: - End-to-end encryption - "/keys/signatures/upload": + /keys/signatures/upload: post: x-addedInMatrixVersion: "1.1" summary: Upload cross-signing signatures. @@ -158,91 +157,109 @@ paths: operationId: uploadCrossSigningSignatures security: - accessToken: [] - parameters: - - in: body - name: signatures - description: |- - A map from user ID to key ID to signed JSON objects containing the - signatures to be published. - required: true - schema: - type: object - title: Signatures - additionalProperties: + requestBody: + content: + application/json: + schema: type: object + title: Signatures additionalProperties: type: object - example: { - "@alice:example.com": { - "HIJKLMN": { - "user_id": "@alice:example.com", - "device_id": "HIJKLMN", - "algorithms": [ - "m.olm.v1.curve25519-aes-sha256", - "m.megolm.v1.aes-sha" - ], - "keys": { - "curve25519:HIJKLMN": "base64+curve25519+key", - "ed25519:HIJKLMN": "base64+ed25519+key" + additionalProperties: + type: object + example: { + "@alice:example.com": { + "HIJKLMN": { + "user_id": "@alice:example.com", + "device_id": "HIJKLMN", + "algorithms": [ + "m.olm.v1.curve25519-aes-sha256", + "m.megolm.v1.aes-sha" + ], + "keys": { + "curve25519:HIJKLMN": "base64+curve25519+key", + "ed25519:HIJKLMN": "base64+ed25519+key" + }, + "signatures": { + "@alice:example.com": { + "ed25519:base64+self+signing+public+key": "base64+signature+of+HIJKLMN" + } + } }, - "signatures": { - "@alice:example.com": { - "ed25519:base64+self+signing+public+key": "base64+signature+of+HIJKLMN" + "base64+master+public+key": { + "user_id": "@alice:example.com", + "usage": [ + "master" + ], + "keys": { + "ed25519:base64+master+public+key": "base64+master+public+key" + }, + "signatures": { + "@alice:example.com": { + "ed25519:HIJKLMN": "base64+signature+of+master+key" + } } } }, - "base64+master+public+key": { - "user_id": "@alice:example.com", - "usage": ["master"], - "keys": { - "ed25519:base64+master+public+key": "base64+master+public+key" - }, - "signatures": { - "@alice:example.com": { - "ed25519:HIJKLMN": "base64+signature+of+master+key" - } - } - } - }, - "@bob:example.com": { - "bobs+base64+master+public+key": { - "user_id": "@bob:example.com", - "keys": { - "ed25519:bobs+base64+master+public+key": "bobs+base64+master+public+key" - }, - "usage": ["master"], - "signatures": { - "@alice:example.com": { - "ed25519:base64+user+signing+public+key": "base64+signature+of+bobs+master+key" + "@bob:example.com": { + "bobs+base64+master+public+key": { + "user_id": "@bob:example.com", + "keys": { + "ed25519:bobs+base64+master+public+key": "bobs+base64+master+public+key" + }, + "usage": [ + "master" + ], + "signatures": { + "@alice:example.com": { + "ed25519:base64+user+signing+public+key": "base64+signature+of+bobs+master+key" + } } } } } - } + description: |- + A map from user ID to key ID to signed JSON objects containing the + signatures to be published. + required: true responses: - 200: + "200": description: The provided signatures were processed. - schema: - type: object - properties: - failures: + content: + application/json: + schema: type: object - description: |- - 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: + properties: + failures: type: object - title: Error - example: { - "@alice:example.com": { - "HIJKLMN": { - "errcode": "M_INVALID_SIGNATURE", - "error": "Invalid signature" - } - } - } + description: |- + 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: + type: object + title: Error + example: + "@alice:example.com": + HIJKLMN: + errcode: M_INVALID_SIGNATURE + error: Invalid signature tags: - End-to-end encryption +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/definitions/push_condition.yaml b/data/api/client-server/definitions/push_condition.yaml index 4f2fe472..8a3a9f32 100644 --- a/data/api/client-server/definitions/push_condition.yaml +++ b/data/api/client-server/definitions/push_condition.yaml @@ -30,7 +30,7 @@ properties: the power level event the user needs a minimum power level for. Fields must be specified under the `notifications` property in the power level event's `content`. - x-example: content.body + example: content.body pattern: type: string description: |- diff --git a/data/api/client-server/definitions/push_rule.yaml b/data/api/client-server/definitions/push_rule.yaml index 94a9d320..4f1b41ad 100644 --- a/data/api/client-server/definitions/push_rule.yaml +++ b/data/api/client-server/definitions/push_rule.yaml @@ -17,9 +17,9 @@ type: object properties: actions: items: - type: - - object - - string + oneOf: + - type: object + - type: string type: array description: |- The actions to perform when this rule is matched. diff --git a/data/api/client-server/device_management.yaml b/data/api/client-server/device_management.yaml index 84e5ee23..32d3db9a 100644 --- a/data/api/client-server/device_management.yaml +++ b/data/api/client-server/device_management.yaml @@ -11,126 +11,124 @@ # 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. - -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server device management API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server device management API + version: 1.0.0 paths: - "/devices": + /devices: get: summary: List registered devices for the current user - description: |- - Gets information about all devices for the current user. + description: Gets information about all devices for the current user. operationId: getDevices security: - accessToken: [] responses: - 200: + "200": description: Device information - schema: - type: object - properties: - devices: - type: array - description: A list of all registered devices for this user. - items: - type: object - allOf: - - $ref: "definitions/client_device.yaml" - examples: - application/json: { - "devices": [ - { - "device_id": "QBUAZIFURK", - "display_name": "android", - "last_seen_ip": "1.2.3.4", - "last_seen_ts": 1474491775024 + content: + application/json: + schema: + type: object + properties: + devices: + type: array + description: A list of all registered devices for this user. + items: + type: object + allOf: + - $ref: definitions/client_device.yaml + examples: + response: + value: { + "devices": [ + { + "device_id": "QBUAZIFURK", + "display_name": "android", + "last_seen_ip": "1.2.3.4", + "last_seen_ts": 1474491775024 + } + ] } - ] - } tags: - Device management "/devices/{deviceId}": get: summary: Get a single device - description: |- - Gets information on a single device, by device id. + description: Gets information on a single device, by device id. operationId: getDevice security: - accessToken: [] parameters: - in: path - type: string name: deviceId description: The device to retrieve. required: true - x-example: "QBUAZIFURK" - responses: - 200: - description: Device information + example: QBUAZIFURK schema: - type: object - allOf: - - $ref: "definitions/client_device.yaml" - examples: - application/json: { - "device_id": "QBUAZIFURK", - "display_name": "android", - "last_seen_ip": "1.2.3.4", - "last_seen_ts": 1474491775024 - } - 404: + type: string + responses: + "200": + description: Device information + content: + application/json: + schema: + type: object + allOf: + - $ref: definitions/client_device.yaml + examples: + response: + value: { + "device_id": "QBUAZIFURK", + "display_name": "android", + "last_seen_ip": "1.2.3.4", + "last_seen_ts": 1474491775024 + } + "404": description: The current user has no device with the given ID. tags: - Device management put: summary: Update a device - description: |- - Updates the metadata on the given device. + description: Updates the metadata on the given device. operationId: updateDevice security: - accessToken: [] parameters: - in: path - type: string name: deviceId description: The device to update. required: true - x-example: "QBUAZIFURK" - - in: body - name: body - required: true - description: New information for the device. + example: QBUAZIFURK schema: - type: object - properties: - display_name: - type: string - description: |- - The new display name for this device. If not given, the - display name is unchanged. - example: { "display_name": "My other phone" } - responses: - 200: - description: The device was successfully updated. - examples: - application/json: { + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + display_name: + type: string + description: |- + The new display name for this device. If not given, the + display name is unchanged. + example: { + "display_name": "My other phone" } - schema: - type: object # empty json object - 404: + description: New information for the device. + required: true + responses: + "200": + description: The device was successfully updated. + content: + application/json: + schema: + type: object # empty json object + examples: + response: + value: {} + "404": description: The current user has no device with the given ID. tags: - Device management @@ -145,41 +143,46 @@ paths: - accessToken: [] parameters: - in: path - type: string name: deviceId description: The device to delete. required: true - x-example: "QBUAZIFURK" - - in: body - name: body - required: true + example: QBUAZIFURK schema: - type: object - properties: - auth: - description: |- - Additional authentication information for the - user-interactive authentication API. - allOf: - - "$ref": "definitions/auth_data.yaml" + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + auth: + description: |- + Additional authentication information for the + user-interactive authentication API. + allOf: + - $ref: definitions/auth_data.yaml + required: true responses: - 200: + "200": description: |- The device was successfully removed, or had been removed previously. - schema: - type: object - examples: - application/json: { - } - 401: - description: |- - The homeserver requires additional authentication information. - schema: - "$ref": "definitions/auth_response.yaml" + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "401": + description: The homeserver requires additional authentication information. + content: + application/json: + schema: + $ref: definitions/auth_response.yaml tags: - Device management - "/delete_devices": + /delete_devices: post: summary: Bulk deletion of devices description: |- @@ -189,42 +192,62 @@ paths: operationId: deleteDevices security: - accessToken: [] - parameters: - - in: body - name: body - required: true - schema: - type: object - properties: - devices: - type: array - description: The list of device IDs to delete. - items: - type: string - description: A list of device IDs. - example: ["QBUAZIFURK", "AUIECTSRND"] - auth: - allOf: - - "$ref": "definitions/auth_data.yaml" - description: |- + requestBody: + content: + application/json: + schema: + type: object + properties: + devices: + type: array + description: The list of device IDs to delete. + items: + type: string + description: A list of device IDs. + example: + - QBUAZIFURK + - AUIECTSRND + auth: + allOf: + - $ref: definitions/auth_data.yaml + description: |- Additional authentication information for the user-interactive authentication API. - required: - - devices + required: + - devices + required: true responses: - 200: + "200": description: |- The devices were successfully removed, or had been removed previously. - schema: - type: object - examples: - application/json: { - } - 401: - description: |- - The homeserver requires additional authentication information. - schema: - "$ref": "definitions/auth_response.yaml" + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "401": + description: The homeserver requires additional authentication information. + content: + application/json: + schema: + $ref: definitions/auth_response.yaml tags: - Device management +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/directory.yaml b/data/api/client-server/directory.yaml index 25b854e0..df29fbf8 100644 --- a/data/api/client-server/directory.yaml +++ b/data/api/client-server/directory.yaml @@ -11,21 +11,10 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server Directory API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server Directory API + version: 1.0.0 paths: "/directory/room/{roomAlias}": put: @@ -35,52 +24,64 @@ paths: - accessToken: [] parameters: - in: path - type: string name: roomAlias description: | The room alias to set. Its format is defined [in the appendices](/appendices/#room-aliases). required: true - x-example: "#monkeys:matrix.org" - - in: body - name: body - description: Information about this room alias. - required: true + example: "#monkeys:matrix.org" schema: - type: object - properties: - room_id: - type: string - description: The room ID to set. - required: ['room_id'] - example: { - "room_id": "!abnjk1jdasj98:capuchins.com" - } + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + room_id: + type: string + description: The room ID to set. + required: + - room_id + example: { + "room_id": "!abnjk1jdasj98:capuchins.com" + } + description: Information about this room alias. + required: true responses: - 200: + "200": description: The mapping was created. - examples: - application/json: {} - schema: - type: object - 400: + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "400": description: The given `roomAlias` is not a valid room alias. - examples: - application/json: { - "errcode": "M_INVALID_PARAM", - "error": "Room alias invalid" - } - schema: - "$ref": "definitions/errors/error.yaml" - 409: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_INVALID_PARAM", + "error": "Room alias invalid" + } + "409": description: A room alias with that name already exists. - examples: - application/json: { - "errcode": "M_UNKNOWN", - "error": "Room alias #monkeys:matrix.org already exists." - } - schema: - "$ref": "definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_UNKNOWN", + "error": "Room alias #monkeys:matrix.org already exists." + } tags: - Room directory get: @@ -91,59 +92,68 @@ paths: The server will use the federation API to resolve the alias if the domain part of the alias does not correspond to the server's own domain. - operationId: getRoomIdByAlias parameters: - in: path - type: string name: roomAlias description: | The room alias. Its format is defined [in the appendices](/appendices/#room-aliases). required: true - x-example: "#monkeys:matrix.org" + example: "#monkeys:matrix.org" + schema: + type: string responses: - 200: + "200": description: The room ID and other information for this alias. - schema: - type: object - properties: - room_id: - type: string - description: The room ID for this room alias. - servers: - type: array - description: A list of servers that are aware of this room alias. - items: - type: string - description: A server which is aware of this room alias. - examples: - application/json: { - "room_id": "!abnjk1jdasj98:capuchins.com", - "servers": [ - "capuchins.com", - "matrix.org", - "another.com" - ] - } - 400: + content: + application/json: + schema: + type: object + properties: + room_id: + type: string + description: The room ID for this room alias. + servers: + type: array + description: A list of servers that are aware of this room alias. + items: + type: string + description: A server which is aware of this room alias. + examples: + response: + value: { + "room_id": "!abnjk1jdasj98:capuchins.com", + "servers": [ + "capuchins.com", + "matrix.org", + "another.com" + ] + } + "400": description: The given `roomAlias` is not a valid room alias. - examples: - application/json: { - "errcode": "M_INVALID_PARAM", - "error": "Room alias invalid" - } - schema: - "$ref": "definitions/errors/error.yaml" - 404: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_INVALID_PARAM", + "error": "Room alias invalid" + } + "404": description: There is no mapped room ID for this room alias. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Room alias #monkeys:matrix.org not found." - } - schema: - "$ref": "definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Room alias #monkeys:matrix.org not found." + } tags: - Room directory delete: @@ -160,36 +170,41 @@ paths: canonical alias event are recommended to, in addition to their other relevant permission checks, delete the alias and return a successful response even if the user does not have permission to update the `m.room.canonical_alias` event. - operationId: deleteRoomAlias security: - accessToken: [] parameters: - in: path - type: string name: roomAlias description: | The room alias to remove. Its format is defined [in the appendices](/appendices/#room-aliases). required: true - x-example: "#monkeys:matrix.org" + example: "#monkeys:matrix.org" + schema: + type: string responses: - 200: + "200": description: The mapping was deleted. - examples: - application/json: { - } - schema: - type: object - 404: + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "404": description: There is no mapped room ID for this room alias. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Room alias #monkeys:example.org not found." - } - schema: - "$ref": "definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Room alias #monkeys:example.org not found." + } tags: - Room directory "/rooms/{roomId}/aliases": @@ -212,59 +227,86 @@ paths: Clients are recommended not to display this list of aliases prominently as they are not curated, unlike those listed in the `m.room.canonical_alias` state event. - operationId: getLocalAliases security: - accessToken: [] parameters: - in: path - type: string name: roomId description: The room ID to find local aliases of. required: true - x-example: "!abc123:example.org" + example: "!abc123:example.org" + schema: + type: string responses: - 200: - description: |- - The list of local aliases for the room. - examples: - application/json: { - "aliases": [ - "#somewhere:example.com", - "#another:example.com", - "#hat_trick:example.com" - ] - } - schema: - type: object - properties: - aliases: - type: array - description: The server's local aliases on the room. Can be empty. - items: - type: string - required: ['aliases'] - 400: + "200": + description: The list of local aliases for the room. + content: + application/json: + schema: + type: object + properties: + aliases: + type: array + description: The server's local aliases on the room. Can be empty. + items: + type: string + required: + - aliases + examples: + response: + value: { + "aliases": [ + "#somewhere:example.com", + "#another:example.com", + "#hat_trick:example.com" + ] + } + "400": description: The given `roomAlias` is not a valid room alias. - examples: - application/json: { - "errcode": "M_INVALID_PARAM", - "error": "Room alias invalid" - } - schema: - "$ref": "definitions/errors/error.yaml" - 403: - description: The user is not permitted to retrieve the list of local aliases for the room. - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "You are not a member of the room." - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_INVALID_PARAM", + "error": "Room alias invalid" + } + "403": + description: The user is not permitted to retrieve the list of local aliases for + the room. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "You are not a member of the room." + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Room directory +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/event_context.yaml b/data/api/client-server/event_context.yaml index 4a2541a6..0d740241 100644 --- a/data/api/client-server/event_context.yaml +++ b/data/api/client-server/event_context.yaml @@ -11,21 +11,10 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server Event Context API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server Event Context API + version: 1.0.0 paths: "/rooms/{roomId}/context/{eventId}": get: @@ -42,29 +31,31 @@ paths: - accessToken: [] parameters: - in: path - type: string name: roomId description: The room to get events from. required: true - x-example: "!636q39766251:example.com" + example: "!636q39766251:example.com" + schema: + type: string - in: path - type: string name: eventId description: The event to get context around. required: true - x-example: "$f3h4d129462ha:example.com" + example: $f3h4d129462ha:example.com + schema: + type: string - in: query - type: integer name: limit description: |- The maximum number of context events to return. The limit applies to the sum of the `events_before` and `events_after` arrays. The requested event ID is always returned in `event` even if `limit` is 0. Defaults to 10. - x-example: 3 + example: 3 + schema: + type: integer - in: query name: filter - type: string description: |- A JSON `RoomEventFilter` to filter the returned events with. The filter is only applied to `events_before`, `events_after`, and @@ -73,78 +64,94 @@ paths: homeserver prefers. See [Filtering](/client-server-api/#filtering) for more information. - x-example: "66696p746572" - responses: - 200: - description: The events and state surrounding the requested event. + example: 66696p746572 schema: - type: object - description: The events and state surrounding the requested event. - properties: - start: - type: string - description: |- - A token that can be used to paginate backwards with. - end: - type: string - description: |- - A token that can be used to paginate forwards with. - events_before: - type: array - description: |- - A list of room events that happened just before the - requested event, in reverse-chronological order. - items: - $ref: "definitions/client_event.yaml" - event: - description: |- - Details of the requested event. - allOf: - - $ref: "definitions/client_event.yaml" - events_after: - type: array - description: |- - A list of room events that happened just after the - requested event, in chronological order. - items: - $ref: "definitions/client_event.yaml" - state: - type: array - description: |- - The state of the room at the last event returned. - items: - $ref: "definitions/client_event.yaml" - examples: - application/json: { - "end": "t29-57_2_0_2", - "events_after": [ - { - "room_id": "!636q39766251:example.com", - "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" - } - ], - "event": { - "event_id": "$f3h4d129462ha:example.com", - "room_id": "!636q39766251:example.com", - "$ref": "../../event-schemas/examples/m.room.message$m.image.yaml" - }, - "events_before": [ - { - "room_id": "!636q39766251:example.com", - "$ref": "../../event-schemas/examples/m.room.message$m.file.yaml" - } - ], - "start": "t27-54_2_0_2", - "state": [ - { - "room_id": "!636q39766251:example.com", - "$ref": "../../event-schemas/examples/m.room.create.yaml" - }, - { - "room_id": "!636q39766251:example.com", - "$ref": "../../event-schemas/examples/m.room.member.yaml" - } - ] - } + type: string + responses: + "200": + description: The events and state surrounding the requested event. + content: + application/json: + schema: + type: object + description: The events and state surrounding the requested event. + properties: + start: + type: string + description: A token that can be used to paginate backwards with. + end: + type: string + description: A token that can be used to paginate forwards with. + events_before: + type: array + description: |- + A list of room events that happened just before the + requested event, in reverse-chronological order. + items: + $ref: definitions/client_event.yaml + event: + description: Details of the requested event. + allOf: + - $ref: definitions/client_event.yaml + events_after: + type: array + description: |- + A list of room events that happened just after the + requested event, in chronological order. + items: + $ref: definitions/client_event.yaml + state: + type: array + description: The state of the room at the last event returned. + items: + $ref: definitions/client_event.yaml + examples: + response: + value: { + "end": "t29-57_2_0_2", + "events_after": [ + { + "room_id": "!636q39766251:example.com", + "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" + } + ], + "event": { + "event_id": "$f3h4d129462ha:example.com", + "room_id": "!636q39766251:example.com", + "$ref": "../../event-schemas/examples/m.room.message$m.image.yaml" + }, + "events_before": [ + { + "room_id": "!636q39766251:example.com", + "$ref": "../../event-schemas/examples/m.room.message$m.file.yaml" + } + ], + "start": "t27-54_2_0_2", + "state": [ + { + "room_id": "!636q39766251:example.com", + "$ref": "../../event-schemas/examples/m.room.create.yaml" + }, + { + "room_id": "!636q39766251:example.com", + "$ref": "../../event-schemas/examples/m.room.member.yaml" + } + ] + } tags: - Room participation +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/filter.yaml b/data/api/client-server/filter.yaml index d5575ff5..8405f81e 100644 --- a/data/api/client-server/filter.yaml +++ b/data/api/client-server/filter.yaml @@ -11,20 +11,10 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server filter API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https -basePath: /_matrix/client/v3 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server filter API + version: 1.0.0 paths: "/user/{userId}/filter": post: @@ -38,61 +28,90 @@ paths: - accessToken: [] parameters: - in: path - type: string name: userId required: true - description: - The id of the user uploading the filter. The access token must be + description: The id of the user uploading the filter. The access token must be authorized to make requests for this user id. - x-example: "@alice:example.com" - - in: body - name: filter - required: true - description: The filter to upload. + example: "@alice:example.com" schema: - type: object - allOf: - - $ref: "definitions/sync_filter.yaml" - example: { - "room": { - "state": { - "types": ["m.room.*"], - "not_rooms": ["!726s6s6q:example.com"] + type: string + requestBody: + content: + application/json: + schema: + type: object + allOf: + - $ref: definitions/sync_filter.yaml + example: { + "room": { + "state": { + "types": [ + "m.room.*" + ], + "not_rooms": [ + "!726s6s6q:example.com" + ] + }, + "timeline": { + "limit": 10, + "types": [ + "m.room.message" + ], + "not_rooms": [ + "!726s6s6q:example.com" + ], + "not_senders": [ + "@spam:example.com" + ] + }, + "ephemeral": { + "types": [ + "m.receipt", + "m.typing" + ], + "not_rooms": [ + "!726s6s6q:example.com" + ], + "not_senders": [ + "@spam:example.com" + ] + } }, - "timeline": { - "limit": 10, - "types": ["m.room.message"], - "not_rooms": ["!726s6s6q:example.com"], - "not_senders": ["@spam:example.com"] + "presence": { + "types": [ + "m.presence" + ], + "not_senders": [ + "@alice:example.com" + ] }, - "ephemeral": { - "types": ["m.receipt", "m.typing"], - "not_rooms": ["!726s6s6q:example.com"], - "not_senders": ["@spam:example.com"] - } - }, - "presence": { - "types": ["m.presence"], - "not_senders": ["@alice:example.com"] - }, - "event_format": "client", - "event_fields": ["type", "content", "sender"] - } + "event_format": "client", + "event_fields": [ + "type", + "content", + "sender" + ] + } + description: The filter to upload. + required: true responses: - 200: + "200": description: The filter was created. - schema: - type: object - properties: - filter_id: - type: string - description: |- - The ID of the filter that was created. Cannot start - with a `{` as this character is used to determine - if the filter provided is inline JSON or a previously - declared filter by homeservers on some APIs. - example: "66696p746572" - required: ['filter_id'] + content: + application/json: + schema: + type: object + properties: + filter_id: + type: string + description: |- + The ID of the filter that was created. Cannot start + with a `{` as this character is used to determine + if the filter provided is inline JSON or a previously + declared filter by homeservers on some APIs. + example: 66696p746572 + required: + - filter_id tags: - Room participation "/user/{userId}/filter/{filterId}": @@ -104,53 +123,95 @@ paths: parameters: - in: path name: userId - type: string - description: |- - The user ID to download a filter for. - x-example: "@alice:example.com" + description: The user ID to download a filter for. required: true + example: "@alice:example.com" + schema: + type: string - in: path name: filterId - type: string - description: |- - The filter ID to download. - x-example: "66696p746572" + description: The filter ID to download. required: true - responses: - 200: - description: |- - The filter definition. - examples: - application/json: { - "room": { - "state": { - "types": ["m.room.*"], - "not_rooms": ["!726s6s6q:example.com"] - }, - "timeline": { - "limit": 10, - "types": ["m.room.message"], - "not_rooms": ["!726s6s6q:example.com"], - "not_senders": ["@spam:example.com"] - }, - "ephemeral": { - "types": ["m.receipt", "m.typing"], - "not_rooms": ["!726s6s6q:example.com"], - "not_senders": ["@spam:example.com"] - } - }, - "presence": { - "types": ["m.presence"], - "not_senders": ["@alice:example.com"] - }, - "event_format": "client", - "event_fields": ["type", "content", "sender"] - } + example: 66696p746572 schema: - type: object - allOf: - - $ref: "definitions/sync_filter.yaml" - 404: - description: "Unknown filter." + type: string + responses: + "200": + description: The filter definition. + content: + application/json: + schema: + type: object + allOf: + - $ref: definitions/sync_filter.yaml + examples: + response: + value: { + "room": { + "state": { + "types": [ + "m.room.*" + ], + "not_rooms": [ + "!726s6s6q:example.com" + ] + }, + "timeline": { + "limit": 10, + "types": [ + "m.room.message" + ], + "not_rooms": [ + "!726s6s6q:example.com" + ], + "not_senders": [ + "@spam:example.com" + ] + }, + "ephemeral": { + "types": [ + "m.receipt", + "m.typing" + ], + "not_rooms": [ + "!726s6s6q:example.com" + ], + "not_senders": [ + "@spam:example.com" + ] + } + }, + "presence": { + "types": [ + "m.presence" + ], + "not_senders": [ + "@alice:example.com" + ] + }, + "event_format": "client", + "event_fields": [ + "type", + "content", + "sender" + ] + } + "404": + description: Unknown filter. tags: - Room participation +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/inviting.yaml b/data/api/client-server/inviting.yaml index 53439e95..ce5d503d 100644 --- a/data/api/client-server/inviting.yaml +++ b/data/api/client-server/inviting.yaml @@ -11,21 +11,10 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server Room Joining API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server Room Joining API + version: 1.0.0 paths: # With an extra " " to disambiguate from the 3pid invite endpoint # The extra space makes it sort first for what I'm sure is a good reason. @@ -47,48 +36,53 @@ paths: If the user was invited to the room, the homeserver will append a `m.room.member` event to the room. - operationId: inviteUser security: - accessToken: [] parameters: - in: path - type: string name: roomId description: The room identifier (not alias) to which to invite the user. required: true - x-example: "!d41d8cd:matrix.org" - - in: body - name: body - required: true + example: "!d41d8cd:matrix.org" schema: - type: object - example: { - "user_id": "@cheeky_monkey:matrix.org", - "reason": "Welcome to the team!" - } - properties: - user_id: - type: string - description: The fully qualified user ID of the invitee. - reason: - x-addedInMatrixVersion: "1.1" - type: string - description: |- - Optional reason to be included as the `reason` on the subsequent - membership event. - required: ["user_id"] - responses: - 200: - description: The user has been invited to join the room, or was already invited to the room. - examples: - application/json: { + type: string + requestBody: + content: + application/json: + schema: + type: object + example: { + "user_id": "@cheeky_monkey:matrix.org", + "reason": "Welcome to the team!" } - schema: - type: object - 400: + properties: + user_id: + type: string + description: The fully qualified user ID of the invitee. + reason: + x-addedInMatrixVersion: "1.1" + type: string + description: |- + Optional reason to be included as the `reason` on the subsequent + membership event. + required: + - user_id + required: true + responses: + "200": + description: The user has been invited to join the room, or was already invited + to the room. + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "400": description: |- - + The request is invalid. A meaningful `errcode` and description error text will be returned. Example reasons for rejection include: @@ -98,9 +92,11 @@ paths: - One or more users being invited to the room are residents of a homeserver which does not support the requested room version. The `errcode` will be `M_UNSUPPORTED_ROOM_VERSION` in these cases. - schema: - "$ref": "definitions/errors/error.yaml" - 403: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + "403": description: |- You do not have permission to invite the user to the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are: @@ -108,14 +104,36 @@ paths: - The invitee is already a member of the room. - The inviter is not currently in the room. - The inviter's power level is insufficient to invite users to the room. - examples: - application/json: { - "errcode": "M_FORBIDDEN", "error": "@cheeky_monkey:matrix.org is banned from the room"} - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "@cheeky_monkey:matrix.org is banned from the room" + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Room membership +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/joining.yaml b/data/api/client-server/joining.yaml index 48d630c4..020c5a0e 100644 --- a/data/api/client-server/joining.yaml +++ b/data/api/client-server/joining.yaml @@ -11,21 +11,10 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server Room Inviting API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server Room Inviting API + version: 1.0.0 paths: "/rooms/{roomId}/join": post: @@ -47,48 +36,55 @@ paths: - accessToken: [] parameters: - in: path - type: string name: roomId description: The room identifier (not alias) to join. required: true - x-example: "!d41d8cd:matrix.org" - - in: body - name: body - required: true + example: "!d41d8cd:matrix.org" schema: - type: object - properties: - third_party_signed: - allOf: - - $ref: "definitions/third_party_signed.yaml" - description: |- - If supplied, the homeserver must verify that it matches a pending - `m.room.third_party_invite` event in the room, and perform - key validity checking if required by the event. - reason: - x-addedInMatrixVersion: "1.1" - type: string - description: |- - Optional reason to be included as the `reason` on the subsequent - membership event. - example: "Looking for support" + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + third_party_signed: + allOf: + - $ref: definitions/third_party_signed.yaml + description: |- + If supplied, the homeserver must verify that it matches a pending + `m.room.third_party_invite` event in the room, and perform + key validity checking if required by the event. + reason: + x-addedInMatrixVersion: "1.1" + type: string + description: |- + Optional reason to be included as the `reason` on the subsequent + membership event. + example: Looking for support + required: true responses: - 200: + "200": description: |- The room has been joined. The joined room ID must be returned in the `room_id` field. - examples: - application/json: { - "room_id": "!d41d8cd:matrix.org"} - schema: - type: object - properties: - room_id: - type: string - description: The joined room ID. - required: ["room_id"] - 403: + content: + application/json: + schema: + type: object + properties: + room_id: + type: string + description: The joined room ID. + required: + - room_id + examples: + response: + value: { + "room_id": "!d41d8cd:matrix.org" + } + "403": description: |- You do not have permission to join the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejection are: @@ -96,15 +92,22 @@ paths: - The room is invite-only and the user was not invited. - The user has been banned from the room. - The room is restricted and the user failed to satisfy any of the conditions. - examples: - application/json: { - "errcode": "M_FORBIDDEN", "error": "You are not invited to this room."} - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "You are not invited to this room." + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Room membership "/join/{roomIdOrAlias}": @@ -126,57 +129,67 @@ paths: - accessToken: [] parameters: - in: path - type: string name: roomIdOrAlias description: The room identifier or alias to join. required: true - x-example: "#monkeys:matrix.org" - - in: query - type: array - items: + example: "#monkeys:matrix.org" + schema: type: string + - in: query name: server_name description: |- The servers to attempt to join the room through. One of the servers must be participating in the room. - x-example: ["matrix.org", "elsewhere.ca"] - - in: body - name: body - required: true + example: + - matrix.org + - elsewhere.ca schema: - type: object - properties: - third_party_signed: - allOf: - - $ref: "definitions/third_party_signed.yaml" - description: |- - If a `third_party_signed` was supplied, the homeserver must verify - that it matches a pending `m.room.third_party_invite` event in the - room, and perform key validity checking if required by the event. - reason: - x-addedInMatrixVersion: "1.1" - type: string - description: |- - Optional reason to be included as the `reason` on the subsequent - membership event. - example: "Looking for support" + type: array + items: + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + third_party_signed: + allOf: + - $ref: definitions/third_party_signed.yaml + description: |- + If a `third_party_signed` was supplied, the homeserver must verify + that it matches a pending `m.room.third_party_invite` event in the + room, and perform key validity checking if required by the event. + reason: + x-addedInMatrixVersion: "1.1" + type: string + description: |- + Optional reason to be included as the `reason` on the subsequent + membership event. + example: Looking for support + required: true responses: - 200: + "200": description: |- The room has been joined. The joined room ID must be returned in the `room_id` field. - examples: - application/json: { - "room_id": "!d41d8cd:matrix.org"} - schema: - type: object - properties: - room_id: - type: string - description: The joined room ID. - required: ["room_id"] - 403: + content: + application/json: + schema: + type: object + properties: + room_id: + type: string + description: The joined room ID. + required: + - room_id + examples: + response: + value: { + "room_id": "!d41d8cd:matrix.org" + } + "403": description: |- You do not have permission to join the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejection are: @@ -184,14 +197,36 @@ paths: - The room is invite-only and the user was not invited. - The user has been banned from the room. - The room is restricted and the user failed to satisfy any of the conditions. - examples: - application/json: { - "errcode": "M_FORBIDDEN", "error": "You are not invited to this room."} - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "You are not invited to this room." + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Room membership +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/key_backup.yaml b/data/api/client-server/key_backup.yaml index 0622d761..cd7cf5a0 100644 --- a/data/api/client-server/key_backup.yaml +++ b/data/api/client-server/key_backup.yaml @@ -11,164 +11,153 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server Key Backup API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server Key Backup API + version: 1.0.0 paths: - "/room_keys/version": + /room_keys/version: post: x-addedInMatrixVersion: "1.1" summary: Create a new backup. - description: |- - Creates a new backup. + description: Creates a new backup. operationId: postRoomKeysVersion security: - accessToken: [] - parameters: - - in: body - name: version - description: "The backup configuration." - required: true - schema: - type: object - properties: - algorithm: - description: The algorithm used for storing backups. - type: string - enum: ["m.megolm_backup.v1.curve25519-aes-sha2"] - example: "m.megolm_backup.v1.curve25519-aes-sha2" - auth_data: - description: |- - Algorithm-dependent data. See the documentation for the backup - algorithms in [Server-side key backups](/client-server-api/#server-side-key-backups) for more information on the - expected format of the data. - type: object - example: { - "public_key": "abcdefg", - "signatures": { - "@alice:example.org": { - "ed25519:deviceid": "signature" - } - } - } - required: - - algorithm - - auth_data + requestBody: + content: + application/json: + schema: + type: object + properties: + algorithm: + description: The algorithm used for storing backups. + type: string + enum: + - m.megolm_backup.v1.curve25519-aes-sha2 + example: m.megolm_backup.v1.curve25519-aes-sha2 + auth_data: + description: |- + Algorithm-dependent data. See the documentation for the backup + algorithms in [Server-side key backups](/client-server-api/#server-side-key-backups) for more information on the + expected format of the data. + type: object + example: + public_key: abcdefg + signatures: + "@alice:example.org": + ed25519:deviceid: signature + required: + - algorithm + - auth_data + description: The backup configuration. + required: true responses: - 200: - description: - The version id of the new backup. - schema: - type: object - properties: - version: - type: string - description: The backup version. This is an opaque string. - example: "1" - required: - - version - 429: + "200": + description: The version id of the new backup. + content: + application/json: + schema: + type: object + properties: + version: + type: string + description: The backup version. This is an opaque string. + example: "1" + required: + - version + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - End-to-end encryption get: x-addedInMatrixVersion: "1.1" summary: Get information about the latest backup version. - description: |- - Get information about the latest backup version. + description: Get information about the latest backup version. operationId: getRoomKeysVersionCurrent security: - accessToken: [] responses: - 200: - description: - The information about the backup. - schema: - type: object - properties: - algorithm: - type: string - description: The algorithm used for storing backups. - enum: ["m.megolm_backup.v1.curve25519-aes-sha2"] - example: "m.megolm_backup.v1.curve25519-aes-sha2" - auth_data: - description: |- - Algorithm-dependent data. See the documentation for the backup - algorithms in [Server-side key backups](/client-server-api/#server-side-key-backups) for more information on the - expected format of the data. + "200": + description: The information about the backup. + content: + application/json: + schema: type: object - example: { - "public_key": "abcdefg", - "signatures": { - "@alice:example.org": { - "ed25519:deviceid": "signature" - } + properties: + algorithm: + type: string + description: The algorithm used for storing backups. + enum: + - m.megolm_backup.v1.curve25519-aes-sha2 + example: m.megolm_backup.v1.curve25519-aes-sha2 + auth_data: + description: |- + Algorithm-dependent data. See the documentation for the backup + algorithms in [Server-side key backups](/client-server-api/#server-side-key-backups) for more information on the + expected format of the data. + type: object + example: + public_key: abcdefg + signatures: + "@alice:example.org": + ed25519:deviceid: signature + count: + description: The number of keys stored in the backup. + type: integer + example: 42 + etag: + description: |- + An opaque string representing stored keys in the backup. + Clients can compare it with the `etag` value they received + in the request of their last key storage request. If not + equal, another client has modified the backup. + type: string + example: anopaquestring + version: + type: string + description: The backup version. + example: "1" + required: + - algorithm + - auth_data + - count + - etag + - version + "404": + description: No backup exists. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "No current backup version" } - } - count: - description: The number of keys stored in the backup. - type: integer - example: 42 - etag: - description: |- - An opaque string representing stored keys in the backup. - Clients can compare it with the `etag` value they received - in the request of their last key storage request. If not - equal, another client has modified the backup. - type: string - example: "anopaquestring" - version: - type: string - description: The backup version. - example: "1" - required: - - algorithm - - auth_data - - count - - etag - - version - 404: - description: - No backup exists. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "No current backup version" - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - End-to-end encryption "/room_keys/version/{version}": get: x-addedInMatrixVersion: "1.1" summary: Get information about an existing backup. - description: |- - Get information about an existing backup. + description: Get information about an existing backup. operationId: getRoomKeysVersion security: - accessToken: [] parameters: - in: path - type: string name: version description: |- The backup version to get, as returned in the `version` parameter @@ -176,82 +165,86 @@ paths: [`POST /_matrix/client/v3/room_keys/version`](/client-server-api/#post_matrixclientv3room_keysversion) or this endpoint. required: true - x-example: "1" + example: "1" + schema: + type: string responses: - 200: - description: - The information about the requested backup. - schema: - type: object - properties: - algorithm: - type: string - description: The algorithm used for storing backups. - enum: ["m.megolm_backup.v1.curve25519-aes-sha2"] - example: "m.megolm_backup.v1.curve25519-aes-sha2" - auth_data: - description: |- - Algorithm-dependent data. See the documentation for the backup - algorithms in [Server-side key backups](/client-server-api/#server-side-key-backups) for more information on the - expected format of the data. + "200": + description: The information about the requested backup. + content: + application/json: + schema: type: object - example: { - "public_key": "abcdefg", - "signatures": { - "@alice:example.org": { - "ed25519:deviceid": "signature" - } + properties: + algorithm: + type: string + description: The algorithm used for storing backups. + enum: + - m.megolm_backup.v1.curve25519-aes-sha2 + example: m.megolm_backup.v1.curve25519-aes-sha2 + auth_data: + description: |- + Algorithm-dependent data. See the documentation for the backup + algorithms in [Server-side key backups](/client-server-api/#server-side-key-backups) for more information on the + expected format of the data. + type: object + example: + public_key: abcdefg + signatures: + "@alice:example.org": + ed25519:deviceid: signature + count: + description: The number of keys stored in the backup. + type: integer + example: 42 + etag: + description: |- + An opaque string representing stored keys in the backup. + Clients can compare it with the `etag` value they received + in the request of their last key storage request. If not + equal, another client has modified the backup. + type: string + example: anopaquestring + version: + type: string + description: The backup version. + example: "1" + required: + - algorithm + - auth_data + - count + - etag + - version + "404": + description: The backup specified does not exist. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Unknown backup version" } - } - count: - description: The number of keys stored in the backup. - type: integer - example: 42 - etag: - description: |- - An opaque string representing stored keys in the backup. - Clients can compare it with the `etag` value they received - in the request of their last key storage request. If not - equal, another client has modified the backup. - type: string - example: "anopaquestring" - version: - type: string - description: The backup version. - example: "1" - required: - - algorithm - - auth_data - - count - - etag - - version - 404: - description: - The backup specified does not exist. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Unknown backup version" - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - End-to-end encryption put: x-addedInMatrixVersion: "1.1" summary: Update information about an existing backup. - description: |- - Update information about an existing backup. Only `auth_data` can be modified. + description: Update information about an existing backup. Only `auth_data` can + be modified. operationId: putRoomKeysVersion security: - accessToken: [] parameters: - in: path - type: string name: version description: |- The backup version to update, as returned in the `version` @@ -259,76 +252,88 @@ paths: [`POST /_matrix/client/v3/room_keys/version`](/client-server-api/#post_matrixclientv3room_keysversion) or [`GET /_matrix/client/v3/room_keys/version/{version}`](/client-server-api/#get_matrixclientv3room_keysversionversion). required: true - x-example: "1" - - in: body - name: version - description: "The backup configuration" - required: true + example: "1" schema: - type: object - properties: - algorithm: - description: |- - The algorithm used for storing backups. Must be the same as - the algorithm currently used by the backup. - type: string - enum: ["m.megolm_backup.v1.curve25519-aes-sha2"] - example: "m.megolm_backup.v1.curve25519-aes-sha2" - auth_data: - description: |- - Algorithm-dependent data. See the documentation for the backup - algorithms in [Server-side key backups](/client-server-api/#server-side-key-backups) for more information on the - expected format of the data. - type: object - example: { - "public_key": "abcdefg", - "signatures": { - "@alice:example.org": { - "ed25519:deviceid": "signature" - } - } - } - version: - description: |- - The backup version. If present, must be the same as the - version in the path parameter. - type: string - example: "1" - required: - - algorithm - - auth_data + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + algorithm: + description: |- + The algorithm used for storing backups. Must be the same as + the algorithm currently used by the backup. + type: string + enum: + - m.megolm_backup.v1.curve25519-aes-sha2 + example: m.megolm_backup.v1.curve25519-aes-sha2 + auth_data: + description: |- + Algorithm-dependent data. See the documentation for the backup + algorithms in [Server-side key backups](/client-server-api/#server-side-key-backups) for more information on the + expected format of the data. + type: object + example: + public_key: abcdefg + signatures: + "@alice:example.org": + ed25519:deviceid: signature + version: + description: |- + The backup version. If present, must be the same as the + version in the path parameter. + type: string + example: "1" + required: + - algorithm + - auth_data + description: The backup configuration + required: true responses: - 200: + "200": description: The update succeeded. - examples: - application/json: {} - schema: - type: object - 400: + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "400": description: |- A parameter was incorrect. For example, the `algorithm` does not match the current backup algorithm, or the `version` in the body does not match the `version` in the path. - examples: - application/json: { - "errcode": "M_INVALID_PARAM", - "error": "Algorithm does not match" - } - schema: - "$ref": "definitions/errors/error.yaml" - 404: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_INVALID_PARAM", + "error": "Algorithm does not match" + } + "404": description: The backup specified does not exist. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Unknown backup version" - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Unknown backup version" + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - End-to-end encryption delete: @@ -342,7 +347,6 @@ paths: - accessToken: [] parameters: - in: path - type: string name: version description: |- The backup version to delete, as returned in the `version` @@ -350,611 +354,689 @@ paths: [`POST /_matrix/client/v3/room_keys/version`](/client-server-api/#post_matrixclientv3room_keysversion) or [`GET /_matrix/client/v3/room_keys/version/{version}`](/client-server-api/#get_matrixclientv3room_keysversionversion). required: true - x-example: "1" + example: "1" + schema: + type: string responses: - 200: + "200": description: |- The delete succeeded, or the specified backup was previously deleted. - schema: - type: object - properties: {} - 404: + content: + application/json: + schema: + type: object + properties: {} + "404": description: |- The backup specified does not exist. If the backup was previously deleted, the call should succeed rather than returning an error. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Unknown backup version" - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Unknown backup version" + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - End-to-end encryption "/room_keys/keys/{roomId}/{sessionId}": put: x-addedInMatrixVersion: "1.1" summary: Store a key in the backup. - description: |- - Store a key in the backup. + description: Store a key in the backup. operationId: putRoomKeyBySessionId security: - accessToken: [] parameters: - in: query - type: string name: version - description: |- - The backup in which to store the key. Must be the current backup. + description: The backup in which to store the key. Must be the current backup. required: true - x-example: "1" + example: "1" + schema: + type: string - in: path - type: string name: roomId description: The ID of the room that the key is for. required: true - x-example: "!roomid:example.org" + example: "!roomid:example.org" + schema: + type: string - in: path - type: string name: sessionId description: The ID of the megolm session that the key is for. required: true - x-example: "sessionid" - - in: body - name: data - description: "The key data." - required: true + example: sessionid schema: - "$ref": "definitions/key_backup_data.yaml" + type: string + requestBody: + content: + application/json: + schema: + $ref: definitions/key_backup_data.yaml + description: The key data. + required: true responses: - 200: + "200": description: The update succeeded. - schema: - type: object - title: RoomKeysUpdateResponse - properties: - etag: - description: |- - The new etag value representing stored keys in the backup. - See `GET /room_keys/version/{version}` for more details. - type: string - example: "abcdefg" - count: - description: The number of keys stored in the backup - type: integer - example: 10 - required: - - etag - - count - 403: + content: + application/json: + schema: + type: object + title: RoomKeysUpdateResponse + properties: + etag: + description: |- + The new etag value representing stored keys in the backup. + See `GET /room_keys/version/{version}` for more details. + type: string + example: abcdefg + count: + description: The number of keys stored in the backup + type: integer + example: 10 + required: + - etag + - count + "403": description: |- The version specified does not match the current backup version. The current version will be included in the `current_version` field. - examples: - application/json: { - "errcode": "M_WRONG_ROOM_KEYS_VERSION", - "error": "Wrong backup version.", - "current_version": "42" - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_WRONG_ROOM_KEYS_VERSION", + "error": "Wrong backup version.", + "current_version": "42" + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - End-to-end encryption get: x-addedInMatrixVersion: "1.1" summary: Retrieve a key from the backup. - description: |- - Retrieve a key from the backup. + description: Retrieve a key from the backup. operationId: getRoomKeyBySessionId security: - accessToken: [] parameters: - in: query - type: string name: version - description: |- - The backup from which to retrieve the key. + description: The backup from which to retrieve the key. required: true - x-example: "1" + example: "1" + schema: + type: string - in: path - type: string name: roomId description: The ID of the room that the requested key is for. required: true - x-example: "!roomid:example.org" + example: "!roomid:example.org" + schema: + type: string - in: path - type: string name: sessionId description: The ID of the megolm session whose key is requested. required: true - x-example: "sessionid" + example: sessionid + schema: + type: string responses: - 200: + "200": description: The key data - schema: - "$ref": "definitions/key_backup_data.yaml" - 404: + content: + application/json: + schema: + $ref: definitions/key_backup_data.yaml + "404": description: The key or backup was not found. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Key not found." - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Key not found." + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - End-to-end encryption delete: x-addedInMatrixVersion: "1.1" summary: Delete a key from the backup. - description: |- - Delete a key from the backup. + description: Delete a key from the backup. operationId: deleteRoomKeyBySessionId security: - accessToken: [] parameters: - in: query - type: string name: version - description: |- - The backup from which to delete the key + description: The backup from which to delete the key required: true - x-example: "1" + example: "1" + schema: + type: string - in: path - type: string name: roomId description: The ID of the room that the specified key is for. required: true - x-example: "!roomid:example.org" + example: "!roomid:example.org" + schema: + type: string - in: path - type: string name: sessionId description: The ID of the megolm session whose key is to be deleted. required: true - x-example: "sessionid" + example: sessionid + schema: + type: string responses: - 200: + "200": description: The update succeeded - schema: - type: object - title: RoomKeysUpdateResponse - properties: - etag: - description: |- - The new etag value representing stored keys in the backup. - See `GET /room_keys/version/{version}` for more details. - type: string - example: "abcdefg" - count: - description: The number of keys stored in the backup - type: integer - example: 10 - required: - - etag - - count - 404: - description: |- - The backup was not found. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Unknown backup version" - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + type: object + title: RoomKeysUpdateResponse + properties: + etag: + description: |- + The new etag value representing stored keys in the backup. + See `GET /room_keys/version/{version}` for more details. + type: string + example: abcdefg + count: + description: The number of keys stored in the backup + type: integer + example: 10 + required: + - etag + - count + "404": + description: The backup was not found. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Unknown backup version" + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - End-to-end encryption "/room_keys/keys/{roomId}": put: x-addedInMatrixVersion: "1.1" summary: Store several keys in the backup for a given room. - description: |- - Store several keys in the backup for a given room. + description: Store several keys in the backup for a given room. operationId: putRoomKeysByRoomId security: - accessToken: [] parameters: - in: query - type: string name: version - description: |- - The backup in which to store the keys. Must be the current backup. + description: The backup in which to store the keys. Must be the current backup. required: true - x-example: "1" + example: "1" + schema: + type: string - in: path - type: string name: roomId description: The ID of the room that the keys are for. required: true - x-example: "!roomid:example.org" - - in: body - description: "The backup data" - name: backupData - required: true + example: "!roomid:example.org" schema: - $ref: "definitions/room_key_backup.yaml" + type: string + requestBody: + content: + application/json: + schema: + $ref: definitions/room_key_backup.yaml + description: The backup data + required: true responses: - 200: + "200": description: The update succeeded - schema: - type: object - title: RoomKeysUpdateResponse - properties: - etag: - description: |- - The new etag value representing stored keys in the backup. - See `GET /room_keys/version/{version}` for more details. - type: string - example: "abcdefg" - count: - description: The number of keys stored in the backup - type: integer - example: 10 - required: - - etag - - count - 403: + content: + application/json: + schema: + type: object + title: RoomKeysUpdateResponse + properties: + etag: + description: |- + The new etag value representing stored keys in the backup. + See `GET /room_keys/version/{version}` for more details. + type: string + example: abcdefg + count: + description: The number of keys stored in the backup + type: integer + example: 10 + required: + - etag + - count + "403": description: |- The version specified does not match the current backup version. The current version will be included in the `current_version` field. - examples: - application/json: { - "errcode": "M_WRONG_ROOM_KEYS_VERSION", - "error": "Wrong backup version.", - "current_version": "42" - } - schema: - "$ref": "definitions/errors/error.yaml" - 404: - description: |- - The backup was not found. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Unknown backup version" - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_WRONG_ROOM_KEYS_VERSION", + "error": "Wrong backup version.", + "current_version": "42" + } + "404": + description: The backup was not found. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Unknown backup version" + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - End-to-end encryption get: x-addedInMatrixVersion: "1.1" summary: Retrieve the keys from the backup for a given room. - description: |- - Retrieve the keys from the backup for a given room. + description: Retrieve the keys from the backup for a given room. operationId: getRoomKeysByRoomId security: - accessToken: [] parameters: - in: query - type: string name: version - description: |- - The backup from which to retrieve the key. + description: The backup from which to retrieve the key. required: true - x-example: "1" + example: "1" + schema: + type: string - in: path - type: string name: roomId description: The ID of the room that the requested key is for. required: true - x-example: "!roomid:example.org" + example: "!roomid:example.org" + schema: + type: string responses: - 200: + "200": description: |- The key data. If no keys are found, then an object with an empty `sessions` property will be returned (`{"sessions": {}}`). - schema: - type: object - $ref: "definitions/room_key_backup.yaml" - 404: - description: |- - The backup was not found. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Unknown backup version" - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + type: object + $ref: definitions/room_key_backup.yaml + "404": + description: The backup was not found. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Unknown backup version" + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - End-to-end encryption delete: x-addedInMatrixVersion: "1.1" summary: Delete the keys from the backup for a given room. - description: |- - Delete the keys from the backup for a given room. + description: Delete the keys from the backup for a given room. operationId: deleteRoomKeysByRoomId security: - accessToken: [] parameters: - in: query - type: string name: version - description: |- - The backup from which to delete the key. + description: The backup from which to delete the key. required: true - x-example: "1" + example: "1" + schema: + type: string - in: path - type: string name: roomId description: The ID of the room that the specified key is for. required: true - x-example: "!roomid:example.org" + example: "!roomid:example.org" + schema: + type: string responses: - 200: + "200": description: The update succeeded - schema: - type: object - title: RoomKeysUpdateResponse - properties: - etag: - description: |- - The new etag value representing stored keys in the backup. - See `GET /room_keys/version/{version}` for more details. - type: string - example: "abcdefg" - count: - description: The number of keys stored in the backup - type: integer - example: 10 - required: - - etag - - count - 404: - description: |- - The backup was not found. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Unknown backup version" - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + type: object + title: RoomKeysUpdateResponse + properties: + etag: + description: |- + The new etag value representing stored keys in the backup. + See `GET /room_keys/version/{version}` for more details. + type: string + example: abcdefg + count: + description: The number of keys stored in the backup + type: integer + example: 10 + required: + - etag + - count + "404": + description: The backup was not found. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Unknown backup version" + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - End-to-end encryption - "/room_keys/keys": + /room_keys/keys: put: x-addedInMatrixVersion: "1.1" summary: Store several keys in the backup. - description: |- - Store several keys in the backup. + description: Store several keys in the backup. operationId: putRoomKeys security: - accessToken: [] parameters: - in: query - type: string name: version - description: |- - The backup in which to store the keys. Must be the current backup. - required: true - x-example: "1" - - in: body - description: "The backup data." - name: backupData + description: The backup in which to store the keys. Must be the current backup. required: true + example: "1" schema: - type: object - properties: - rooms: - type: object - description: |- - A map of room IDs to room key backup data. - additionalProperties: - allOf: - - $ref: "definitions/room_key_backup.yaml" - example: { - "!room:example.org": { - "sessions": { - "sessionid1": { - "first_message_index": 1, - "forwarded_count": 0, - "is_verified": true, - "session_data": { - "ephemeral": "base64+ephemeral+key", - "ciphertext": "base64+ciphertext+of+JSON+data", - "mac": "base64+mac+of+ciphertext" - } - } - } - } - } - required: - - rooms + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + rooms: + type: object + description: A map of room IDs to room key backup data. + additionalProperties: + allOf: + - $ref: definitions/room_key_backup.yaml + example: + "!room:example.org": + sessions: + sessionid1: + first_message_index: 1 + forwarded_count: 0 + is_verified: true + session_data: + ephemeral: base64+ephemeral+key + ciphertext: base64+ciphertext+of+JSON+data + mac: base64+mac+of+ciphertext + required: + - rooms + description: The backup data. + required: true responses: - 200: + "200": description: The update succeeded - schema: - type: object - title: RoomKeysUpdateResponse - properties: - etag: - description: |- - The new etag value representing stored keys in the backup. - See `GET /room_keys/version/{version}` for more details. - type: string - example: "abcdefg" - count: - description: The number of keys stored in the backup - type: integer - example: 10 - required: - - etag - - count - 403: + content: + application/json: + schema: + type: object + title: RoomKeysUpdateResponse + properties: + etag: + description: |- + The new etag value representing stored keys in the backup. + See `GET /room_keys/version/{version}` for more details. + type: string + example: abcdefg + count: + description: The number of keys stored in the backup + type: integer + example: 10 + required: + - etag + - count + "403": description: |- The version specified does not match the current backup version. The current version will be included in the `current_version` field. - examples: - application/json: { - "errcode": "M_WRONG_ROOM_KEYS_VERSION", - "error": "Wrong backup version.", - "current_version": "42" - } - schema: - "$ref": "definitions/errors/error.yaml" - 404: - description: |- - The backup was not found. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Unknown backup version" - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_WRONG_ROOM_KEYS_VERSION", + "error": "Wrong backup version.", + "current_version": "42" + } + "404": + description: The backup was not found. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Unknown backup version" + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - End-to-end encryption get: x-addedInMatrixVersion: "1.1" summary: Retrieve the keys from the backup. - description: |- - Retrieve the keys from the backup. + description: Retrieve the keys from the backup. operationId: getRoomKeys security: - accessToken: [] parameters: - in: query - type: string name: version - description: |- - The backup from which to retrieve the keys. + description: The backup from which to retrieve the keys. required: true - x-example: "1" + example: "1" + schema: + type: string responses: - 200: + "200": description: |- The key data. If no keys are found, then an object with an empty `rooms` property will be returned (`{"rooms": {}}`). - schema: - type: object - properties: - rooms: + content: + application/json: + schema: type: object - description: |- - A map of room IDs to room key backup data. - additionalProperties: - allOf: - - $ref: "definitions/room_key_backup.yaml" - example: { - "!room:example.org": { - "sessions": { - "sessionid1": { - "first_message_index": 1, - "forwarded_count": 0, - "is_verified": true, - "session_data": { - "ephemeral": "base64+ephemeral+key", - "ciphertext": "base64+ciphertext+of+JSON+data", - "mac": "base64+mac+of+ciphertext" - } - } - } - } - } - required: - - rooms - 404: + properties: + rooms: + type: object + description: A map of room IDs to room key backup data. + additionalProperties: + allOf: + - $ref: definitions/room_key_backup.yaml + example: + "!room:example.org": + sessions: + sessionid1: + first_message_index: 1 + forwarded_count: 0 + is_verified: true + session_data: + ephemeral: base64+ephemeral+key + ciphertext: base64+ciphertext+of+JSON+data + mac: base64+mac+of+ciphertext + required: + - rooms + "404": description: The backup was not found. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Unknown backup version." - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Unknown backup version." + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - End-to-end encryption delete: x-addedInMatrixVersion: "1.1" summary: Delete the keys from the backup. - description: |- - Delete the keys from the backup. + description: Delete the keys from the backup. operationId: deleteRoomKeys security: - accessToken: [] parameters: - in: query - type: string name: version - description: |- - The backup from which to delete the key + description: The backup from which to delete the key required: true - x-example: "1" + example: "1" + schema: + type: string responses: - 200: + "200": description: The update succeeded - schema: - type: object - title: RoomKeysUpdateResponse - properties: - etag: - description: |- - The new etag value representing stored keys in the backup. - See `GET /room_keys/version/{version}` for more details. - type: string - example: "abcdefg" - count: - description: The number of keys stored in the backup - type: integer - example: 10 - required: - - etag - - count - 404: - description: |- - The backup was not found. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Unknown backup version" - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + type: object + title: RoomKeysUpdateResponse + properties: + etag: + description: |- + The new etag value representing stored keys in the backup. + See `GET /room_keys/version/{version}` for more details. + type: string + example: abcdefg + count: + description: The number of keys stored in the backup + type: integer + example: 10 + required: + - etag + - count + "404": + description: The backup was not found. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Unknown backup version" + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - End-to-end encryption +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/keys.yaml b/data/api/client-server/keys.yaml index 137295c5..cb8a11db 100644 --- a/data/api/client-server/keys.yaml +++ b/data/api/client-server/keys.yaml @@ -13,414 +13,365 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server Client Config API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server Client Config API + version: 1.0.0 paths: - "/keys/upload": + /keys/upload: post: summary: Upload end-to-end encryption keys. - description: |- - Publishes end-to-end encryption keys for the device. + description: Publishes end-to-end encryption keys for the device. operationId: uploadKeys security: - accessToken: [] - parameters: - - in: body - name: keys - description: |- - The keys to be published - required: true - schema: - type: object - properties: - device_keys: - description: |- - Identity keys for the device. May be absent if no new - identity keys are required. - 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 - `:`. The format of the key is determined - by the [key algorithm](/client-server-api/#key-algorithms). + requestBody: + content: + application/json: + schema: + type: object + properties: + device_keys: + description: |- + Identity keys for the device. May be absent if no new + identity keys are required. + 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 + `:`. The format of the key is determined + by the [key algorithm](/client-server-api/#key-algorithms). - May be absent if no new one-time keys are required. - 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" - } - } - } - } - fallback_keys: - 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 - be replaced when additional one-time keys are being uploaded. The - server will notify the client of the fallback key being used through - `/sync`. + May be absent if no new one-time keys are required. + 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 + fallback_keys: + 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 + be replaced when additional one-time keys are being uploaded. The + server will notify the client of the fallback key being used through + `/sync`. - There can only be at most one key per algorithm uploaded, and the server - will only persist one key per algorithm. + There can only be at most one key per algorithm uploaded, and the server + will only persist one key per algorithm. - When uploading a signed key, an additional `fallback: true` key should - be included to denote that the key is a fallback key. + When uploading a signed key, an additional `fallback: true` key should + be included to denote that the key is a fallback key. - May be absent if a new fallback key is not required. - example: { - "curve25519:AAAAAG": "/qyvZvwjiTxGdGU0RCguDCLeR+nmsb3FfNG3/Ve4vU8", - "signed_curve25519:AAAAGj": { - "key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs", - "fallback": true, - "signatures": { - "@alice:example.com": { - "ed25519:JLAFKJWSCS": "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw" - } - } - } - } + May be absent if a new fallback key is not required. + example: + curve25519:AAAAAG: /qyvZvwjiTxGdGU0RCguDCLeR+nmsb3FfNG3/Ve4vU8 + signed_curve25519:AAAAGj: + key: zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs + fallback: true + signatures: + "@alice:example.com": + ed25519:JLAFKJWSCS: FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw + description: The keys to be published + required: true responses: - 200: - description: - The provided keys were successfully uploaded. - schema: - type: object - properties: - one_time_key_counts: + "200": + description: The provided keys were successfully uploaded. + content: + application/json: + schema: type: object - additionalProperties: - type: integer - description: |- - For each key algorithm, the number of unclaimed one-time keys - of that type currently held on the server for this device. - If an algorithm is not listed, the count for that algorithm - is to be assumed zero. - example: - curve25519: 10 - signed_curve25519: 20 - required: - - one_time_key_counts - + properties: + one_time_key_counts: + type: object + additionalProperties: + type: integer + description: |- + For each key algorithm, the number of unclaimed one-time keys + of that type currently held on the server for this device. + If an algorithm is not listed, the count for that algorithm + is to be assumed zero. + example: + curve25519: 10 + signed_curve25519: 20 + required: + - one_time_key_counts tags: - End-to-end encryption - "/keys/query": + /keys/query: post: summary: Download device identity keys. - description: |- - Returns the current devices and identity keys for the given users. + description: Returns the current devices and identity keys for the given users. operationId: queryKeys security: - accessToken: [] - parameters: - - in: body - name: query - description: |- - Query defining the keys to be downloaded - required: true - schema: - type: object - properties: - timeout: - type: integer - description: |- - The time (in milliseconds) to wait when downloading keys from - remote servers. 10 seconds is the recommended default. - example: 10000 - device_keys: - type: object - description: |- - 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" - example: - "@alice:example.com": [] - required: - - device_keys - - responses: - 200: - description: - The device information - schema: - type: object - properties: - failures: - type: object - description: |- - If any remote homeservers could not be reached, they are - recorded here. The names of the properties are the names of - the unreachable servers. - - If the homeserver could be reached, but the user or device - was unknown, no failure is recorded. Instead, the corresponding - user or device is missing from the `device_keys` result. - additionalProperties: - type: object - example: {} - device_keys: - type: object - description: |- - Information on the queried devices. A map from user ID, to a - map from device ID to device information. For each device, - the information returned will be the same as uploaded via - `/keys/upload`, with the addition of an `unsigned` - property. - additionalProperties: + requestBody: + content: + application/json: + schema: + type: object + properties: + timeout: + type: integer + description: |- + The time (in milliseconds) to wait when downloading keys from + remote servers. 10 seconds is the recommended default. + example: 10000 + device_keys: type: object + description: |- + 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: - 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. + type: array + items: + type: string + description: device ID + example: + "@alice:example.com": [] + required: + - device_keys + description: Query defining the keys to be downloaded + required: true + responses: + "200": + description: The device information + content: + application/json: + schema: + type: object + properties: + failures: + type: object + description: |- + If any remote homeservers could not be reached, they are + recorded here. The names of the properties are the names of + the unreachable servers. + + If the homeserver could be reached, but the user or device + was unknown, no failure is recorded. Instead, the corresponding + user or device is missing from the `device_keys` result. + additionalProperties: + type: object + example: {} + device_keys: + type: object + description: |- + Information on the queried devices. A map from user ID, to a + map from device ID to device information. For each device, + 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: - device_display_name: - type: string - description: - The display name which the user set on the device. - example: - "@alice:example.com": - JLAFKJWSCS: { - "user_id": "@alice:example.com", - "device_id": "JLAFKJWSCS", - "algorithms": [ - "m.olm.v1.curve25519-aes-sha2", - "m.megolm.v1.aes-sha2" - ], - "keys": { - "curve25519:JLAFKJWSCS": "3C5BFWi2Y8MaVvjM8M22DBmh24PmgR0nPvJOIArzgyI", - "ed25519:JLAFKJWSCS": "lEuiRJBit0IG6nUf5pUzWTUEsRVVe/HJkoKuEww9ULI" - }, - "signatures": { - "@alice:example.com": { - "ed25519:JLAFKJWSCS": "dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA" - } - }, - "unsigned": { - "device_display_name": "Alice's mobile phone" - } - } - master_keys: - x-addedInMatrixVersion: "1.1" - type: object - description: |- - Information on the master cross-signing keys of the queried users. - A map from user ID, to master key information. For each key, the - information returned will be the same as uploaded via - `/keys/device_signing/upload`, along with the signatures - uploaded via `/keys/signatures/upload` that the requesting user - is allowed to see. - additionalProperties: - allOf: - - $ref: definitions/cross_signing_key.yaml - example: { - "@alice:example.com": { - "user_id": "@alice:example.com", - "usage": ["master"], - "keys": { - "ed25519:base64+master+public+key": "base64+master+public+key", - } - } - } - self_signing_keys: - x-addedInMatrixVersion: "1.1" - type: object - description: |- - Information on the self-signing keys of the queried users. A map - 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: - allOf: - - $ref: definitions/cross_signing_key.yaml - example: { - "@alice:example.com": { - "user_id": "@alice:example.com", - "usage": ["self_signing"], - "keys": { - "ed25519:base64+self+signing+public+key": "base64+self+signing+master+public+key", - }, - "signatures": { - "@alice:example.com": { - "ed25519:base64+master+public+key": "signature+of+self+signing+key" - } - } - } - } - user_signing_keys: - type: object - description: |- - Information on the user-signing key of the user making the - request, if they queried their own device information. A map - from user ID, to user-signing key information. The - information returned will be the same as uploaded via - `/keys/device_signing/upload`. - additionalProperties: - allOf: - - $ref: definitions/cross_signing_key.yaml - example: { - "@alice:example.com": { - "user_id": "@alice:example.com", - "usage": ["user_signing"], - "keys": { - "ed25519:base64+user+signing+public+key": "base64+user+signing+master+public+key", - }, - "signatures": { - "@alice:example.com": { - "ed25519:base64+master+public+key": "signature+of+user+signing+key" - } - } - } - } + 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: + user_id: "@alice:example.com" + device_id: JLAFKJWSCS + algorithms: + - m.olm.v1.curve25519-aes-sha2 + - m.megolm.v1.aes-sha2 + keys: + curve25519:JLAFKJWSCS: 3C5BFWi2Y8MaVvjM8M22DBmh24PmgR0nPvJOIArzgyI + ed25519:JLAFKJWSCS: lEuiRJBit0IG6nUf5pUzWTUEsRVVe/HJkoKuEww9ULI + signatures: + "@alice:example.com": + ed25519:JLAFKJWSCS: dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA + unsigned: + device_display_name: Alice's mobile phone + master_keys: + x-addedInMatrixVersion: "1.1" + type: object + description: |- + Information on the master cross-signing keys of the queried users. + A map from user ID, to master key information. For each key, the + information returned will be the same as uploaded via + `/keys/device_signing/upload`, along with the signatures + uploaded via `/keys/signatures/upload` that the requesting user + is allowed to see. + additionalProperties: + allOf: + - $ref: definitions/cross_signing_key.yaml + example: + "@alice:example.com": + user_id: "@alice:example.com" + usage: + - master + keys: + ed25519:base64+master+public+key: base64+master+public+key + self_signing_keys: + x-addedInMatrixVersion: "1.1" + type: object + description: |- + Information on the self-signing keys of the queried users. A map + 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: + allOf: + - $ref: definitions/cross_signing_key.yaml + example: + "@alice:example.com": + user_id: "@alice:example.com" + usage: + - self_signing + keys: + ed25519:base64+self+signing+public+key: base64+self+signing+master+public+key + signatures: + "@alice:example.com": + ed25519:base64+master+public+key: signature+of+self+signing+key + user_signing_keys: + type: object + description: |- + Information on the user-signing key of the user making the + request, if they queried their own device information. A map + from user ID, to user-signing key information. The + information returned will be the same as uploaded via + `/keys/device_signing/upload`. + additionalProperties: + allOf: + - $ref: definitions/cross_signing_key.yaml + example: + "@alice:example.com": + user_id: "@alice:example.com" + usage: + - user_signing + keys: + ed25519:base64+user+signing+public+key: base64+user+signing+master+public+key + signatures: + "@alice:example.com": + ed25519:base64+master+public+key: signature+of+user+signing+key tags: - End-to-end encryption - "/keys/claim": + /keys/claim: post: summary: Claim one-time encryption keys. - description: |- - Claims one-time keys for use in pre-key messages. + description: Claims one-time keys for use in pre-key messages. operationId: claimKeys security: - accessToken: [] - parameters: - - in: body - name: query - description: |- - Query defining the keys to be claimed - required: true - schema: - type: object - properties: - timeout: - type: integer - description: |- - The time (in milliseconds) to wait when downloading keys from - remote servers. 10 seconds is the recommended default. - example: 10000 - one_time_keys: - type: object - description: |- - The keys to be claimed. A map from user ID, to a map from - device ID to algorithm name. - additionalProperties: + requestBody: + content: + application/json: + schema: + type: object + properties: + timeout: + type: integer + description: |- + The time (in milliseconds) to wait when downloading keys from + remote servers. 10 seconds is the recommended default. + example: 10000 + one_time_keys: type: object + description: |- + The keys to be claimed. A map from user ID, to a map from + device ID to algorithm name. additionalProperties: - type: string - description: algorithm - example: "signed_curve25519" - example: { - "@alice:example.com": { "JLAFKJWSCS": "signed_curve25519" } - } - required: - - one_time_keys - responses: - 200: - description: - The claimed keys. - schema: - type: object - properties: - failures: - type: object - description: |- - If any remote homeservers could not be reached, they are - recorded here. The names of the properties are the names of - the unreachable servers. - - If the homeserver could be reached, but the user or device - was unknown, no failure is recorded. Instead, the corresponding - user or device is missing from the `one_time_keys` result. - additionalProperties: - type: object - example: {} - one_time_keys: - type: object - description: |- - One-time keys for the queried devices. A map from user ID, to a - map from devices to a map from `:` to the key object. - - See the [key algorithms](/client-server-api/#key-algorithms) section for information - on the Key Object format. - - 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" - # 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": { - "signed_curve25519:AAAAHg": { - "key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs", - "signatures": { - "@alice:example.com": { - "ed25519:JLAFKJWSCS": "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw" - } - } - } - } - } - } - required: ['one_time_keys'] + additionalProperties: + type: string + description: algorithm + example: signed_curve25519 + example: + "@alice:example.com": + JLAFKJWSCS: signed_curve25519 + required: + - one_time_keys + description: Query defining the keys to be claimed + required: true + responses: + "200": + description: The claimed keys. + content: + application/json: + schema: + type: object + properties: + failures: + type: object + description: |- + If any remote homeservers could not be reached, they are + recorded here. The names of the properties are the names of + the unreachable servers. + + If the homeserver could be reached, but the user or device + was unknown, no failure is recorded. Instead, the corresponding + user or device is missing from the `one_time_keys` result. + additionalProperties: + type: object + example: {} + one_time_keys: + type: object + description: |- + One-time keys for the queried devices. A map from user ID, to a + map from devices to a map from `:` to the key object. + + See the [key algorithms](/client-server-api/#key-algorithms) section for information + on the Key Object format. + + 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" + # 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: + 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": + /keys/changes: get: summary: Query users with recent device key updates. description: |- @@ -439,48 +390,70 @@ paths: parameters: - in: query name: from - type: string description: |- - The desired start point of the list. Should be the `next_batch` field - from a response to an earlier call to [`/sync`](/client-server-api/#get_matrixclientv3sync). Users who have not - uploaded new device identity keys since this point, nor deleted - existing devices with identity keys since then, will be excluded - from the results. + The desired start point of the list. Should be the `next_batch` field + from a response to an earlier call to [`/sync`](/client-server-api/#get_matrixclientv3sync). Users who have not + uploaded new device identity keys since this point, nor deleted + existing devices with identity keys since then, will be excluded + from the results. required: true - x-example: "s72594_4483_1934" + example: s72594_4483_1934 + schema: + type: string - in: query name: to - type: string description: |- - The desired end point of the list. Should be the `next_batch` - field from a recent call to [`/sync`](/client-server-api/#get_matrixclientv3sync) - typically the most recent - such call. This may be used by the server as a hint to check its - caches are up to date. + The desired end point of the list. Should be the `next_batch` + field from a recent call to [`/sync`](/client-server-api/#get_matrixclientv3sync) - typically the most recent + such call. This may be used by the server as a hint to check its + caches are up to date. required: true - x-example: "s75689_5632_2435" - responses: - 200: - description: - The list of users who updated their devices. + example: s75689_5632_2435 schema: - type: object - properties: - changed: - type: array - items: - type: string - description: |- - The Matrix User IDs of all users who updated their device - identity keys. - example: ["@alice:example.com", "@bob:example.org"] - left: - type: array - items: - type: string - description: |- - The Matrix User IDs of all users who may have left all - the end-to-end encrypted rooms they previously shared - with the user. - example: ["@clara:example.com", "@doug:example.org"] + type: string + responses: + "200": + description: The list of users who updated their devices. + content: + application/json: + schema: + type: object + properties: + changed: + type: array + items: + type: string + description: |- + The Matrix User IDs of all users who updated their device + identity keys. + example: + - "@alice:example.com" + - "@bob:example.org" + left: + type: array + items: + type: string + description: |- + The Matrix User IDs of all users who may have left all + the end-to-end encrypted rooms they previously shared + with the user. + example: + - "@clara:example.com" + - "@doug:example.org" tags: - End-to-end encryption +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/kicking.yaml b/data/api/client-server/kicking.yaml index c0d8f671..6eaa8243 100644 --- a/data/api/client-server/kicking.yaml +++ b/data/api/client-server/kicking.yaml @@ -11,21 +11,10 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server Room Kicking API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server Room Kicking API + version: 1.0.0 paths: "/rooms/{roomId}/kick": post: @@ -43,39 +32,44 @@ paths: - accessToken: [] parameters: - in: path - type: string name: roomId description: The room identifier (not alias) from which the user should be kicked. required: true - x-example: "!e42d8c:matrix.org" - - in: body - name: body - required: true + example: "!e42d8c:matrix.org" schema: - type: object - example: { + type: string + requestBody: + content: + application/json: + schema: + type: object + example: { "reason": "Telling unfunny jokes", "user_id": "@cheeky_monkey:matrix.org" } - properties: - user_id: - type: string - description: The fully qualified user ID of the user being kicked. - reason: - type: string - description: |- - The reason the user has been kicked. This will be supplied as the - `reason` on the target's updated [`m.room.member`](/client-server-api/#mroommember) event. - required: ["user_id"] + properties: + user_id: + type: string + description: The fully qualified user ID of the user being kicked. + reason: + type: string + description: |- + The reason the user has been kicked. This will be supplied as the + `reason` on the target's updated [`m.room.member`](/client-server-api/#mroommember) event. + required: + - user_id + required: true responses: - 200: + "200": description: The user has been kicked from the room. - examples: - application/json: { - } - schema: - type: object - 403: + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "403": description: |- You do not have permission to kick the user from the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are: @@ -83,12 +77,30 @@ paths: - The kicker is not currently in the room. - The kickee is not currently in the room. - The kicker's power level is insufficient to kick users from the room. - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "You do not have a high enough power level to kick from this room." - } - schema: - "$ref": "definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "You do not have a high enough power level to kick from this room." + } tags: - Room membership +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/knocking.yaml b/data/api/client-server/knocking.yaml index c2a760ca..b778f02b 100644 --- a/data/api/client-server/knocking.yaml +++ b/data/api/client-server/knocking.yaml @@ -11,21 +11,10 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server Room Knocking API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server Room Knocking API + version: 1.0.0 paths: "/knock/{roomIdOrAlias}": post: @@ -52,74 +41,107 @@ paths: - accessToken: [] parameters: - in: path - type: string name: roomIdOrAlias description: The room identifier or alias to knock upon. required: true - x-example: "#monkeys:matrix.org" - - in: query - type: array - items: + example: "#monkeys:matrix.org" + schema: type: string + - in: query name: server_name description: |- The servers to attempt to knock on the room through. One of the servers must be participating in the room. - x-example: ["matrix.org", "elsewhere.ca"] - - in: body - name: body - required: true + example: + - matrix.org + - elsewhere.ca schema: - type: object - properties: - reason: - type: string - description: |- - Optional reason to be included as the `reason` on the subsequent - membership event. - example: "Looking for support" + type: array + items: + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + reason: + type: string + description: |- + Optional reason to be included as the `reason` on the subsequent + membership event. + example: Looking for support + required: true responses: - 200: + "200": description: |- The room has been knocked upon. The knocked room ID must be returned in the `room_id` field. - examples: - application/json: { - "room_id": "!d41d8cd:matrix.org" - } - schema: - type: object - properties: - room_id: - type: string - description: The knocked room ID. - required: ["room_id"] - 403: + content: + application/json: + schema: + type: object + properties: + room_id: + type: string + description: The knocked room ID. + required: + - room_id + examples: + response: + value: { + "room_id": "!d41d8cd:matrix.org" + } + "403": description: |- You do not have permission to knock on the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejection are: - The room is not set up for knocking. - The user has been banned from the room. - examples: - application/json: { - "errcode": "M_FORBIDDEN", "error": "You are not allowed to knock on this room." - } - schema: - "$ref": "definitions/errors/error.yaml" - 404: - description: |- - The room could not be found or resolved to a room ID. - examples: - application/json: { - "errcode": "M_NOT_FOUND", "error": "That room does not appear to exist." - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "You are not allowed to knock on this room." + } + "404": + description: The room could not be found or resolved to a room ID. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "That room does not appear to exist." + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Room membership +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/leaving.yaml b/data/api/client-server/leaving.yaml index ce304883..6e7d67d0 100644 --- a/data/api/client-server/leaving.yaml +++ b/data/api/client-server/leaving.yaml @@ -11,21 +11,10 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server Room Leaving API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server Room Leaving API + version: 1.0.0 paths: "/rooms/{roomId}/leave": post: @@ -47,39 +36,44 @@ paths: - accessToken: [] parameters: - in: path - type: string name: roomId description: The room identifier to leave. required: true - x-example: "!nkl290a:matrix.org" - - in: body - name: body - required: true + example: "!nkl290a:matrix.org" schema: - type: object - example: { - "reason": "Saying farewell - thanks for the support!" - } - properties: - reason: - x-addedInMatrixVersion: "1.1" - type: string - description: |- - Optional reason to be included as the `reason` on the subsequent - membership event. - responses: - 200: - description: |- - The room has been left. - examples: - application/json: { + type: string + requestBody: + content: + application/json: + schema: + type: object + example: { + "reason": "Saying farewell - thanks for the support!" } - schema: - type: object - 429: + properties: + reason: + x-addedInMatrixVersion: "1.1" + type: string + description: |- + Optional reason to be included as the `reason` on the subsequent + membership event. + required: true + responses: + "200": + description: The room has been left. + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Room membership "/rooms/{roomId}/forget": @@ -100,32 +94,54 @@ paths: - accessToken: [] parameters: - in: path - type: string name: roomId description: The room identifier to forget. required: true - x-example: "!au1ba7o:matrix.org" + example: "!au1ba7o:matrix.org" + schema: + type: string responses: - 200: - description: |- - The room has been forgotten. - examples: - application/json: { - } - schema: - type: object - 400: + "200": + description: The room has been forgotten. + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "400": description: The user has not left the room - examples: - application/json: { - "errcode": "M_UNKNOWN", - "error": "User @example:matrix.org is in room !au1ba7o:matrix.org" - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_UNKNOWN", + "error": "User @example:matrix.org is in room !au1ba7o:matrix.org" + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Room membership +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/list_joined_rooms.yaml b/data/api/client-server/list_joined_rooms.yaml index 177949bf..68451409 100644 --- a/data/api/client-server/list_joined_rooms.yaml +++ b/data/api/client-server/list_joined_rooms.yaml @@ -11,48 +11,54 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server Room Listing API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server Room Listing API + version: 1.0.0 paths: - "/joined_rooms": + /joined_rooms: get: summary: Lists the user's current rooms. - description: |- - This API returns a list of the user's current rooms. + description: This API returns a list of the user's current rooms. operationId: getJoinedRooms security: - accessToken: [] responses: - 200: + "200": description: A list of the rooms the user is in. - schema: - type: object - required: ["joined_rooms"] - properties: - joined_rooms: - type: array - description: |- - The ID of each room in which the user has `joined` membership. - items: - type: string - examples: - application/json: { - "joined_rooms": [ - "!foo:example.com" - ] - } + content: + application/json: + schema: + type: object + required: + - joined_rooms + properties: + joined_rooms: + type: array + description: The ID of each room in which the user has `joined` membership. + items: + type: string + examples: + response: + value: { + "joined_rooms": [ + "!foo:example.com" + ] + } tags: - Room membership +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/list_public_rooms.yaml b/data/api/client-server/list_public_rooms.yaml index 185a955e..e4f0551b 100644 --- a/data/api/client-server/list_public_rooms.yaml +++ b/data/api/client-server/list_public_rooms.yaml @@ -11,56 +11,56 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server Room Directory API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 -consumes: - - application/json -produces: - - application/json + title: Matrix Client-Server Room Directory API + version: 1.0.0 paths: "/directory/list/room/{roomId}": get: summary: Gets the visibility of a room in the directory - description: |- - Gets the visibility of a given room on the server's public room directory. + description: Gets the visibility of a given room on the server's public room + directory. operationId: getRoomVisibilityOnDirectory parameters: - in: path - type: string name: roomId description: The room ID. required: true - x-example: "!curbf:matrix.org" + example: "!curbf:matrix.org" + schema: + type: string responses: - 200: + "200": description: The visibility of the room in the directory - schema: - type: object - properties: - visibility: - type: string - enum: ['private', 'public'] - description: The visibility of the room in the directory. - examples: - application/json: { - "visibility": "public" - } - 404: + content: + application/json: + schema: + type: object + properties: + visibility: + type: string + enum: + - private + - public + description: The visibility of the room in the directory. + examples: + response: + value: { + "visibility": "public" + } + "404": description: The room is not known to the server - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Room not found" - } - schema: - "$ref": "definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Room not found" + } tags: - Room discovery put: @@ -77,47 +77,56 @@ paths: - accessToken: [] parameters: - in: path - type: string name: roomId description: The room ID. required: true - x-example: "!curbf:matrix.org" - - in: body - name: body - required: true - description: |- - The new visibility for the room on the room directory. + example: "!curbf:matrix.org" schema: - type: object - properties: - visibility: - type: string - enum: ["private", "public"] - description: |- - The new visibility setting for the room. - Defaults to 'public'. - example: { - "visibility": "public" - } + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + visibility: + type: string + enum: + - private + - public + description: |- + The new visibility setting for the room. + Defaults to 'public'. + example: { + "visibility": "public" + } + description: The new visibility for the room on the room directory. + required: true responses: - 200: + "200": description: The visibility was updated, or no change was needed. - examples: - application/json: {} - schema: - type: object - 404: + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "404": description: The room is not known to the server - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Room not found" - } - schema: - "$ref": "definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Room not found" + } tags: - Room discovery - "/publicRooms": + /publicRooms: get: summary: Lists the public rooms on the server. description: |- @@ -129,28 +138,32 @@ paths: parameters: - in: query name: limit - type: integer - description: |- - Limit the number of results returned. + description: Limit the number of results returned. + schema: + type: integer - in: query name: since - type: string description: |- A pagination token from a previous request, allowing clients to get the next (or previous) batch of rooms. The direction of pagination is specified solely by which token is supplied, rather than via an explicit flag. + schema: + type: string - in: query name: server - type: string description: |- The server to fetch the public room lists from. Defaults to the local server. - responses: - 200: - description: A list of the rooms on the server. schema: - $ref: "definitions/public_rooms_response.yaml" + type: string + responses: + "200": + description: A list of the rooms on the server. + content: + application/json: + schema: + $ref: definitions/public_rooms_response.yaml tags: - Room discovery post: @@ -166,35 +179,32 @@ paths: parameters: - in: query name: server - type: string description: |- The server to fetch the public room lists from. Defaults to the local server. - - in: body - name: body - required: true - description: |- - Options for which rooms to return. schema: - type: object - properties: - limit: - type: integer - description: |- - Limit the number of results returned. - since: - type: string - description: |- - A pagination token from a previous request, allowing clients - to get the next (or previous) batch of rooms. The direction - of pagination is specified solely by which token is supplied, - rather than via an explicit flag. - filter: - type: object - title: "Filter" - description: |- - Filter to apply to the results. - properties: + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + limit: + type: integer + description: Limit the number of results returned. + since: + type: string + description: |- + A pagination token from a previous request, allowing clients + to get the next (or previous) batch of rooms. The direction + of pagination is specified solely by which token is supplied, + rather than via an explicit flag. + filter: + type: object + title: Filter + description: Filter to apply to the results. + properties: generic_search_term: type: string description: |- @@ -210,31 +220,50 @@ paths: for. To include rooms without a room type, specify `null` within this list. When not specified, all applicable rooms (regardless of type) are returned. - include_all_networks: - type: boolean - description: |- - Whether or not to include all known networks/protocols from - application services on the homeserver. Defaults to false. - example: false - third_party_instance_id: - type: string - description: |- - The specific third-party network/protocol to request from the - homeserver. Can only be used if `include_all_networks` is false. - example: "irc" - example: { - "limit": 10, - "filter": { - "generic_search_term": "foo", - "room_types": [null, "m.space"] - }, - "include_all_networks": false, - "third_party_instance_id": "irc" - } + include_all_networks: + type: boolean + description: |- + Whether or not to include all known networks/protocols from + application services on the homeserver. Defaults to false. + example: false + third_party_instance_id: + type: string + description: |- + The specific third-party network/protocol to request from the + homeserver. Can only be used if `include_all_networks` is false. + example: irc + example: { + "limit": 10, + "filter": { + "generic_search_term": "foo", + "room_types": [ + null, + "m.space" + ] + }, + "include_all_networks": false, + "third_party_instance_id": "irc" + } + description: Options for which rooms to return. + required: true responses: - 200: + "200": description: A list of the rooms on the server. - schema: - $ref: "definitions/public_rooms_response.yaml" + content: + application/json: + schema: + $ref: definitions/public_rooms_response.yaml tags: - Room discovery +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 diff --git a/data/api/client-server/login.yaml b/data/api/client-server/login.yaml index b62cf2d2..a8953e65 100644 --- a/data/api/client-server/login.yaml +++ b/data/api/client-server/login.yaml @@ -13,23 +13,12 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server Registration and Login API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server Registration and Login API + version: 1.0.0 paths: - "/login": + /login: get: summary: Get the supported login types to authenticate users description: |- @@ -37,45 +26,56 @@ paths: should pick one of these and supply it as the `type` when logging in. operationId: getLoginFlows responses: - 200: + "200": description: The login types the homeserver supports - examples: - application/json: { - "flows": [ - {"type": "m.login.password"}, - {"type": "m.login.token", "get_login_token": true} - ] - } - schema: - type: object - properties: - flows: - type: array - description: The homeserver's supported login types - items: - type: object - title: LoginFlow - required: ['type'] - properties: - type: - description: |- - The login type. This is supplied as the `type` when - logging in. - type: string - get_login_token: - type: boolean - x-addedInMatrixVersion: "1.7" - description: |- - If `type` is `m.login.token`, an optional field to indicate - to the unauthenticated client that the homeserver supports - the [`POST /login/get_token`](/client-server-api/#post_matrixclientv1loginget_token) - endpoint. Note that supporting the endpoint does not - necessarily indicate that the user attempting to log in will - be able to generate such a token. - 429: + content: + application/json: + schema: + type: object + properties: + flows: + type: array + description: The homeserver's supported login types + items: + type: object + title: LoginFlow + required: + - type + properties: + type: + description: |- + The login type. This is supplied as the `type` when + logging in. + type: string + get_login_token: + type: boolean + x-addedInMatrixVersion: "1.7" + description: |- + If `type` is `m.login.token`, an optional field to indicate + to the unauthenticated client that the homeserver supports + the [`POST /login/get_token`](/client-server-api/#post_matrixclientv1loginget_token) + endpoint. Note that supporting the endpoint does not + necessarily indicate that the user attempting to log in will + be able to generate such a token. + examples: + response: + value: { + "flows": [ + { + "type": "m.login.password" + }, + { + "type": "m.login.token", + "get_login_token": true + } + ] + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Session management post: @@ -92,13 +92,12 @@ paths: invalidate any access token previously associated with that device. See [Relationship between access tokens and devices](/client-server-api/#relationship-between-access-tokens-and-devices). operationId: login - parameters: - - in: body - name: body - required: true - schema: - type: object - example: { + requestBody: + content: + application/json: + schema: + type: object + example: { "type": "m.login.password", "identifier": { "type": "m.id.user", @@ -107,148 +106,182 @@ paths: "password": "ilovebananas", "initial_device_display_name": "Jungle Phone" } - properties: - type: - type: string - enum: ["m.login.password", "m.login.token"] - description: The login type being used. - identifier: - "$ref": "definitions/user_identifier.yaml" - user: - type: string - description: The fully qualified user ID or just local part of the user ID, to log in. Deprecated in favour of `identifier`. - medium: - type: string - description: When logging in using a third-party identifier, the medium of the identifier. Must be 'email'. Deprecated in favour of `identifier`. - address: - type: string - description: Third-party identifier for the user. Deprecated in favour of `identifier`. - password: - type: string - description: |- - Required when `type` is `m.login.password`. The user's - password. - token: - type: string - description: |- - Required when `type` is `m.login.token`. Part of Token-based login. - device_id: - type: string - description: |- - ID of the client device. If this does not correspond to a - known client device, a new device will be created. The given - device ID must not be the same as a - [cross-signing](/client-server-api/#cross-signing) key ID. - The server will auto-generate a device_id - if this is not specified. - initial_device_display_name: - type: string - description: |- - A display name to assign to the newly-created device. Ignored - if `device_id` corresponds to a known device. - refresh_token: - type: boolean - description: |- - If true, the client supports refresh tokens. - x-addedInMatrixVersion: "1.3" - required: ["type"] - + properties: + type: + type: string + enum: + - m.login.password + - m.login.token + description: The login type being used. + identifier: + $ref: definitions/user_identifier.yaml + user: + type: string + description: The fully qualified user ID or just local part of the user ID, to + log in. Deprecated in favour of `identifier`. + medium: + type: string + description: When logging in using a third-party identifier, the medium of the + identifier. Must be 'email'. Deprecated in favour of + `identifier`. + address: + type: string + description: Third-party identifier for the user. Deprecated in favour of + `identifier`. + password: + type: string + description: |- + Required when `type` is `m.login.password`. The user's + password. + token: + type: string + description: Required when `type` is `m.login.token`. Part of Token-based login. + device_id: + type: string + description: |- + ID of the client device. If this does not correspond to a + known client device, a new device will be created. The given + device ID must not be the same as a + [cross-signing](/client-server-api/#cross-signing) key ID. + The server will auto-generate a device_id + if this is not specified. + initial_device_display_name: + type: string + description: |- + A display name to assign to the newly-created device. Ignored + if `device_id` corresponds to a known device. + refresh_token: + type: boolean + description: If true, the client supports refresh tokens. + x-addedInMatrixVersion: "1.3" + required: + - type + required: true responses: - 200: + "200": description: The user has been authenticated. - examples: - application/json: { - "user_id": "@cheeky_monkey:matrix.org", - "access_token": "abc123", - "refresh_token": "def456", - "expires_in_ms": 60000, - "device_id": "GHTYAJCE", - "well_known": { - "m.homeserver": { - "base_url": "https://example.org" - }, - "m.identity_server": { - "base_url": "https://id.example.org" - } - } - } - schema: - type: object - properties: - user_id: - type: string - description: The fully-qualified Matrix ID for the account. - access_token: - type: string - description: |- - An access token for the account. - This access token can then be used to authorize other requests. - refresh_token: - type: string - description: |- - A refresh token for the account. This token can be used to - obtain a new access token when it expires by calling the - `/refresh` endpoint. - x-addedInMatrixVersion: "1.3" - expires_in_ms: - type: integer - description: |- - The lifetime of the access token, in milliseconds. Once - the access token has expired a new access token can be - obtained by using the provided refresh token. If no - refresh token is provided, the client will need to re-log in - to obtain a new access token. If not given, the client can - assume that the access token will not expire. - x-addedInMatrixVersion: "1.3" - home_server: - type: string - description: |- - The server_name of the homeserver on which the account has - been registered. + content: + application/json: + schema: + type: object + properties: + user_id: + type: string + description: The fully-qualified Matrix ID for the account. + access_token: + type: string + description: |- + An access token for the account. + This access token can then be used to authorize other requests. + refresh_token: + type: string + description: |- + A refresh token for the account. This token can be used to + obtain a new access token when it expires by calling the + `/refresh` endpoint. + x-addedInMatrixVersion: "1.3" + expires_in_ms: + type: integer + description: |- + The lifetime of the access token, in milliseconds. Once + the access token has expired a new access token can be + obtained by using the provided refresh token. If no + refresh token is provided, the client will need to re-log in + to obtain a new access token. If not given, the client can + assume that the access token will not expire. + x-addedInMatrixVersion: "1.3" + home_server: + type: string + description: |- + The server_name of the homeserver on which the account has + been registered. - **Deprecated**. Clients should extract the server_name from - `user_id` (by splitting at the first colon) if they require - it. Note also that `homeserver` is not spelt this way. - device_id: - type: string - description: |- - ID of the logged-in device. Will be the same as the - corresponding parameter in the request, if one was specified. - well_known: - description: |- - Optional client configuration provided by the server. If present, - clients SHOULD use the provided object to reconfigure themselves, - optionally validating the URLs within. This object takes the same - form as the one returned from .well-known autodiscovery. - allOf: - - "$ref": "definitions/wellknown/full.yaml" - required: ["access_token", "device_id", "user_id"] - 400: - description: |- - Part of the request was invalid. For example, the login type may not be recognised. - examples: - application/json: { - "errcode": "M_UNKNOWN", - "error": "Bad login type." - } - schema: - "$ref": "definitions/errors/error.yaml" - 403: + **Deprecated**. Clients should extract the server_name from + `user_id` (by splitting at the first colon) if they require + it. Note also that `homeserver` is not spelt this way. + device_id: + type: string + description: |- + ID of the logged-in device. Will be the same as the + corresponding parameter in the request, if one was specified. + well_known: + description: |- + Optional client configuration provided by the server. If present, + clients SHOULD use the provided object to reconfigure themselves, + optionally validating the URLs within. This object takes the same + form as the one returned from .well-known autodiscovery. + allOf: + - $ref: definitions/wellknown/full.yaml + required: + - access_token + - device_id + - user_id + examples: + response: + value: { + "user_id": "@cheeky_monkey:matrix.org", + "access_token": "abc123", + "refresh_token": "def456", + "expires_in_ms": 60000, + "device_id": "GHTYAJCE", + "well_known": { + "m.homeserver": { + "base_url": "https://example.org" + }, + "m.identity_server": { + "base_url": "https://id.example.org" + } + } + } + "400": + description: Part of the request was invalid. For example, the login type may + not be recognised. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_UNKNOWN", + "error": "Bad login type." + } + "403": description: |- The login attempt failed. This can include one of the following error codes: * `M_FORBIDDEN`: The provided authentication data was incorrect or the requested device ID is the same as a cross-signing key ID. * `M_USER_DEACTIVATED`: The user has been deactivated. - examples: - application/json: { - "errcode": "M_FORBIDDEN" - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN" + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Session management +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/login_token.yaml b/data/api/client-server/login_token.yaml index be0dca8b..73e607d1 100644 --- a/data/api/client-server/login_token.yaml +++ b/data/api/client-server/login_token.yaml @@ -11,25 +11,15 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server Registration and Login API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v1 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server Registration and Login API + version: 1.0.0 paths: - "/login/get_token": + /login/get_token: post: - summary: Optional endpoint to generate a single-use, time-limited, `m.login.token` token. + summary: Optional endpoint to generate a single-use, time-limited, + `m.login.token` token. description: |- Optional endpoint - the server is not required to implement this endpoint if it does not intend to use or support this functionality. @@ -64,55 +54,81 @@ paths: x-addedInMatrixVersion: "1.7" security: - accessToken: [] - parameters: - - in: body - name: body - required: true - schema: - type: object - properties: - auth: - description: |- - Additional authentication information for the user-interactive authentication API. - allOf: - - $ref: "definitions/auth_data.yaml" + requestBody: + content: + application/json: + schema: + type: object + properties: + auth: + description: Additional authentication information for the user-interactive + authentication API. + allOf: + - $ref: definitions/auth_data.yaml + required: true responses: - 200: - description: The login token an unauthenticated client can use to log in as the requesting user. - examples: - application/json: { - "login_token": "", - "expires_in_ms": 120000 - } - schema: - type: object - required: ["login_token", "expires_in_ms"] - properties: - login_token: - type: string - description: The login token for the `m.login.token` login flow. - expires_in_ms: - type: integer - description: |- - The time remaining in milliseconds until the homeserver will no longer accept the token. `120000` - (2 minutes) is recommended as a default. - 400: + "200": + description: The login token an unauthenticated client can use to log in as the + requesting user. + content: + application/json: + schema: + type: object + required: + - login_token + - expires_in_ms + properties: + login_token: + type: string + description: The login token for the `m.login.token` login flow. + expires_in_ms: + type: integer + description: |- + The time remaining in milliseconds until the homeserver will no longer accept the token. `120000` + (2 minutes) is recommended as a default. + examples: + response: + value: { + "login_token": "", + "expires_in_ms": 120000 + } + "400": description: |- The request was malformed, or the user does not have an ability to generate tokens for their devices, as implied by the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api). Clients should verify whether the user has an ability to call this endpoint with the `m.get_login_token` [capability](/client-server-api/#capabilities-negotiation). - schema: - "$ref": "definitions/errors/error.yaml" - 401: - description: |- - The homeserver requires additional authentication information. - schema: - "$ref": "definitions/auth_response.yaml" - 429: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + "401": + description: The homeserver requires additional authentication information. + content: + application/json: + schema: + $ref: definitions/auth_response.yaml + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Session management +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v1 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/logout.yaml b/data/api/client-server/logout.yaml index ad809de0..c3287472 100644 --- a/data/api/client-server/logout.yaml +++ b/data/api/client-server/logout.yaml @@ -11,23 +11,12 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server Registration and Login API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server Registration and Login API + version: 1.0.0 paths: - "/logout": + /logout: post: summary: Invalidates a user access token description: |- @@ -38,14 +27,16 @@ paths: security: - accessToken: [] responses: - 200: + "200": description: The access token used in the request was successfully invalidated. - schema: - type: object - properties: {} + content: + application/json: + schema: + type: object + properties: {} tags: - Session management - "/logout/all": + /logout/all: post: summary: Invalidates all access tokens for a user description: |- @@ -64,10 +55,27 @@ paths: security: - accessToken: [] responses: - 200: + "200": description: The user's access tokens were successfully invalidated. - schema: - type: object - properties: {} + content: + application/json: + schema: + type: object + properties: {} tags: - Session management +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/message_pagination.yaml b/data/api/client-server/message_pagination.yaml index cc4d72b4..940b9802 100644 --- a/data/api/client-server/message_pagination.yaml +++ b/data/api/client-server/message_pagination.yaml @@ -11,21 +11,10 @@ # 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. -swagger: "2.0" +openapi: 3.1.0 info: - title: "Matrix Client-Server Rooms API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server Rooms API + version: 1.0.0 paths: "/rooms/{roomId}/messages": get: @@ -41,16 +30,16 @@ paths: - accessToken: [] parameters: - in: path - type: string name: roomId description: The room to get events from. required: true - x-example: "!636q39766251:example.com" + example: "!636q39766251:example.com" + schema: + type: string - in: query - type: string name: from x-changedInMatrixVersion: - 1.3: | + "1.3": | Previously, this field was required and paginating from the first or last visible event in the room history wasn't supported. description: |- @@ -66,18 +55,19 @@ paths: from the first or last (per the value of the `dir` parameter) visible event in the room history for the requesting user. required: false - x-example: "s345_678_333" + example: s345_678_333 + schema: + type: string - in: query - type: string name: to description: |- The token to stop returning events at. This token can be obtained from a `prev_batch` or `next_batch` token returned by the `/sync` endpoint, or from an `end` token returned by a previous request to this endpoint. required: false + schema: + type: string - in: query - type: string - enum: ["b", "f"] name: dir description: |- The direction to return events from. If this is set to `f`, events @@ -85,92 +75,114 @@ paths: is set to `b`, events will be returned in *reverse* chronological order, again starting at `from`. required: true - x-example: "b" - - in: query - type: integer - name: limit - description: |- - The maximum number of events to return. Default: 10. - x-example: "3" - - in: query - type: string - name: filter - description: |- - A JSON RoomEventFilter to filter returned events with. - x-example: |- - {"contains_url":true} - responses: - 200: - description: A list of messages with a new token to request more. + example: b schema: - type: object - description: A list of messages with a new token to request more. - properties: - start: - type: string - description: |- - A token corresponding to the start of `chunk`. This will be the same as - the value given in `from`. - end: - type: string - description: |- - A token corresponding to the end of `chunk`. This token can be passed - back to this endpoint to request further events. - - If no further events are available (either because we have - reached the start of the timeline, or because the user does - not have permission to see any more events), this property - is omitted from the response. - chunk: - type: array - description: |- - A list of room events. The order depends on the `dir` parameter. - For `dir=b` events will be in reverse-chronological order, - for `dir=f` in chronological order. (The exact definition of `chronological` - is dependent on the server implementation.) - - Note that an empty `chunk` does not *necessarily* imply that no more events - are available. Clients should continue to paginate until no `end` property - is returned. - items: - "$ref": "definitions/client_event.yaml" - state: - type: array - description: |- - A list of state events relevant to showing the `chunk`. For example, if - `lazy_load_members` is enabled in the filter then this may contain - the membership events for the senders of events in the `chunk`. - - Unless `include_redundant_members` is `true`, the server - may remove membership events which would have already been - sent to the client in prior calls to this endpoint, assuming - the membership of those members has not changed. - items: - $ref: "definitions/client_event.yaml" - required: [start, chunk] - examples: + type: string + enum: + - b + - f + - in: query + name: limit + description: "The maximum number of events to return. Default: 10." + example: "3" + schema: + type: integer + - in: query + name: filter + description: A JSON RoomEventFilter to filter returned events with. + example: '{"contains_url":true}' + schema: + type: string + responses: + "200": + description: A list of messages with a new token to request more. + content: application/json: - { - "start": "t47429-4392820_219380_26003_2265", - "end": "t47409-4357353_219380_26003_2265", - "chunk": - [ - { - "room_id": "!636q39766251:example.com", - "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml", - }, - { - "room_id": "!636q39766251:example.com", - "$ref": "../../event-schemas/examples/m.room.name.yaml", - }, - { - "room_id": "!636q39766251:example.com", - "$ref": "../../event-schemas/examples/m.room.message$m.video.yaml", - }, - ], - } - 403: - description: > + schema: + type: object + description: A list of messages with a new token to request more. + properties: + start: + type: string + description: |- + A token corresponding to the start of `chunk`. This will be the same as + the value given in `from`. + end: + type: string + description: |- + A token corresponding to the end of `chunk`. This token can be passed + back to this endpoint to request further events. + + If no further events are available (either because we have + reached the start of the timeline, or because the user does + not have permission to see any more events), this property + is omitted from the response. + chunk: + type: array + description: |- + A list of room events. The order depends on the `dir` parameter. + For `dir=b` events will be in reverse-chronological order, + for `dir=f` in chronological order. (The exact definition of `chronological` + is dependent on the server implementation.) + + Note that an empty `chunk` does not *necessarily* imply that no more events + are available. Clients should continue to paginate until no `end` property + is returned. + items: + $ref: definitions/client_event.yaml + state: + type: array + description: |- + A list of state events relevant to showing the `chunk`. For example, if + `lazy_load_members` is enabled in the filter then this may contain + the membership events for the senders of events in the `chunk`. + + Unless `include_redundant_members` is `true`, the server + may remove membership events which would have already been + sent to the client in prior calls to this endpoint, assuming + the membership of those members has not changed. + items: + $ref: definitions/client_event.yaml + required: + - start + - chunk + examples: + response: + value: { + "start": "t47429-4392820_219380_26003_2265", + "end": "t47409-4357353_219380_26003_2265", + "chunk": [ + { + "room_id": "!636q39766251:example.com", + "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" + }, + { + "room_id": "!636q39766251:example.com", + "$ref": "../../event-schemas/examples/m.room.name.yaml" + }, + { + "room_id": "!636q39766251:example.com", + "$ref": "../../event-schemas/examples/m.room.message$m.video.yaml" + } + ] + } + "403": + description: | You aren't a member of the room. tags: - Room participation +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/notifications.yaml b/data/api/client-server/notifications.yaml index 8f8b62b4..1cde576b 100644 --- a/data/api/client-server/notifications.yaml +++ b/data/api/client-server/notifications.yaml @@ -11,24 +11,12 @@ # 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. - -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server Notifications API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server Notifications API + version: 1.0.0 paths: - "/notifications": + /notifications: get: summary: Gets a list of events that the user has been notified about description: |- @@ -39,97 +27,124 @@ paths: - accessToken: [] parameters: - in: query - type: string name: from description: |- Pagination token to continue from. This should be the `next_token` returned from an earlier call to this endpoint. required: false - x-example: "xxxxx" + example: xxxxx + schema: + type: string - in: query - type: integer name: limit description: Limit on the number of events to return in this request. required: false - x-example: 20 + example: 20 + schema: + type: integer - in: query name: only - type: string description: |- Allows basic filtering of events returned. Supply `highlight` to return only events where the notification had the highlight tweak set. required: false - x-example: "highlight" - responses: - 200: - description: A batch of events is being returned - examples: - application/json: { - "next_token": "abcdef", - "notifications": [ - { - "actions": [ - "notify" - ], - "profile_tag": "hcbvkzxhcvb", - "read": true, - "room_id": "!abcdefg:example.com", - "ts": 1475508881945, - "event": { - "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" - } - } - ] - } + example: highlight schema: - type: object - required: ["notifications"] - properties: - next_token: - type: string - description: |- - The token to supply in the `from` param of the next - `/notifications` request in order to request more - events. If this is absent, there are no more results. - notifications: - type: array - items: - type: object - required: ["actions", "event", "read", "room_id", "ts"] - title: Notification - properties: - actions: - type: array - description: |- - The action(s) to perform when the conditions for this rule are met. - See [Push Rules: API](/client-server-api/#push-rules-api). - items: - type: - - object - - string - event: - title: Event - description: The Event object for the event that triggered the notification. - allOf: - - "$ref": "definitions/client_event_without_room_id.yaml" - profile_tag: - type: string - description: The profile tag of the rule that matched this event. - read: - type: boolean - description: |- - Indicates whether the user has sent a read receipt indicating - that they have read this message. - room_id: - type: string - description: The ID of the room in which the event was posted. - ts: - type: integer - format: int64 - description: |- - The unix timestamp at which the event notification was sent, - in milliseconds. - description: The list of events that triggered notifications. + type: string + responses: + "200": + description: A batch of events is being returned + content: + application/json: + schema: + type: object + required: + - notifications + properties: + next_token: + type: string + description: |- + The token to supply in the `from` param of the next + `/notifications` request in order to request more + events. If this is absent, there are no more results. + notifications: + type: array + items: + type: object + required: + - actions + - event + - read + - room_id + - ts + title: Notification + properties: + actions: + type: array + description: |- + The action(s) to perform when the conditions for this rule are met. + See [Push Rules: API](/client-server-api/#push-rules-api). + items: + oneOf: + - type: object + - type: string + event: + title: Event + description: The Event object for the event that triggered the notification. + allOf: + - $ref: definitions/client_event_without_room_id.yaml + profile_tag: + type: string + description: The profile tag of the rule that matched this event. + read: + type: boolean + description: |- + Indicates whether the user has sent a read receipt indicating + that they have read this message. + room_id: + type: string + description: The ID of the room in which the event was posted. + ts: + type: integer + format: int64 + description: |- + The unix timestamp at which the event notification was sent, + in milliseconds. + description: The list of events that triggered notifications. + examples: + response: + value: { + "next_token": "abcdef", + "notifications": [ + { + "actions": [ + "notify" + ], + "profile_tag": "hcbvkzxhcvb", + "read": true, + "room_id": "!abcdefg:example.com", + "ts": 1475508881945, + "event": { + "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" + } + } + ] + } tags: - Push notifications +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/old_sync.yaml b/data/api/client-server/old_sync.yaml index 329289d8..3e0ad0b6 100644 --- a/data/api/client-server/old_sync.yaml +++ b/data/api/client-server/old_sync.yaml @@ -11,23 +11,12 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server Sync API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server Sync API + version: 1.0.0 paths: - "/events": + /events: get: summary: Listen on the event stream. description: |- @@ -43,54 +32,61 @@ paths: - accessToken: [] parameters: - in: query - type: string name: from description: |- The token to stream from. This token is either from a previous request to this API or from the initial sync API. required: false - x-example: "s3456_9_0" + example: s3456_9_0 + schema: + type: string - in: query - type: integer name: timeout description: The maximum time in milliseconds to wait for an event. required: false - x-example: "35000" - responses: - 200: - description: "The events received, which may be none." - examples: - application/json: { - "start": "s3456_9_0", - "end": "s3457_9_0", - "chunk": [ - {"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"} - ] - } + example: "35000" schema: - type: object - properties: - start: - type: string - description: |- - A token which correlates to the start of `chunk`. This - is usually the same token supplied to `from=`. - end: - type: string - description: |- - A token which correlates to the end of `chunk`. This - token should be used in the next request to `/events`. - chunk: - type: array - description: "An array of events." - items: - $ref: "definitions/client_event.yaml" - 400: - description: "Bad pagination `from` parameter." + type: integer + responses: + "200": + description: The events received, which may be none. + content: + application/json: + schema: + type: object + properties: + start: + type: string + description: |- + A token which correlates to the start of `chunk`. This + is usually the same token supplied to `from=`. + end: + type: string + description: |- + A token which correlates to the end of `chunk`. This + token should be used in the next request to `/events`. + chunk: + type: array + description: An array of events. + items: + $ref: definitions/client_event.yaml + examples: + response: + value: { + "start": "s3456_9_0", + "end": "s3457_9_0", + "chunk": [ + { + "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" + } + ] + } + "400": + description: Bad pagination `from` parameter. tags: - Room participation deprecated: true - "/initialSync": + /initialSync: get: summary: Get the user's current state. description: |- @@ -106,13 +102,13 @@ paths: - accessToken: [] parameters: - in: query - type: integer name: limit description: The maximum number of messages to return for each room. required: false - x-example: "2" + example: "2" + schema: + type: integer - in: query - type: boolean name: archived description: |- Whether to include rooms that the user has left. If `false` then @@ -120,176 +116,201 @@ paths: included. If set to `true` then rooms that the user has left are included as well. By default this is `false`. required: false - x-example: "true" - responses: - 200: - description: The user's current state. - examples: - application/json: { - "end": "s3456_9_0", - "presence": [ - {"$ref": "../../event-schemas/examples/m.presence.yaml"} - ], - "account_data": [ - { - "type": "org.example.custom.config", - "content": { - "custom_config_key": "custom_config_value" - } - } - ], - "rooms": [ - { - "membership": "join", - "messages": { - "chunk": [ - { - "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", - "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" - }, - { - "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", - "$ref": "../../event-schemas/examples/m.room.message$m.video.yaml" - } - ], - "end": "s3456_9_0", - "start": "t44-3453_9_0" - }, - "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", - "state": [ - { - "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", - "$ref": "../../event-schemas/examples/m.room.join_rules.yaml" - }, - { - "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", - "$ref": "../../event-schemas/examples/m.room.member.yaml" - }, - { - "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", - "$ref": "../../event-schemas/examples/m.room.create.yaml" - }, - { - "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", - "$ref": "../../event-schemas/examples/m.room.power_levels.yaml" - } - ], - "visibility": "private", - "account_data": [ - { - "type": "m.tag", - "content": {"tags": {"work": {"order": 1}}} - }, - { - "type": "org.example.custom.room.config", - "content": { - "custom_config_key": "custom_config_value" - } - } - ] - } - ] - } + example: "true" schema: - type: object - properties: - end: - type: string - description: |- - A token which correlates to the end of the timelines returned. This - token should be used with the `/events` endpoint to listen for new - events. - presence: - type: array - description: A list of presence events. - items: - $ref: "definitions/client_event.yaml" - rooms: - type: array - items: - type: object - title: RoomInfo - properties: - room_id: - type: string - description: "The ID of this room." - membership: - type: string - description: "The user's membership state in this room." - enum: ["invite", "join", "leave", "ban"] - invite: - type: object - title: "InviteEvent" - description: "The invite event if `membership` is `invite`" - allOf: - - $ref: "definitions/client_event.yaml" - messages: + type: boolean + responses: + "200": + description: The user's current state. + content: + application/json: + schema: + type: object + properties: + end: + type: string + description: |- + A token which correlates to the end of the timelines returned. This + token should be used with the `/events` endpoint to listen for new + events. + presence: + type: array + description: A list of presence events. + items: + $ref: definitions/client_event.yaml + rooms: + type: array + items: type: object - title: PaginationChunk - description: "The pagination chunk for this room." + title: RoomInfo properties: - start: + room_id: type: string - description: |- - A token which correlates to the start of `chunk`. - Can be passed to - [`/rooms//messages`](#get_matrixclientv3roomsroomidmessages) - to retrieve earlier events. + description: The ID of this room. + membership: + type: string + description: The user's membership state in this room. + enum: + - invite + - join + - leave + - ban + invite: + type: object + title: InviteEvent + description: The invite event if `membership` is `invite` + allOf: + - $ref: definitions/client_event.yaml + messages: + type: object + title: PaginationChunk + description: The pagination chunk for this room. + properties: + start: + type: string + description: |- + A token which correlates to the start of `chunk`. + Can be passed to + [`/rooms//messages`](#get_matrixclientv3roomsroomidmessages) + to retrieve earlier events. - If no earlier events are available, this property may be omitted from - the response. - end: - type: string - description: |- - A token which correlates to the end of `chunk`. - Can be passed to - [`/rooms//messages`](#get_matrixclientv3roomsroomidmessages) - to retrieve later events. - chunk: + If no earlier events are available, this property may be omitted from + the response. + end: + type: string + description: |- + A token which correlates to the end of `chunk`. + Can be passed to + [`/rooms//messages`](#get_matrixclientv3roomsroomidmessages) + to retrieve later events. + chunk: + type: array + description: |- + If the user is a member of the room this will be a + list of the most recent messages for this room. If + the user has left the room this will be the + messages that preceded them leaving. This array + will consist of at most `limit` elements. + items: + $ref: definitions/client_event.yaml + required: + - end + - chunk + state: type: array description: |- - If the user is a member of the room this will be a - list of the most recent messages for this room. If - the user has left the room this will be the - messages that preceded them leaving. This array - will consist of at most `limit` elements. + If the user is a member of the room this will be the + current state of the room as a list of events. If the + user has left the room this will be the state of the + room when they left it. items: - $ref: "definitions/client_event.yaml" - required: ["end", "chunk"] - state: - type: array - description: |- - If the user is a member of the room this will be the - current state of the room as a list of events. If the - user has left the room this will be the state of the - room when they left it. - items: - $ref: "definitions/client_event.yaml" - visibility: - type: string - enum: ["private", "public"] - description: |- - Whether this room is visible to the `/publicRooms` API - or not." - account_data: - type: array - description: |- - The private data that this user has attached to - this room. - items: - $ref: "definitions/client_event.yaml" - required: ["room_id", "membership"] - account_data: - type: array - description: |- - The global private data created by this user. - items: - title: Event - type: object - allOf: - - "$ref": "../../event-schemas/schema/core-event-schema/event.yaml" - required: ["end", "rooms", "presence"] - 404: + $ref: definitions/client_event.yaml + visibility: + type: string + enum: + - private + - public + description: |- + Whether this room is visible to the `/publicRooms` API + or not." + account_data: + type: array + description: |- + The private data that this user has attached to + this room. + items: + $ref: definitions/client_event.yaml + required: + - room_id + - membership + account_data: + type: array + description: The global private data created by this user. + items: + title: Event + type: object + allOf: + - $ref: ../../event-schemas/schema/core-event-schema/event.yaml + required: + - end + - rooms + - presence + examples: + response: + value: { + "end": "s3456_9_0", + "presence": [ + { + "$ref": "../../event-schemas/examples/m.presence.yaml" + } + ], + "account_data": [ + { + "type": "org.example.custom.config", + "content": { + "custom_config_key": "custom_config_value" + } + } + ], + "rooms": [ + { + "membership": "join", + "messages": { + "chunk": [ + { + "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", + "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" + }, + { + "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", + "$ref": "../../event-schemas/examples/m.room.message$m.video.yaml" + } + ], + "end": "s3456_9_0", + "start": "t44-3453_9_0" + }, + "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", + "state": [ + { + "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", + "$ref": "../../event-schemas/examples/m.room.join_rules.yaml" + }, + { + "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", + "$ref": "../../event-schemas/examples/m.room.member.yaml" + }, + { + "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", + "$ref": "../../event-schemas/examples/m.room.create.yaml" + }, + { + "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", + "$ref": "../../event-schemas/examples/m.room.power_levels.yaml" + } + ], + "visibility": "private", + "account_data": [ + { + "type": "m.tag", + "content": { + "tags": { + "work": { + "order": 1 + } + } + } + }, + { + "type": "org.example.custom.room.config", + "content": { + "custom_config_key": "custom_config_value" + } + } + ] + } + ] + } + "404": description: There is no avatar URL for this user or this user does not exist. tags: - Room participation @@ -310,20 +331,42 @@ paths: - accessToken: [] parameters: - in: path - type: string name: eventId description: The event ID to get. required: true - x-example: "$asfDuShaf7Gafaw:matrix.org" - responses: - 200: - description: The full event. - examples: - application/json: {"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"} + example: $asfDuShaf7Gafaw:matrix.org schema: - $ref: "definitions/client_event.yaml" - 404: - description: The event was not found or you do not have permission to read this event. + type: string + responses: + "200": + description: The full event. + content: + application/json: + schema: + $ref: definitions/client_event.yaml + examples: + response: + value: { + "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" + } + "404": + description: The event was not found or you do not have permission to read this + event. tags: - Room participation deprecated: true +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/openid.yaml b/data/api/client-server/openid.yaml index 28c28516..2dbd1227 100644 --- a/data/api/client-server/openid.yaml +++ b/data/api/client-server/openid.yaml @@ -11,21 +11,10 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server OpenID API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server OpenID API + version: 1.0.0 paths: "/user/{userId}/openid/request_token": post: @@ -44,40 +33,62 @@ paths: - accessToken: [] parameters: - in: path - type: string name: userId description: |- The user to request an OpenID token for. Should be the user who is authenticated for the request. required: true - x-example: "@alice:example.com" - - in: body - name: body - description: An empty object. Reserved for future expansion. - required: true + example: "@alice:example.com" schema: - type: object - example: {} + type: string + requestBody: + content: + application/json: + schema: + type: object + example: {} + description: An empty object. Reserved for future expansion. + required: true responses: - 200: + "200": description: |- OpenID token information. This response is nearly compatible with the response documented in the [OpenID Connect 1.0 Specification](http://openid.net/specs/openid-connect-core-1_0.html#TokenResponse) with the only difference being the lack of an `id_token`. Instead, the Matrix homeserver's name is provided. - examples: - application/json: { - "access_token": "SomeT0kenHere", - "token_type": "Bearer", - "matrix_server_name": "example.com", - "expires_in": 3600, - } - schema: - $ref: "definitions/openid_token.yaml" - 429: + content: + application/json: + schema: + $ref: definitions/openid_token.yaml + examples: + response: + value: { + "access_token": "SomeT0kenHere", + "token_type": "Bearer", + "matrix_server_name": "example.com", + "expires_in": 3600 + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - OpenID +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/peeking_events.yaml b/data/api/client-server/peeking_events.yaml index 4b8a6a96..19eb67a0 100644 --- a/data/api/client-server/peeking_events.yaml +++ b/data/api/client-server/peeking_events.yaml @@ -11,21 +11,10 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server Sync Guest API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server Sync Guest API + version: 1.0.0 paths: # With an extra " " to disambiguate from the getEvents endpoint # The extra space makes it sort first for what I'm sure is a good reason. @@ -48,62 +37,82 @@ paths: - accessToken: [] parameters: - in: query - type: string name: from description: |- The token to stream from. This token is either from a previous request to this API or from the initial sync API. required: false - x-example: "s3456_9_0" + example: s3456_9_0 + schema: + type: string - in: query - type: integer name: timeout description: The maximum time in milliseconds to wait for an event. required: false - x-example: "35000" - - in: query - type: string - name: room_id - description: |- - The room ID for which events should be returned. - x-example: - - "!somewhere:over.the.rainbow" - responses: - 200: - description: "The events received, which may be none." - examples: - application/json: { - "start": "s3456_9_0", - "end": "s3457_9_0", - "chunk": [ - { - "room_id": "!somewhere:over.the.rainbow", - "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" - } - ] - } + example: "35000" schema: - type: object - properties: - start: - type: string - description: |- - A token which correlates to the first value in `chunk`. This - is usually the same token supplied to `from=`. - end: - type: string - description: |- - A token which correlates to the last value in `chunk`. This - token should be used in the next request to `/events`. - chunk: - type: array - description: "An array of events." - items: - type: object - title: Event - allOf: - - "$ref": "definitions/client_event.yaml" - 400: - description: "Bad pagination `from` parameter." + type: integer + - in: query + name: room_id + description: The room ID for which events should be returned. + example: + - "!somewhere:over.the.rainbow" + schema: + type: string + responses: + "200": + description: The events received, which may be none. + content: + application/json: + schema: + type: object + properties: + start: + type: string + description: |- + A token which correlates to the first value in `chunk`. This + is usually the same token supplied to `from=`. + end: + type: string + description: |- + A token which correlates to the last value in `chunk`. This + token should be used in the next request to `/events`. + chunk: + type: array + description: An array of events. + items: + type: object + title: Event + allOf: + - $ref: definitions/client_event.yaml + examples: + response: + value: { + "start": "s3456_9_0", + "end": "s3457_9_0", + "chunk": [ + { + "room_id": "!somewhere:over.the.rainbow", + "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" + } + ] + } + "400": + description: Bad pagination `from` parameter. tags: - Room participation +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/presence.yaml b/data/api/client-server/presence.yaml index 6d144db2..caa19854 100644 --- a/data/api/client-server/presence.yaml +++ b/data/api/client-server/presence.yaml @@ -11,21 +11,10 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server Presence API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server Presence API + version: 1.0.0 paths: "/presence/{userId}/status": put: @@ -40,99 +29,136 @@ paths: - accessToken: [] parameters: - in: path - type: string name: userId description: The user whose presence state to update. required: true - x-example: "@alice:example.com" - - in: body - name: presenceState - description: The updated presence state. - required: true + example: "@alice:example.com" schema: - type: object - example: { + type: string + requestBody: + content: + application/json: + schema: + type: object + example: { "presence": "online", "status_msg": "I am here." } - properties: - presence: - type: string - enum: ["online", "offline", "unavailable"] - description: The new presence state. - status_msg: - type: string - description: The status message to attach to this state. - required: ["presence"] + properties: + presence: + type: string + enum: + - online + - offline + - unavailable + description: The new presence state. + status_msg: + type: string + description: The status message to attach to this state. + required: + - presence + description: The updated presence state. + required: true responses: - 200: + "200": description: The new presence state was set. - examples: - application/json: { - } - schema: - type: object # empty json object - 429: + content: + application/json: + schema: + type: object # empty json object + examples: + response: + value: {} + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Presence get: summary: Get this user's presence state. - description: |- - Get the given user's presence state. + description: Get the given user's presence state. operationId: getPresence security: - accessToken: [] parameters: - in: path - type: string name: userId description: The user whose presence state to get. required: true - x-example: "@alice:example.com" - responses: - 200: - description: The presence state for this user. - examples: - application/json: { - "presence": "unavailable", - "last_active_ago": 420845 - } + example: "@alice:example.com" schema: - type: object - properties: - presence: - type: string - enum: ["online", "offline", "unavailable"] - description: This user's presence. - last_active_ago: - type: integer - description: |- - The length of time in milliseconds since an action was performed - by this user. - status_msg: - type: [string, "null"] - description: The state message for this user if one was set. - currently_active: - type: boolean - description: "Whether the user is currently active" - required: ["presence"] - 404: + type: string + responses: + "200": + description: The presence state for this user. + content: + application/json: + schema: + type: object + properties: + presence: + type: string + enum: + - online + - offline + - unavailable + description: This user's presence. + last_active_ago: + type: integer + description: |- + The length of time in milliseconds since an action was performed + by this user. + status_msg: + description: The state message for this user if one was set. + type: ["string", "null"] + currently_active: + type: boolean + description: Whether the user is currently active + required: + - presence + examples: + response: + value: { + "presence": "unavailable", + "last_active_ago": 420845 + } + "403": + description: You are not allowed to see this user's presence status. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "You are not allowed to see their presence" + } + "404": description: |- There is no presence state for this user. This user may not exist or isn't exposing presence information to you. - schema: - "$ref": "definitions/errors/error.yaml" - 403: - description: You are not allowed to see this user's presence status. - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "You are not allowed to see their presence" - } - schema: - "$ref": "definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: definitions/errors/error.yaml tags: - Presence +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml index 9865e020..b47cf591 100644 --- a/data/api/client-server/profile.yaml +++ b/data/api/client-server/profile.yaml @@ -11,21 +11,10 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server Profile API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server Profile API + version: 1.0.0 paths: "/profile/{userId}/displayname": put: @@ -38,36 +27,42 @@ paths: - accessToken: [] parameters: - in: path - type: string name: userId description: The user whose display name to set. required: true - x-example: "@alice:example.com" - - in: body - name: displayName - description: The new display name information. - required: true + example: "@alice:example.com" schema: - type: object - example: { + type: string + requestBody: + content: + application/json: + schema: + type: object + example: { "displayname": "Alice Margatroid" } - properties: - displayname: - type: string - description: The new display name for this user. + properties: + displayname: + type: string + description: The new display name for this user. + description: The new display name information. + required: true responses: - 200: + "200": description: The display name was set. - examples: - application/json: { - } - schema: - type: object # empty json object - 429: + content: + application/json: + schema: + type: object # empty json object + examples: + response: + value: {} + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - User data get: @@ -79,25 +74,30 @@ paths: operationId: getDisplayName parameters: - in: path - type: string name: userId description: The user whose display name to get. required: true - x-example: "@alice:example.com" - responses: - 200: - description: The display name for this user. - examples: - application/json: { - "displayname": "Alice Margatroid" - } + example: "@alice:example.com" schema: - type: object - properties: - displayname: - type: string - description: The user's display name if they have set one, otherwise not present. - 404: + type: string + responses: + "200": + description: The display name for this user. + content: + application/json: + schema: + type: object + properties: + displayname: + type: string + description: The user's display name if they have set one, otherwise not + present. + examples: + response: + value: { + "displayname": "Alice Margatroid" + } + "404": description: There is no display name for this user or this user does not exist. tags: - User data @@ -112,37 +112,43 @@ paths: - accessToken: [] parameters: - in: path - type: string name: userId description: The user whose avatar URL to set. required: true - x-example: "@alice:example.com" - - in: body - name: avatar_url - description: The new avatar information. - required: true + example: "@alice:example.com" schema: - type: object - example: { + type: string + requestBody: + content: + application/json: + schema: + type: object + example: { "avatar_url": "mxc://matrix.org/wefh34uihSDRGhw34" } - properties: - avatar_url: - type: string - format: uri - description: The new avatar URL for this user. + properties: + avatar_url: + type: string + format: uri + description: The new avatar URL for this user. + description: The new avatar information. + required: true responses: - 200: + "200": description: The avatar URL was set. - examples: - application/json: { - } - schema: - type: object # empty json object - 429: + content: + application/json: + schema: + type: object # empty json object + examples: + response: + value: {} + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - User data get: @@ -154,26 +160,30 @@ paths: operationId: getAvatarUrl parameters: - in: path - type: string name: userId description: The user whose avatar URL to get. required: true - x-example: "@alice:example.com" - responses: - 200: - description: The avatar URL for this user. - examples: - application/json: { - "avatar_url": "mxc://matrix.org/SDGdghriugerRg" - } + example: "@alice:example.com" schema: - type: object - properties: - avatar_url: - type: string - format: uri - description: The user's avatar URL if they have set one, otherwise not present. - 404: + type: string + responses: + "200": + description: The avatar URL for this user. + content: + application/json: + schema: + type: object + properties: + avatar_url: + type: string + format: uri + description: The user's avatar URL if they have set one, otherwise not present. + examples: + response: + value: { + "avatar_url": "mxc://matrix.org/SDGdghriugerRg" + } + "404": description: There is no avatar URL for this user or this user does not exist. tags: - User data @@ -188,47 +198,75 @@ paths: operationId: getUserProfile parameters: - in: path - type: string name: userId description: The user whose profile information to get. required: true - x-example: "@alice:example.com" + example: "@alice:example.com" + schema: + type: string responses: - 200: + "200": description: The profile information for this user. - examples: - application/json: { - "avatar_url": "mxc://matrix.org/SDGdghriugerRg", - "displayname": "Alice Margatroid" - } - schema: - type: object - properties: - avatar_url: - type: string - format: uri - description: The user's avatar URL if they have set one, otherwise not present. - displayname: - type: string - description: The user's display name if they have set one, otherwise not present. - 403: + content: + application/json: + schema: + type: object + properties: + avatar_url: + type: string + format: uri + description: The user's avatar URL if they have set one, otherwise not present. + displayname: + type: string + description: The user's display name if they have set one, otherwise not + present. + examples: + response: + value: { + "avatar_url": "mxc://matrix.org/SDGdghriugerRg", + "displayname": "Alice Margatroid" + } + "403": x-addedInMatrixVersion: "1.2" - description: The server is unwilling to disclose whether the user exists and/or has profile information. - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "Profile lookup over federation is disabled on this homeserver" - } - schema: - "$ref": "definitions/errors/error.yaml" - 404: - description: There is no profile information for this user or this user does not exist. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Profile not found" - } - schema: - "$ref": "definitions/errors/error.yaml" + description: The server is unwilling to disclose whether the user exists and/or + has profile information. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "Profile lookup over federation is disabled on this homeserver" + } + "404": + description: There is no profile information for this user or this user does not + exist. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Profile not found" + } tags: - User data +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/pusher.yaml b/data/api/client-server/pusher.yaml index b797bb5a..c686e9ae 100644 --- a/data/api/client-server/pusher.yaml +++ b/data/api/client-server/pusher.yaml @@ -12,127 +12,117 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server Push API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server Push API + version: 1.0.0 paths: - "/pushers": + /pushers: get: summary: Gets the current pushers for the authenticated user - description: |- - Gets all currently active pushers for the authenticated user. + description: Gets all currently active pushers for the authenticated user. operationId: getPushers security: - accessToken: [] responses: - 200: + "200": description: The pushers for this user. - examples: - application/json: { - "pushers": [ - { - "pushkey": "Xp/MzCt8/9DcSNE9cuiaoT5Ac55job3TdLSSmtmYl4A=", - "kind": "http", - "app_id": "face.mcapp.appy.prod", - "app_display_name": "Appy McAppface", - "device_display_name": "Alice's Phone", - "profile_tag": "xyz", - "lang": "en-US", - "data": { - "url": "https://example.com/_matrix/push/v1/notify" - } - } - ] - } - schema: - type: object - properties: - pushers: - type: array - title: Pushers - description: |- - An array containing the current pushers for the user - items: - type: object - title: Pusher - properties: - pushkey: - type: string - description: |- - This is a unique identifier for this pusher. See `/set` for - more detail. - Max length, 512 bytes. - kind: - type: string - description: |- - The kind of pusher. `"http"` is a pusher that - sends HTTP pokes. - app_id: - type: string - description: |- - This is a reverse-DNS style identifier for the application. - Max length, 64 chars. - app_display_name: - type: string - description: |- - A string that will allow the user to identify what application - owns this pusher. - device_display_name: - type: string - description: |- - A string that will allow the user to identify what device owns - this pusher. - profile_tag: - type: string - description: |- - This string determines which set of device specific rules this - pusher executes. - lang: - type: string - description: |- - The preferred language for receiving notifications (e.g. 'en' - or 'en-US') - data: + content: + application/json: + schema: + type: object + properties: + pushers: + type: array + title: Pushers + description: An array containing the current pushers for the user + items: type: object - description: |- - A dictionary of information for the pusher implementation - itself. - title: PusherData + title: Pusher properties: - url: - type: string - format: uri - description: |- - Required if `kind` is `http`. The URL to use to send - notifications to. - format: + pushkey: type: string description: |- - The format to use when sending notifications to the Push - Gateway. - required: - - pushkey - - app_id - - kind - - app_display_name - - device_display_name - - lang - - data + This is a unique identifier for this pusher. See `/set` for + more detail. + Max length, 512 bytes. + kind: + type: string + description: |- + The kind of pusher. `"http"` is a pusher that + sends HTTP pokes. + app_id: + type: string + description: |- + This is a reverse-DNS style identifier for the application. + Max length, 64 chars. + app_display_name: + type: string + description: |- + A string that will allow the user to identify what application + owns this pusher. + device_display_name: + type: string + description: |- + A string that will allow the user to identify what device owns + this pusher. + profile_tag: + type: string + description: |- + This string determines which set of device specific rules this + pusher executes. + lang: + type: string + description: |- + The preferred language for receiving notifications (e.g. 'en' + or 'en-US') + data: + type: object + description: |- + A dictionary of information for the pusher implementation + itself. + title: PusherData + properties: + url: + type: string + format: uri + description: |- + Required if `kind` is `http`. The URL to use to send + notifications to. + format: + type: string + description: |- + The format to use when sending notifications to the Push + Gateway. + required: + - pushkey + - app_id + - kind + - app_display_name + - device_display_name + - lang + - data + examples: + response: + value: { + "pushers": [ + { + "pushkey": "Xp/MzCt8/9DcSNE9cuiaoT5Ac55job3TdLSSmtmYl4A=", + "kind": "http", + "app_id": "face.mcapp.appy.prod", + "app_display_name": "Appy McAppface", + "device_display_name": "Alice's Phone", + "profile_tag": "xyz", + "lang": "en-US", + "data": { + "url": "https://example.com/_matrix/push/v1/notify" + } + } + ] + } tags: - Push notifications - "/pushers/set": + /pushers/set: post: summary: Modify a pusher for this user on the homeserver. description: |- @@ -147,131 +137,155 @@ paths: operationId: postPusher security: - accessToken: [] - parameters: - - in: body - name: pusher - description: The pusher information. - required: true - schema: - type: object - example: { - "lang": "en", - "kind": "http", - "app_display_name": "Mat Rix", - "device_display_name": "iPhone 9", - "profile_tag": "xxyyzz", - "app_id": "com.example.app.ios", - "pushkey": "APA91bHPRgkF3JUikC4ENAHEeMrd41Zxv3hVZjC9KtT8OvPVGJ-hQMRKRrZuJAEcl7B338qju59zJMjw2DELjzEvxwYv7hH5Ynpc1ODQ0aT4U4OFEeco8ohsN5PjL1iC2dNtk2BAokeMCg2ZXKqpc8FXKmhX94kIxQ", - "data": { - "url": "https://push-gateway.location.here/_matrix/push/v1/notify", - "format": "event_id_only" - }, - "append": false - } - properties: - pushkey: - type: string - description: |- - This is a unique identifier for this pusher. The value you - should use for this is the routing or destination address - information for the notification, for example, the APNS token - for APNS or the Registration ID for GCM. If your notification - client has no such concept, use any unique identifier. - Max length, 512 bytes. + requestBody: + content: + application/json: + schema: + type: object + example: { + "lang": "en", + "kind": "http", + "app_display_name": "Mat Rix", + "device_display_name": "iPhone 9", + "profile_tag": "xxyyzz", + "app_id": "com.example.app.ios", + "pushkey": "APA91bHPRgkF3JUikC4ENAHEeMrd41Zxv3hVZjC9KtT8OvPVGJ-hQMRKRrZuJAEcl7B338qju59zJMjw2DELjzEvxwYv7hH5Ynpc1ODQ0aT4U4OFEeco8ohsN5PjL1iC2dNtk2BAokeMCg2ZXKqpc8FXKmhX94kIxQ", + "data": { + "url": "https://push-gateway.location.here/_matrix/push/v1/notify", + "format": "event_id_only" + }, + "append": false + } + properties: + pushkey: + type: string + description: |- + This is a unique identifier for this pusher. The value you + should use for this is the routing or destination address + information for the notification, for example, the APNS token + for APNS or the Registration ID for GCM. If your notification + client has no such concept, use any unique identifier. + Max length, 512 bytes. - If the `kind` is `"email"`, this is the email address to - send notifications to. - kind: - type: - - "string" - - "null" - description: |- - The kind of pusher to configure. `"http"` makes a pusher that - sends HTTP pokes. `"email"` makes a pusher that emails the - user with unread notifications. `null` deletes the pusher. - app_id: - type: string - description: |- - This is a reverse-DNS style identifier for the application. - It is recommended that this end with the platform, such that - different platform versions get different app identifiers. - Max length, 64 chars. + If the `kind` is `"email"`, this is the email address to + send notifications to. + kind: + description: |- + The kind of pusher to configure. `"http"` makes a pusher that + sends HTTP pokes. `"email"` makes a pusher that emails the + user with unread notifications. `null` deletes the pusher. + type: ["string", "null"] + app_id: + type: string + description: |- + This is a reverse-DNS style identifier for the application. + It is recommended that this end with the platform, such that + different platform versions get different app identifiers. + Max length, 64 chars. - If the `kind` is `"email"`, this is `"m.email"`. - app_display_name: - type: string - description: |- - Required if `kind` is not `null`. A string that will allow the - user to identify what application owns this pusher. - device_display_name: - type: string - description: |- - Required if `kind` is not `null`. A string that will allow the - user to identify what device owns this pusher. - profile_tag: - type: string - description: |- - This string determines which set of device specific rules this - pusher executes. - lang: - type: string - description: |- - Required if `kind` is not `null`. The preferred language for - receiving notifications (e.g. 'en' or 'en-US'). - data: - type: object - description: |- - Required if `kind` is not `null`. A dictionary of information - for the pusher implementation itself. If `kind` is `http`, - this should contain `url` which is the URL to use to send - notifications to. - title: PusherData - properties: - url: - type: string - format: uri - description: |- - Required if `kind` is `http`. The URL to use to send - notifications to. MUST be an HTTPS URL with a path of - `/_matrix/push/v1/notify`. - example: "https://push-gateway.location.here/_matrix/push/v1/notify" - format: - type: string - description: |- - The format to send notifications in to Push Gateways if the - `kind` is `http`. The details about what fields the - homeserver should send to the push gateway are defined in the - [Push Gateway Specification](/push-gateway-api/). Currently the only format - available is 'event_id_only'. - append: - type: boolean - description: |- - If true, the homeserver should add another pusher with the - given pushkey and App ID in addition to any others with - different user IDs. Otherwise, the homeserver must remove any - other pushers with the same App ID and pushkey for different - users. The default is `false`. - required: ['kind', 'app_id', 'pushkey'] + If the `kind` is `"email"`, this is `"m.email"`. + app_display_name: + type: string + description: |- + Required if `kind` is not `null`. A string that will allow the + user to identify what application owns this pusher. + device_display_name: + type: string + description: |- + Required if `kind` is not `null`. A string that will allow the + user to identify what device owns this pusher. + profile_tag: + type: string + description: |- + This string determines which set of device specific rules this + pusher executes. + lang: + type: string + description: |- + Required if `kind` is not `null`. The preferred language for + receiving notifications (e.g. 'en' or 'en-US'). + data: + type: object + description: |- + Required if `kind` is not `null`. A dictionary of information + for the pusher implementation itself. If `kind` is `http`, + this should contain `url` which is the URL to use to send + notifications to. + title: PusherData + properties: + url: + type: string + format: uri + description: |- + Required if `kind` is `http`. The URL to use to send + notifications to. MUST be an HTTPS URL with a path of + `/_matrix/push/v1/notify`. + example: https://push-gateway.location.here/_matrix/push/v1/notify + format: + type: string + description: |- + The format to send notifications in to Push Gateways if the + `kind` is `http`. The details about what fields the + homeserver should send to the push gateway are defined in the + [Push Gateway Specification](/push-gateway-api/). Currently the only format + available is 'event_id_only'. + append: + type: boolean + description: |- + If true, the homeserver should add another pusher with the + given pushkey and App ID in addition to any others with + different user IDs. Otherwise, the homeserver must remove any + other pushers with the same App ID and pushkey for different + users. The default is `false`. + required: + - kind + - app_id + - pushkey + description: The pusher information. + required: true responses: - 200: + "200": description: The pusher was set. - examples: - application/json: {} - schema: - type: object - description: An empty object. - 400: + content: + application/json: + schema: + type: object + description: An empty object. + examples: + response: + value: {} + "400": description: One or more of the pusher values were invalid. - examples: - application/json: { - "error": "Missing parameters: lang, data", - "errcode": "M_MISSING_PARAM" - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "error": "Missing parameters: lang, data", + "errcode": "M_MISSING_PARAM" + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Push notifications +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/pushrules.yaml b/data/api/client-server/pushrules.yaml index 817138d1..77a07afd 100644 --- a/data/api/client-server/pushrules.yaml +++ b/data/api/client-server/pushrules.yaml @@ -11,23 +11,12 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server Push Rules API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server Push Rules API + version: 1.0.0 paths: - "/pushrules/": + /pushrules/: get: summary: Retrieve all push rulesets. description: |- @@ -39,321 +28,344 @@ paths: security: - accessToken: [] responses: - 200: + "200": description: All the push rulesets for this user. - schema: - type: object - required: ["global"] - properties: - global: + content: + application/json: + schema: type: object - description: The global ruleset. - title: Ruleset - allOf: [ - "$ref": "definitions/push_ruleset.yaml" - ] - examples: - application/json: { - "global": { - "content": [ + required: + - global + properties: + global: + type: object + description: The global ruleset. + title: Ruleset + allOf: + - $ref: definitions/push_ruleset.yaml + examples: + response: + value: { + "global": { + "content": [ { - "actions": [ - "notify", - { - "set_tweak": "sound", - "value": "default" - }, - { - "set_tweak": "highlight" - } - ], - "default": true, - "enabled": true, - "pattern": "alice", - "rule_id": ".m.rule.contains_user_name" + "actions": [ + "notify", + { + "set_tweak": "sound", + "value": "default" + }, + { + "set_tweak": "highlight" + } + ], + "default": true, + "enabled": true, + "pattern": "alice", + "rule_id": ".m.rule.contains_user_name" } - ], - "override": [ + ], + "override": [ { - "actions": [], - "conditions": [], - "default": true, - "enabled": false, - "rule_id": ".m.rule.master" + "actions": [], + "conditions": [], + "default": true, + "enabled": false, + "rule_id": ".m.rule.master" }, { - "actions": [], - "conditions": [ - { - "key": "content.msgtype", - "kind": "event_match", - "pattern": "m.notice" - } - ], - "default": true, - "enabled": true, - "rule_id": ".m.rule.suppress_notices" + "actions": [], + "conditions": [ + { + "key": "content.msgtype", + "kind": "event_match", + "pattern": "m.notice" + } + ], + "default": true, + "enabled": true, + "rule_id": ".m.rule.suppress_notices" } - ], - "room": [], - "sender": [], - "underride": [ + ], + "room": [], + "sender": [], + "underride": [ { - "actions": [ - "notify", - { - "set_tweak": "sound", - "value": "ring" - }, - { - "set_tweak": "highlight", - "value": false - } - ], - "conditions": [ - { - "key": "type", - "kind": "event_match", - "pattern": "m.call.invite" - } - ], - "default": true, - "enabled": true, - "rule_id": ".m.rule.call" + "actions": [ + "notify", + { + "set_tweak": "sound", + "value": "ring" + }, + { + "set_tweak": "highlight", + "value": false + } + ], + "conditions": [ + { + "key": "type", + "kind": "event_match", + "pattern": "m.call.invite" + } + ], + "default": true, + "enabled": true, + "rule_id": ".m.rule.call" }, { - "actions": [ - "notify", - { - "set_tweak": "sound", - "value": "default" - }, - { - "set_tweak": "highlight" - } - ], - "conditions": [ - { - "kind": "contains_display_name" - } - ], - "default": true, - "enabled": true, - "rule_id": ".m.rule.contains_display_name" + "actions": [ + "notify", + { + "set_tweak": "sound", + "value": "default" + }, + { + "set_tweak": "highlight" + } + ], + "conditions": [ + { + "kind": "contains_display_name" + } + ], + "default": true, + "enabled": true, + "rule_id": ".m.rule.contains_display_name" }, { - "actions": [ - "notify", - { - "set_tweak": "sound", - "value": "default" - }, - { - "set_tweak": "highlight", - "value": false - } - ], - "conditions": [ - { - "kind": "room_member_count", - "is": "2" - }, - { - "kind": "event_match", - "key": "type", - "pattern": "m.room.message" - } - ], - "default": true, - "enabled": true, - "rule_id": ".m.rule.room_one_to_one" + "actions": [ + "notify", + { + "set_tweak": "sound", + "value": "default" + }, + { + "set_tweak": "highlight", + "value": false + } + ], + "conditions": [ + { + "kind": "room_member_count", + "is": "2" + }, + { + "kind": "event_match", + "key": "type", + "pattern": "m.room.message" + } + ], + "default": true, + "enabled": true, + "rule_id": ".m.rule.room_one_to_one" }, { - "actions": [ - "notify", - { - "set_tweak": "sound", - "value": "default" - }, - { - "set_tweak": "highlight", - "value": false - } - ], - "conditions": [ - { - "key": "type", - "kind": "event_match", - "pattern": "m.room.member" - }, - { - "key": "content.membership", - "kind": "event_match", - "pattern": "invite" - }, - { - "key": "state_key", - "kind": "event_match", - "pattern": "@alice:example.com" - } - ], - "default": true, - "enabled": true, - "rule_id": ".m.rule.invite_for_me" + "actions": [ + "notify", + { + "set_tweak": "sound", + "value": "default" + }, + { + "set_tweak": "highlight", + "value": false + } + ], + "conditions": [ + { + "key": "type", + "kind": "event_match", + "pattern": "m.room.member" + }, + { + "key": "content.membership", + "kind": "event_match", + "pattern": "invite" + }, + { + "key": "state_key", + "kind": "event_match", + "pattern": "@alice:example.com" + } + ], + "default": true, + "enabled": true, + "rule_id": ".m.rule.invite_for_me" }, { - "actions": [ - "notify", - { - "set_tweak": "highlight", - "value": false - } - ], - "conditions": [ - { - "key": "type", - "kind": "event_match", - "pattern": "m.room.member" - } - ], - "default": true, - "enabled": true, - "rule_id": ".m.rule.member_event" + "actions": [ + "notify", + { + "set_tweak": "highlight", + "value": false + } + ], + "conditions": [ + { + "key": "type", + "kind": "event_match", + "pattern": "m.room.member" + } + ], + "default": true, + "enabled": true, + "rule_id": ".m.rule.member_event" }, { - "actions": [ - "notify", - { - "set_tweak": "highlight", - "value": false - } - ], - "conditions": [ - { - "key": "type", - "kind": "event_match", - "pattern": "m.room.message" - } - ], - "default": true, - "enabled": true, - "rule_id": ".m.rule.message" + "actions": [ + "notify", + { + "set_tweak": "highlight", + "value": false + } + ], + "conditions": [ + { + "key": "type", + "kind": "event_match", + "pattern": "m.room.message" + } + ], + "default": true, + "enabled": true, + "rule_id": ".m.rule.message" } - ] - } - } + ] + } + } tags: - Push notifications "/pushrules/{scope}/{kind}/{ruleId}": get: summary: Retrieve a push rule. - description: |- - Retrieve a single specified push rule. + description: Retrieve a single specified push rule. operationId: getPushRule security: - accessToken: [] parameters: - in: path - type: string name: scope required: true - x-example: "global" - description: |- - `global` to specify global rules. + description: "`global` to specify global rules." + example: global + schema: + type: string - in: path - type: string name: kind required: true - x-example: content - enum: ["override", "underride", "sender", "room", "content"] description: | The kind of rule + example: content + schema: + type: string + enum: + - override + - underride + - sender + - room + - content - in: path - type: string name: ruleId required: true - x-example: "nocake" description: | The identifier for the rule. + example: nocake + schema: + type: string responses: - 200: + "200": description: |- The specific push rule. This will also include keys specific to the rule itself such as the rule's `actions` and `conditions` if set. - examples: - application/json: { - "actions": [], - "pattern": "cake*lie", - "rule_id": "nocake", - "enabled": true, - "default": false - } - schema: - type: object - description: The push rule. - allOf: [ - "$ref": "definitions/push_rule.yaml" - ] - 404: - description: |- - The push rule does not exist. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "The push rule was not found." - } - schema: - "$ref": "definitions/errors/error.yaml" + content: + application/json: + schema: + type: object + description: The push rule. + allOf: + - $ref: definitions/push_rule.yaml + examples: + response: + value: { + "actions": [], + "pattern": "cake*lie", + "rule_id": "nocake", + "enabled": true, + "default": false + } + "404": + description: The push rule does not exist. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "The push rule was not found." + } tags: - Push notifications delete: summary: Delete a push rule. - description: |- - This endpoint removes the push rule defined in the path. + description: This endpoint removes the push rule defined in the path. operationId: deletePushRule security: - accessToken: [] parameters: - in: path - type: string name: scope required: true - x-example: "global" - description: |- - `global` to specify global rules. + description: "`global` to specify global rules." + example: global + schema: + type: string - in: path - type: string name: kind required: true - x-example: content - enum: ["override", "underride", "sender", "room", "content"] description: | The kind of rule + example: content + schema: + type: string + enum: + - override + - underride + - sender + - room + - content - in: path - type: string name: ruleId required: true - x-example: "nocake" description: | The identifier for the rule. + example: nocake + schema: + type: string responses: - 200: + "200": description: The push rule was deleted. - examples: - application/json: { - } - schema: - type: object # empty json object - 404: - description: |- - The push rule does not exist. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "The push rule was not found." - } - schema: - "$ref": "definitions/errors/error.yaml" + content: + application/json: + schema: + type: object # empty json object + examples: + response: + value: {} + "404": + description: The push rule does not exist. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "The push rule was not found." + } tags: - Push notifications put: @@ -380,305 +392,369 @@ paths: - accessToken: [] parameters: - in: path - type: string name: scope required: true - x-example: "global" - description: |- - `global` to specify global rules. + description: "`global` to specify global rules." + example: global + schema: + type: string - in: path - type: string name: kind required: true - x-example: content - enum: ["override", "underride", "sender", "room", "content"] description: | The kind of rule + example: content + schema: + type: string + enum: + - override + - underride + - sender + - room + - content - in: path - type: string name: ruleId required: true - x-example: "nocake" description: | The identifier for the rule. If the string starts with a dot ("."), the request MUST be rejected as this is reserved for server-default rules. Slashes ("/") and backslashes ("\\") are also not allowed. + example: nocake + schema: + type: string - in: query - type: string name: before required: false - x-example: someRuleId description: |- Use 'before' with a `rule_id` as its value to make the new rule the next-most important rule with respect to the given user defined rule. It is not possible to add a rule relative to a predefined server rule. + example: someRuleId + schema: + type: string - in: query - type: string name: after required: false - x-example: anotherRuleId description: |- This makes the new rule the next-less important rule relative to the given user defined rule. It is not possible to add a rule relative to a predefined server rule. - - in: body - name: pushrule - description: |- - The push rule data. Additional top-level keys may be present depending - on the parameters for the rule `kind`. - required: true + example: anotherRuleId schema: - type: object - example: { + type: string + requestBody: + content: + application/json: + schema: + type: object + example: { "pattern": "cake*lie", - "actions": ["notify"] + "actions": [ + "notify" + ] } - properties: - actions: - type: array - description: |- - The action(s) to perform when the conditions for this rule are met. - items: - type: - - string - - object - conditions: - type: array - 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 applicable to `underride` and `override` rules. - items: - type: object - allOf: [ "$ref": "definitions/push_condition.yaml" ] - pattern: - type: string - description: |- - Only applicable to `content` rules. The glob-style pattern to match against. - required: ["actions"] + properties: + actions: + type: array + description: The action(s) to perform when the conditions for this rule are met. + items: + oneOf: + - type: string + - type: object + conditions: + type: array + 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 applicable to `underride` and `override` rules. + items: + type: object + allOf: + - $ref: definitions/push_condition.yaml + pattern: + type: string + description: Only applicable to `content` rules. The glob-style pattern to match + against. + required: + - actions + description: |- + The push rule data. Additional top-level keys may be present depending + on the parameters for the rule `kind`. + required: true responses: - 200: + "200": description: The push rule was created/updated. - examples: - application/json: { - } - schema: - type: object # empty json object - 400: + content: + application/json: + schema: + type: object # empty json object + examples: + response: + value: {} + "400": description: There was a problem configuring this push rule. - examples: - application/json: { - "error": "before/after rule not found: someRuleId", - "errcode": "M_UNKNOWN" - } - schema: - "$ref": "definitions/errors/error.yaml" - 404: - description: |- - The push rule does not exist (when updating a push rule). - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "The push rule was not found." - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "error": "before/after rule not found: someRuleId", + "errcode": "M_UNKNOWN" + } + "404": + description: The push rule does not exist (when updating a push rule). + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "The push rule was not found." + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Push notifications "/pushrules/{scope}/{kind}/{ruleId}/enabled": get: - summary: "Get whether a push rule is enabled" - description: - This endpoint gets whether the specified push rule is enabled. + summary: Get whether a push rule is enabled + description: This endpoint gets whether the specified push rule is enabled. operationId: isPushRuleEnabled security: - accessToken: [] parameters: - in: path - type: string name: scope required: true - x-example: "global" description: |- Either `global` or `device/` to specify global rules or device rules for the given `profile_tag`. + example: global + schema: + type: string - in: path - type: string name: kind required: true - x-example: cake - enum: ["override", "underride", "sender", "room", "content"] description: | The kind of rule + example: cake + schema: + type: string + enum: + - override + - underride + - sender + - room + - content - in: path - type: string name: ruleId required: true - x-example: nocake description: | The identifier for the rule. + example: nocake + schema: + type: string responses: - 200: + "200": description: Whether the push rule is enabled. - examples: - application/json: { - "enabled": true - } - schema: - type: object - properties: - enabled: - type: boolean - description: Whether the push rule is enabled or not. - required: ["enabled"] - 404: - description: |- - The push rule does not exist. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "The push rule was not found." - } - schema: - "$ref": "definitions/errors/error.yaml" + content: + application/json: + schema: + type: object + properties: + enabled: + type: boolean + description: Whether the push rule is enabled or not. + required: + - enabled + examples: + response: + value: { + "enabled": true + } + "404": + description: The push rule does not exist. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "The push rule was not found." + } tags: - Push notifications put: - summary: "Enable or disable a push rule." - description: |- - This endpoint allows clients to enable or disable the specified push rule. + summary: Enable or disable a push rule. + description: This endpoint allows clients to enable or disable the specified + push rule. operationId: setPushRuleEnabled security: - accessToken: [] parameters: - in: path - type: string name: scope required: true - x-example: "global" - description: |- - `global` to specify global rules. + description: "`global` to specify global rules." + example: global + schema: + type: string - in: path - type: string name: kind required: true - x-example: content - enum: ["override", "underride", "sender", "room", "content"] description: | The kind of rule + example: content + schema: + type: string + enum: + - override + - underride + - sender + - room + - content - in: path - type: string name: ruleId required: true - x-example: "nocake" description: | The identifier for the rule. - - in: body - name: body - description: | - Whether the push rule is enabled or not. - required: true + example: nocake schema: - type: object - properties: - enabled: - type: boolean - description: Whether the push rule is enabled or not. - required: ["enabled"] - example: { + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + enabled: + type: boolean + description: Whether the push rule is enabled or not. + required: + - enabled + example: { "enabled": true } + description: | + Whether the push rule is enabled or not. + required: true responses: - 200: + "200": description: The push rule was enabled or disabled. - examples: - application/json: { - } - schema: - type: object - 404: - description: |- - The push rule does not exist. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "The push rule was not found." - } - schema: - "$ref": "definitions/errors/error.yaml" + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "404": + description: The push rule does not exist. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "The push rule was not found." + } tags: - Push notifications "/pushrules/{scope}/{kind}/{ruleId}/actions": get: - summary: "The actions for a push rule" - description: - This endpoint get the actions for the specified push rule. + summary: The actions for a push rule + description: This endpoint get the actions for the specified push rule. operationId: getPushRuleActions security: - accessToken: [] parameters: - in: path - type: string name: scope required: true - x-example: "global" description: |- Either `global` or `device/` to specify global rules or device rules for the given `profile_tag`. + example: global + schema: + type: string - in: path - type: string name: kind required: true - x-example: content - enum: ["override", "underride", "sender", "room", "content"] description: | The kind of rule + example: content + schema: + type: string + enum: + - override + - underride + - sender + - room + - content - in: path - type: string name: ruleId required: true - x-example: nocake description: | The identifier for the rule. + example: nocake + schema: + type: string responses: - 200: + "200": description: The actions for this push rule. - examples: - application/json: { - "actions": [ - "notify", - {"set_tweak": "sound", "value": "bing"} - ] - } - schema: - type: object - properties: - actions: - type: array - description: The action(s) to perform for this rule. - items: - type: - - string - - object - required: ["actions"] - 404: - description: |- - The push rule does not exist. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "The push rule was not found." - } - schema: - "$ref": "definitions/errors/error.yaml" + content: + application/json: + schema: + type: object + properties: + actions: + type: array + description: The action(s) to perform for this rule. + items: + oneOf: + - type: string + - type: object + required: + - actions + examples: + response: + value: { + "actions": [ + "notify", + { + "set_tweak": "sound", + "value": "bing" + } + ] + } + "404": + description: The push rule does not exist. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "The push rule was not found." + } tags: - Push notifications put: - summary: "Set the actions for a push rule." + summary: Set the actions for a push rule. description: |- This endpoint allows clients to change the actions of a push rule. This can be used to change the actions of builtin rules. @@ -687,66 +763,96 @@ paths: - accessToken: [] parameters: - in: path - type: string name: scope required: true - x-example: "global" - description: |- - `global` to specify global rules. + description: "`global` to specify global rules." + example: global + schema: + type: string - in: path - type: string name: kind required: true - x-example: room - enum: ["override", "underride", "sender", "room", "content"] description: | The kind of rule + example: room + schema: + type: string + enum: + - override + - underride + - sender + - room + - content - in: path - type: string name: ruleId required: true - x-example: "#spam:example.com" description: | The identifier for the rule. - - in: body - name: body - description: | - The action(s) to perform when the conditions for this rule are met. - required: true + example: "#spam:example.com" schema: - type: object - properties: - actions: - type: array - description: The action(s) to perform for this rule. - items: - type: - - string - - object - required: ["actions"] - example: { + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + actions: + type: array + description: The action(s) to perform for this rule. + items: + oneOf: + - type: string + - type: object + required: + - actions + example: { "actions": [ "notify", - {"set_tweak": "highlight"} + { + "set_tweak": "highlight" + } ] } + description: | + The action(s) to perform when the conditions for this rule are met. + required: true responses: - 200: + "200": description: The actions for the push rule were set. - examples: - application/json: { - } - schema: - type: object - 404: - description: |- - The push rule does not exist. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "The push rule was not found." - } - schema: - "$ref": "definitions/errors/error.yaml" + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "404": + description: The push rule does not exist. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "The push rule was not found." + } tags: - Push notifications +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/read_markers.yaml b/data/api/client-server/read_markers.yaml index d5993f67..5372df34 100644 --- a/data/api/client-server/read_markers.yaml +++ b/data/api/client-server/read_markers.yaml @@ -12,21 +12,10 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server Read Marker API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server Read Marker API + version: 1.0.0 paths: "/rooms/{roomId}/read_markers": post: @@ -39,52 +28,72 @@ paths: - accessToken: [] parameters: - in: path - type: string name: roomId description: The room ID to set the read marker in for the user. required: true - x-example: "!somewhere:example.org" - - in: body - name: body - description: The read marker and optional read receipt locations. - required: true + example: "!somewhere:example.org" schema: - type: object - properties: - "m.fully_read": - type: string - description: |- - The event ID the read marker should be located at. The - event MUST belong to the room. - example: "$somewhere:example.org" - x-changedInMatrixVersion: - 1.4: | - This property is no longer required. - "m.read": - type: string - description: |- - The event ID to set the read receipt location at. This is - equivalent to calling `/receipt/m.read/$elsewhere:example.org` - and is provided here to save that extra call. - example: "$elsewhere:example.org" - "m.read.private": - x-addedInMatrixVersion: "1.4" - type: string - description: |- - The event ID to set the *private* read receipt location at. This - equivalent to calling `/receipt/m.read.private/$elsewhere:example.org` - and is provided here to save that extra call. - example: "$elsewhere:example.org" + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + m.fully_read: + type: string + description: |- + The event ID the read marker should be located at. The + event MUST belong to the room. + example: $somewhere:example.org + x-changedInMatrixVersion: + "1.4": | + This property is no longer required. + m.read: + type: string + description: |- + The event ID to set the read receipt location at. This is + equivalent to calling `/receipt/m.read/$elsewhere:example.org` + and is provided here to save that extra call. + example: $elsewhere:example.org + m.read.private: + x-addedInMatrixVersion: "1.4" + type: string + description: |- + The event ID to set the *private* read receipt location at. This + equivalent to calling `/receipt/m.read.private/$elsewhere:example.org` + and is provided here to save that extra call. + example: $elsewhere:example.org + description: The read marker and optional read receipt locations. + required: true responses: - 200: - description: |- - The read marker, and read receipt(s) if provided, have been updated. - schema: - type: object - properties: {} - 429: + "200": + description: The read marker, and read receipt(s) if provided, have been updated. + content: + application/json: + schema: + type: object + properties: {} + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Read Markers +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/receipts.yaml b/data/api/client-server/receipts.yaml index 0b8d4593..abbd7a62 100644 --- a/data/api/client-server/receipts.yaml +++ b/data/api/client-server/receipts.yaml @@ -12,21 +12,10 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server Receipts API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server Receipts API + version: 1.0.0 paths: "/rooms/{roomId}/receipt/{receiptType}/{eventId}": post: @@ -39,13 +28,13 @@ paths: - accessToken: [] parameters: - in: path - type: string name: roomId description: The room in which to send the event. required: true - x-example: "!wefuh21ffskfuh345:example.com" + example: "!wefuh21ffskfuh345:example.com" + schema: + type: string - in: path - type: string name: receiptType description: |- The type of receipt to send. This can also be `m.fully_read` as an @@ -55,63 +44,92 @@ paths: effectively calls `/read_markers` internally when presented with a receipt type of `m.fully_read`. required: true - x-example: "m.read" x-changedInMatrixVersion: - 1.4: | + "1.4": | Allow `m.read.private` receipts and `m.fully_read` markers to be set. - enum: ["m.read", "m.read.private", "m.fully_read"] + example: m.read + schema: + type: string + enum: + - m.read + - m.read.private + - m.fully_read - in: path - type: string name: eventId description: The event ID to acknowledge up to. required: true - x-example: "$1924376522eioj:example.com" - - in: body - name: receipt - description: |- - Extra receipt information to attach to `content` if any. The - server will automatically set the `ts` field. - required: true + example: $1924376522eioj:example.com schema: - type: object - properties: - thread_id: - type: string - x-addedInMatrixVersion: "1.4" - description: |- + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + 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: { - "thread_id": "main" - } - responses: - 200: - description: The receipt was sent. - examples: - application/json: { + example: { + "thread_id": "main" } - schema: - type: object - maxProperties: 0 # empty json object - 429: - description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" - 400: + description: |- + Extra receipt information to attach to `content` if any. The + server will automatically set the `ts` field. + required: true + responses: + "200": + description: The receipt was sent. + content: + application/json: + schema: + type: object + maxProperties: 0 # empty json object + examples: + response: + value: {} + "400": description: |- The `thread_id` is invalid in some way. For example: * It is not a string. * It is empty. * It is provided for an incompatible receipt type. * The `event_id` is not related to the `thread_id`. - schema: - $ref: "definitions/errors/error.yaml" - examples: - application/json: { - "errcode": "M_INVALID_PARAM", - "error": "thread_id field must be a non-empty string" - } + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_INVALID_PARAM", + "error": "thread_id field must be a non-empty string" + } + "429": + description: This request was rate-limited. + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Room participation +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/redaction.yaml b/data/api/client-server/redaction.yaml index 8fa9cbef..aca69fa6 100644 --- a/data/api/client-server/redaction.yaml +++ b/data/api/client-server/redaction.yaml @@ -11,21 +11,10 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server message redaction API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server message redaction API + version: 1.0.0 paths: "/rooms/{roomId}/redact/{eventId}/{txnId}": put: @@ -47,50 +36,71 @@ paths: - accessToken: [] parameters: - in: path - type: string name: roomId description: The room from which to redact the event. required: true - x-example: "!637q39766251:example.com" + example: "!637q39766251:example.com" + schema: + type: string - in: path - type: string name: eventId description: The ID of the event to redact required: true - x-example: "bai2b1i9:matrix.org" + example: bai2b1i9:matrix.org + schema: + type: string - in: path name: txnId - type: string description: |- The [transaction ID](/client-server-api/#transaction-identifiers) for this event. Clients should generate a unique ID; it will be used by the server to ensure idempotency of requests. required: true - x-example: "37" - - in: body - name: body - required: true + example: "37" schema: - type: object - example: { + type: string + requestBody: + content: + application/json: + schema: + type: object + example: { "reason": "Indecent material" } - properties: - reason: - type: string - description: The reason for the event being redacted. + properties: + reason: + type: string + description: The reason for the event being redacted. + required: true responses: - 200: - description: "An ID for the redaction event." - examples: - application/json: { - "event_id": "$YUwQidLecu:example.com" - } - schema: - type: object - properties: - event_id: - type: string - description: |- - A unique identifier for the event. + "200": + description: An ID for the redaction event. + content: + application/json: + schema: + type: object + properties: + event_id: + type: string + description: A unique identifier for the event. + examples: + response: + value: { + "event_id": "$YUwQidLecu:example.com" + } tags: - Room participation +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/refresh.yaml b/data/api/client-server/refresh.yaml index 5923d3b7..f40bd516 100644 --- a/data/api/client-server/refresh.yaml +++ b/data/api/client-server/refresh.yaml @@ -11,21 +11,12 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server Registration and Login API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 -consumes: - - application/json -produces: - - application/json + title: Matrix Client-Server Registration and Login API + version: 1.0.0 paths: - "/refresh": + /refresh: post: x-addedInMatrixVersion: "1.3" summary: Refresh an access token @@ -48,63 +39,81 @@ paths: Application Service identity assertion is disabled for this endpoint. operationId: refresh - parameters: - - in: body - name: body - required: true - schema: - type: object - example: { + requestBody: + content: + application/json: + schema: + type: object + example: { "refresh_token": "some_token" } - properties: - refresh_token: - type: string - description: The refresh token - required: - - refresh_token + properties: + refresh_token: + type: string + description: The refresh token + required: + - refresh_token + required: true responses: - 200: + "200": description: A new access token and refresh token were generated. - examples: - application/json: { - "access_token": "a_new_token", - "expires_in_ms": 60000, - "refresh_token": "another_new_token" - } - schema: - type: object - properties: - access_token: - type: string - description: |- - The new access token to use. - refresh_token: - type: string - description: |- - The new refresh token to use when the access token needs to - be refreshed again. If not given, the old refresh token can - be re-used. - expires_in_ms: - type: integer - description: |- - The lifetime of the access token, in milliseconds. If not - given, the client can assume that the access token will not - expire. - required: - - access_token - 401: - description: |- - The provided token was unknown, or has already been used. - examples: - application/json: { - "errcode": "M_UNKNOWN_TOKEN", - "error": "Soft logged out", - "soft_logout": true - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + type: object + properties: + access_token: + type: string + description: The new access token to use. + refresh_token: + type: string + description: |- + The new refresh token to use when the access token needs to + be refreshed again. If not given, the old refresh token can + be re-used. + expires_in_ms: + type: integer + description: |- + The lifetime of the access token, in milliseconds. If not + given, the client can assume that the access token will not + expire. + required: + - access_token + examples: + response: + value: { + "access_token": "a_new_token", + "expires_in_ms": 60000, + "refresh_token": "another_new_token" + } + "401": + description: The provided token was unknown, or has already been used. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_UNKNOWN_TOKEN", + "error": "Soft logged out", + "soft_logout": true + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 diff --git a/data/api/client-server/registration.yaml b/data/api/client-server/registration.yaml index 29bd4196..1f823ac8 100644 --- a/data/api/client-server/registration.yaml +++ b/data/api/client-server/registration.yaml @@ -12,21 +12,12 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server Registration API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 -consumes: - - application/json -produces: - - application/json + title: Matrix Client-Server Registration API + version: 1.0.0 paths: - "/register": + /register: post: summary: Register for an account on this homeserver. description: |- @@ -73,129 +64,134 @@ paths: parameters: - in: query name: kind - type: string + required: false + description: The kind of account to register. Defaults to `user`. # swagger-UI overrides the default with the example, so better make the # example the default. - x-example: user - required: false - default: user - enum: - - guest - - user - description: The kind of account to register. Defaults to `user`. - - in: body - name: body - required: true + example: user schema: - type: object - properties: - auth: - description: |- + type: string + enum: + - guest + - user + default: user + requestBody: + content: + application/json: + schema: + type: object + properties: + auth: + description: |- Additional authentication information for the user-interactive authentication API. Note that this information is *not* used to define how the registered user should be authenticated, but is instead used to authenticate the `register` call itself. - allOf: - - "$ref": "definitions/auth_data.yaml" - username: - type: string - description: |- - The basis for the localpart of the desired Matrix ID. If omitted, - the homeserver MUST generate a Matrix ID local part. - example: cheeky_monkey - password: - type: string - description: The desired password for the account. - example: ilovebananas - device_id: - type: string - description: |- - ID of the client device. If this does not correspond to a - known client device, a new device will be created. The server - will auto-generate a device_id if this is not specified. - example: GHTYAJCE - initial_device_display_name: - type: string - description: |- - A display name to assign to the newly-created device. Ignored - if `device_id` corresponds to a known device. - example: Jungle Phone - inhibit_login: - type: boolean - description: |- - If true, an `access_token` and `device_id` should not be - returned from this call, therefore preventing an automatic - login. Defaults to false. - example: false - refresh_token: - type: boolean - description: |- - If true, the client supports refresh tokens. - x-addedInMatrixVersion: "1.3" + allOf: + - $ref: definitions/auth_data.yaml + username: + type: string + description: |- + The basis for the localpart of the desired Matrix ID. If omitted, + the homeserver MUST generate a Matrix ID local part. + example: cheeky_monkey + password: + type: string + description: The desired password for the account. + example: ilovebananas + device_id: + type: string + description: |- + ID of the client device. If this does not correspond to a + known client device, a new device will be created. The server + will auto-generate a device_id if this is not specified. + example: GHTYAJCE + initial_device_display_name: + type: string + description: |- + A display name to assign to the newly-created device. Ignored + if `device_id` corresponds to a known device. + example: Jungle Phone + inhibit_login: + type: boolean + description: |- + If true, an `access_token` and `device_id` should not be + returned from this call, therefore preventing an automatic + login. Defaults to false. + example: false + refresh_token: + type: boolean + description: If true, the client supports refresh tokens. + x-addedInMatrixVersion: "1.3" + required: true responses: - 200: + "200": description: The account has been registered. - examples: - application/json: { - "user_id": "@cheeky_monkey:matrix.org", - "access_token": "abc123", - "device_id": "GHTYAJCE" - } - schema: - type: object - properties: - user_id: - type: string - description: |- - The fully-qualified Matrix user ID (MXID) that has been registered. + content: + application/json: + schema: + type: object + properties: + user_id: + type: string + description: |- + The fully-qualified Matrix user ID (MXID) that has been registered. - Any user ID returned by this API must conform to the grammar given in the - [Matrix specification](/appendices/#user-identifiers). - access_token: - type: string - description: |- - An access token for the account. - This access token can then be used to authorize other requests. - Required if the `inhibit_login` option is false. - refresh_token: - type: string - description: |- - A refresh token for the account. This token can be used to - obtain a new access token when it expires by calling the - `/refresh` endpoint. + Any user ID returned by this API must conform to the grammar given in the + [Matrix specification](/appendices/#user-identifiers). + access_token: + type: string + description: |- + An access token for the account. + This access token can then be used to authorize other requests. + Required if the `inhibit_login` option is false. + refresh_token: + type: string + description: |- + A refresh token for the account. This token can be used to + obtain a new access token when it expires by calling the + `/refresh` endpoint. - Omitted if the `inhibit_login` option is true. - x-addedInMatrixVersion: "1.3" - expires_in_ms: - type: integer - description: |- - The lifetime of the access token, in milliseconds. Once - the access token has expired a new access token can be - obtained by using the provided refresh token. If no - refresh token is provided, the client will need to re-log in - to obtain a new access token. If not given, the client can - assume that the access token will not expire. + Omitted if the `inhibit_login` option is true. + x-addedInMatrixVersion: "1.3" + expires_in_ms: + type: integer + description: |- + The lifetime of the access token, in milliseconds. Once + the access token has expired a new access token can be + obtained by using the provided refresh token. If no + refresh token is provided, the client will need to re-log in + to obtain a new access token. If not given, the client can + assume that the access token will not expire. - Omitted if the `inhibit_login` option is true. - x-addedInMatrixVersion: "1.3" - home_server: - type: string - description: |- - The server_name of the homeserver on which the account has - been registered. + Omitted if the `inhibit_login` option is true. + x-addedInMatrixVersion: "1.3" + home_server: + type: string + description: |- + The server_name of the homeserver on which the account has + been registered. - **Deprecated**. Clients should extract the server_name from - `user_id` (by splitting at the first colon) if they require - it. Note also that `homeserver` is not spelt this way. - device_id: - type: string - description: |- - ID of the registered device. Will be the same as the - corresponding parameter in the request, if one was specified. - Required if the `inhibit_login` option is false. - required: ['user_id'] - 400: + **Deprecated**. Clients should extract the server_name from + `user_id` (by splitting at the first colon) if they require + it. Note also that `homeserver` is not spelt this way. + device_id: + type: string + description: |- + ID of the registered device. Will be the same as the + corresponding parameter in the request, if one was specified. + Required if the `inhibit_login` option is false. + required: + - user_id + examples: + response: + value: { + "user_id": "@cheeky_monkey:matrix.org", + "access_token": "abc123", + "device_id": "GHTYAJCE" + } + "400": description: |- Part of the request was invalid. This may include one of the following error codes: @@ -212,69 +208,72 @@ paths: performing User-Interactive Authentication, although they may also return them after authentication is completed if, for example, the requested user ID was registered whilst the client was performing authentication. - examples: - application/json: { - "errcode": "M_USER_IN_USE", - "error": "Desired user ID is already taken." - } - schema: - "$ref": "definitions/errors/error.yaml" - 401: - description: |- - The homeserver requires additional authentication information. - schema: - "$ref": "definitions/auth_response.yaml" - 403: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_USER_IN_USE", + "error": "Desired user ID is already taken." + } + "401": + description: The homeserver requires additional authentication information. + content: + application/json: + schema: + $ref: definitions/auth_response.yaml + "403": description: |- The homeserver does not permit registering the account. This response can be used to identify that a particular `kind` of account is not allowed, or that registration is generally not supported by the homeserver. - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "Registration is disabled" - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "Registration is disabled" + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Account management - "/register/email/requestToken": + /register/email/requestToken: post: - summary: Begins the validation process for an email to be used during registration. + summary: Begins the validation process for an email to be used during + registration. description: |- The homeserver must check that the given email address is **not** already associated with an account on this homeserver. The homeserver should validate the email itself, either by sending a validation email itself or by using a service it has control over. operationId: requestTokenToRegisterEmail - parameters: - - in: body - name: body - required: true - schema: - $ref: "definitions/request_email_validation.yaml" + requestBody: + content: + application/json: + schema: + $ref: definitions/request_email_validation.yaml + required: true responses: - 200: + "200": description: |- An email has been sent to the specified address. Note that this may be an email containing the validation token or it may be informing the user of an error. - schema: - $ref: "definitions/request_token_response.yaml" - 403: - description: The homeserver does not permit the address to be bound. - schema: - $ref: "definitions/errors/error.yaml" - examples: - application/json: { - "errcode": "M_THREEPID_DENIED", - "error": "Third-party identifier is not allowed" - } - 400: + content: + application/json: + schema: + $ref: definitions/request_token_response.yaml + "400": description: |- Part of the request was invalid. This may include one of the following error codes: @@ -285,48 +284,57 @@ paths: has an account on the homeserver in question. * `M_SERVER_NOT_TRUSTED` : The `id_server` parameter refers to an identity server that is not trusted by this homeserver. - examples: - application/json: { - "errcode": "M_THREEPID_IN_USE", - "error": "The specified address is already in use" - } - schema: - "$ref": "definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_THREEPID_IN_USE", + "error": "The specified address is already in use" + } + "403": + description: The homeserver does not permit the address to be bound. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_THREEPID_DENIED", + "error": "Third-party identifier is not allowed" + } tags: - Account management - "/register/msisdn/requestToken": + /register/msisdn/requestToken: post: - summary: Requests a validation token be sent to the given phone number for the purpose of registering an account + summary: Requests a validation token be sent to the given phone number for the + purpose of registering an account description: |- The homeserver must check that the given phone number is **not** already associated with an account on this homeserver. The homeserver should validate the phone number itself, either by sending a validation message itself or by using a service it has control over. operationId: requestTokenToRegisterMSISDN - parameters: - - in: body - name: body - required: true - schema: - $ref: "definitions/request_msisdn_validation.yaml" + requestBody: + content: + application/json: + schema: + $ref: definitions/request_msisdn_validation.yaml + required: true responses: - 200: + "200": description: |- An SMS message has been sent to the specified phone number. Note that this may be an SMS message containing the validation token or it may be informing the user of an error. - schema: - $ref: "definitions/request_token_response.yaml" - 403: - description: The homeserver does not permit the address to be bound. - schema: - $ref: "definitions/errors/error.yaml" - examples: - application/json: { - "errcode": "M_THREEPID_DENIED", - "error": "Third-party identifier is not allowed" - } - 400: + content: + application/json: + schema: + $ref: definitions/request_token_response.yaml + "400": description: |- Part of the request was invalid. This may include one of the following error codes: @@ -337,18 +345,33 @@ paths: has an account on the homeserver in question. * `M_SERVER_NOT_TRUSTED` : The `id_server` parameter refers to an identity server that is not trusted by this homeserver. - examples: - application/json: { - "errcode": "M_THREEPID_IN_USE", - "error": "The specified address is already in use" - } - schema: - "$ref": "definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_THREEPID_IN_USE", + "error": "The specified address is already in use" + } + "403": + description: The homeserver does not permit the address to be bound. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_THREEPID_DENIED", + "error": "Third-party identifier is not allowed" + } tags: - Account management - "/account/password": + /account/password: post: - summary: "Changes a user's password." + summary: Changes a user's password. description: |- Changes the password for an account on this homeserver. @@ -366,53 +389,61 @@ paths: security: - accessToken: [] operationId: changePassword - parameters: - - in: body - name: body - required: true - schema: - type: object - properties: - new_password: - type: string - description: The new password for the account. - example: "ihatebananas" - logout_devices: - type: boolean - description: |- - Whether the user's other access tokens, and their associated devices, should be - revoked if the request succeeds. Defaults to true. + requestBody: + content: + application/json: + schema: + type: object + properties: + new_password: + type: string + description: The new password for the account. + example: ihatebananas + logout_devices: + type: boolean + description: |- + Whether the user's other access tokens, and their associated devices, should be + revoked if the request succeeds. Defaults to true. - When `false`, the server can still take advantage of the [soft logout method](/client-server-api/#soft-logout) - for the user's remaining devices. - example: true - auth: - description: |- - Additional authentication information for the user-interactive authentication API. - allOf: - - "$ref": "definitions/auth_data.yaml" - required: ["new_password"] + When `false`, the server can still take advantage of the [soft logout method](/client-server-api/#soft-logout) + for the user's remaining devices. + example: true + auth: + description: Additional authentication information for the user-interactive + authentication API. + allOf: + - $ref: definitions/auth_data.yaml + required: + - new_password + required: true responses: - 200: + "200": description: The password has been changed. - examples: - application/json: {} - schema: - type: object - 401: - description: |- - The homeserver requires additional authentication information. - schema: - "$ref": "definitions/auth_response.yaml" - 429: + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "401": + description: The homeserver requires additional authentication information. + content: + application/json: + schema: + $ref: definitions/auth_response.yaml + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Account management - "/account/password/email/requestToken": + /account/password/email/requestToken: post: - summary: Requests a validation token be sent to the given email address for the purpose of resetting a user's password + summary: Requests a validation token be sent to the given email address for the + purpose of resetting a user's password description: |- The homeserver must check that the given email address **is associated** with an account on this homeserver. This API should be @@ -430,46 +461,55 @@ paths: The homeserver should validate the email itself, either by sending a validation email itself or by using a service it has control over. operationId: requestTokenToResetPasswordEmail - parameters: - - in: body - name: body - required: true - schema: - $ref: "definitions/request_email_validation.yaml" + requestBody: + content: + application/json: + schema: + $ref: definitions/request_email_validation.yaml + required: true responses: - 200: + "200": description: An email was sent to the given address. - schema: - $ref: "definitions/request_token_response.yaml" - 403: - description: |- - The homeserver does not allow the third-party identifier as a - contact option. - schema: - $ref: "definitions/errors/error.yaml" - examples: - application/json: { - "errcode": "M_THREEPID_DENIED", - "error": "Third-party identifier is not allowed" - } - 400: + content: + application/json: + schema: + $ref: definitions/request_token_response.yaml + "400": description: |- The referenced third-party identifier is not recognised by the homeserver, or the request was invalid. The error code `M_SERVER_NOT_TRUSTED` can be returned if the server does not trust/support the identity server provided in the request. - schema: - $ref: "definitions/errors/error.yaml" - examples: - application/json: { - "errcode": "M_THREEPID_NOT_FOUND", - "error": "Email not found" - } + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_THREEPID_NOT_FOUND", + "error": "Email not found" + } + "403": + description: |- + The homeserver does not allow the third-party identifier as a + contact option. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_THREEPID_DENIED", + "error": "Third-party identifier is not allowed" + } tags: - Account management - "/account/password/msisdn/requestToken": + /account/password/msisdn/requestToken: post: - summary: Requests a validation token be sent to the given phone number for the purpose of resetting a user's password. + summary: Requests a validation token be sent to the given phone number for the + purpose of resetting a user's password. description: |- The homeserver must check that the given phone number **is associated** with an account on this homeserver. This API should be @@ -487,46 +527,54 @@ paths: The homeserver should validate the phone number itself, either by sending a validation message itself or by using a service it has control over. operationId: requestTokenToResetPasswordMSISDN - parameters: - - in: body - name: body - required: true - schema: - $ref: "definitions/request_msisdn_validation.yaml" + requestBody: + content: + application/json: + schema: + $ref: definitions/request_msisdn_validation.yaml + required: true responses: - 200: + "200": description: An SMS message was sent to the given phone number. - schema: - $ref: "definitions/request_token_response.yaml" - 403: - description: |- - The homeserver does not allow the third-party identifier as a - contact option. - schema: - $ref: "definitions/errors/error.yaml" - examples: - application/json: { - "errcode": "M_THREEPID_DENIED", - "error": "Third-party identifier is not allowed" - } - 400: + content: + application/json: + schema: + $ref: definitions/request_token_response.yaml + "400": description: |- The referenced third-party identifier is not recognised by the homeserver, or the request was invalid. The error code `M_SERVER_NOT_TRUSTED` can be returned if the server does not trust/support the identity server provided in the request. - schema: - $ref: "definitions/errors/error.yaml" - examples: - application/json: { - "errcode": "M_THREEPID_NOT_FOUND", - "error": "Phone number not found" - } + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_THREEPID_NOT_FOUND", + "error": "Phone number not found" + } + "403": + description: |- + The homeserver does not allow the third-party identifier as a + contact option. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_THREEPID_DENIED", + "error": "Third-party identifier is not allowed" + } tags: - Account management - "/account/deactivate": + /account/deactivate: post: - summary: "Deactivate a user's account." + summary: Deactivate a user's account. description: |- Deactivate the user's account, removing all ability for the user to login again. @@ -545,63 +593,68 @@ paths: security: - accessToken: [] operationId: deactivateAccount - parameters: - - in: body - name: body - required: true - schema: - type: object - properties: - auth: - description: |- - Additional authentication information for the user-interactive authentication API. - allOf: - - $ref: "definitions/auth_data.yaml" - id_server: - type: string - description: |- - The identity server to unbind all of the user's 3PIDs from. - If not provided, the homeserver MUST use the `id_server` - that was originally use to bind each identifier. If the - homeserver does not know which `id_server` that was, - it must return an `id_server_unbind_result` of - `no-support`. - example: "example.org" + requestBody: + content: + application/json: + schema: + type: object + properties: + auth: + description: Additional authentication information for the user-interactive + authentication API. + allOf: + - $ref: definitions/auth_data.yaml + id_server: + type: string + description: |- + The identity server to unbind all of the user's 3PIDs from. + If not provided, the homeserver MUST use the `id_server` + that was originally use to bind each identifier. If the + homeserver does not know which `id_server` that was, + it must return an `id_server_unbind_result` of + `no-support`. + example: example.org + required: true responses: - 200: + "200": description: The account has been deactivated. - schema: - type: object - properties: - id_server_unbind_result: - type: string - enum: - - "success" - - "no-support" - description: |- - An indicator as to whether or not the homeserver was able to unbind - the user's 3PIDs from the identity server(s). `success` indicates - that all identifiers have been unbound from the identity server while - `no-support` indicates that one or more identifiers failed to unbind - due to the identity server refusing the request or the homeserver - being unable to determine an identity server to unbind from. This - must be `success` if the homeserver has no identifiers to unbind - for the user. - example: "success" - required: - - id_server_unbind_result - 401: - description: |- - The homeserver requires additional authentication information. - schema: - "$ref": "definitions/auth_response.yaml" - 429: + content: + application/json: + schema: + type: object + properties: + id_server_unbind_result: + type: string + enum: + - success + - no-support + description: |- + An indicator as to whether or not the homeserver was able to unbind + the user's 3PIDs from the identity server(s). `success` indicates + that all identifiers have been unbound from the identity server while + `no-support` indicates that one or more identifiers failed to unbind + due to the identity server refusing the request or the homeserver + being unable to determine an identity server to unbind from. This + must be `success` if the homeserver has no identifiers to unbind + for the user. + example: success + required: + - id_server_unbind_result + "401": + description: The homeserver requires additional authentication information. + content: + application/json: + schema: + $ref: definitions/auth_response.yaml + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Account management - "/register/available": + /register/available: get: summary: Checks to see if a username is available on the server. description: |- @@ -621,27 +674,31 @@ paths: parameters: - in: query name: username - type: string - x-example: my_cool_localpart required: true - default: my_cool_localpart description: The username to check the availability of. - responses: - 200: - description: The username is available - examples: - application/json: { - "available": true - } + example: my_cool_localpart schema: - type: object - properties: - available: - type: boolean - description: |- - A flag to indicate that the username is available. This should always - be `true` when the server replies with 200 OK. - 400: + type: string + default: my_cool_localpart + responses: + "200": + description: The username is available + content: + application/json: + schema: + type: object + properties: + available: + type: boolean + description: |- + A flag to indicate that the username is available. This should always + be `true` when the server replies with 200 OK. + examples: + response: + value: { + "available": true + } + "400": description: |- Part of the request was invalid or the username is not available. This may include one of the following error codes: @@ -650,16 +707,33 @@ paths: * `M_INVALID_USERNAME` : The desired username is not a valid user name. * `M_EXCLUSIVE` : The desired username is in the exclusive namespace claimed by an application service. - examples: - application/json: { - "errcode": "M_USER_IN_USE", - "error": "Desired user ID is already taken." - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_USER_IN_USE", + "error": "Desired user ID is already taken." + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Account management +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 diff --git a/data/api/client-server/registration_tokens.yaml b/data/api/client-server/registration_tokens.yaml index 11241b57..9468a0bb 100644 --- a/data/api/client-server/registration_tokens.yaml +++ b/data/api/client-server/registration_tokens.yaml @@ -11,21 +11,12 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server Registration Token API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v1 -consumes: - - application/json -produces: - - application/json + title: Matrix Client-Server Registration Token API + version: 1.0.0 paths: - "/register/m.login.registration_token/validity": + /register/m.login.registration_token/validity: get: x-addedInMatrixVersion: "1.2" summary: Query if a given registration token is still valid. @@ -40,41 +31,63 @@ paths: parameters: - in: query name: token - type: string - x-example: "fBVFdqVE" required: true description: The token to check validity of. - responses: - 200: - description: The check has a result. - examples: - application/json: { - "valid": true - } + example: fBVFdqVE schema: - type: object - properties: - valid: - type: boolean - description: |- - True if the token is still valid, false otherwise. This should - additionally be false if the token is not a recognised token by - the server. - required: ['valid'] - 403: + type: string + responses: + "200": + description: The check has a result. + content: + application/json: + schema: + type: object + properties: + valid: + type: boolean + description: |- + True if the token is still valid, false otherwise. This should + additionally be false if the token is not a recognised token by + the server. + required: + - valid + examples: + response: + value: { + "valid": true + } + "403": description: |- The homeserver does not permit registration and thus all tokens are considered invalid. - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "Registration is not enabled on this homeserver." - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "Registration is not enabled on this homeserver." + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Account management +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v1 diff --git a/data/api/client-server/relations.yaml b/data/api/client-server/relations.yaml index a0abae1b..65c3491a 100644 --- a/data/api/client-server/relations.yaml +++ b/data/api/client-server/relations.yaml @@ -11,21 +11,10 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server Relations API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v1 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server Relations API + version: 1.0.0 paths: "/rooms/{roomId}/relations/{eventId}": get: @@ -45,19 +34,20 @@ paths: - accessToken: [] parameters: - in: path - type: string name: roomId description: The ID of the room containing the parent event. required: true - x-example: "!636q39766251:matrix.org" + example: "!636q39766251:matrix.org" + schema: + type: string - in: path - type: string name: eventId description: The ID of the parent event whose child events are to be returned. required: true - x-example: "$asfDuShaf7Gafaw" + example: $asfDuShaf7Gafaw + schema: + type: string - in: query - type: string name: from description: |- The pagination token to start returning results from. If not supplied, results @@ -67,9 +57,10 @@ paths: `start` token from [`/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages), or a `next_batch` token from [`/sync`](/client-server-api/#get_matrixclientv3sync). required: false - x-example: "page2_token" + example: page2_token + schema: + type: string - in: query - type: string name: to description: |- The pagination token to stop returning results at. If not supplied, results @@ -78,9 +69,10 @@ paths: Like `from`, this can be a previous token from a prior call to this endpoint or from `/messages` or `/sync`. required: false - x-example: "page3_token" + example: page3_token + schema: + type: string - in: query - type: integer name: limit description: |- The maximum number of results to return in a single `chunk`. The server can @@ -88,10 +80,10 @@ paths: Similarly, the server should apply a default value when not supplied. required: false - x-example: 20 + example: 20 + schema: + type: integer - in: query - type: string - enum: ["b", "f"] name: dir x-addedInMatrixVersion: "1.4" description: |- @@ -99,63 +91,76 @@ paths: will be returned in chronological order starting at `from`. If it is set to `b`, events will be returned in *reverse* chronological order, again starting at `from`. + schema: + type: string + enum: + - b + - f responses: # note: this endpoint deliberately does not support rate limiting, therefore a # 429 error response is not included. - - 200: + "200": description: |- The paginated child events which point to the parent. If no events are pointing to the parent or the pagination yields no results, an empty `chunk` is returned. - examples: - application/json: { - "chunk": [{ - "room_id": "!636q39766251:matrix.org", - "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml", - "content": { - "m.relates_to": { - "rel_type": "org.example.my_relation", - "event_id": "$asfDuShaf7Gafaw" + content: + application/json: + schema: + type: object + properties: + chunk: + title: ChildEventsChunk + type: array + description: The child events of the requested event, ordered topologically + most-recent first. + items: + allOf: + - $ref: definitions/client_event.yaml + next_batch: + type: string + description: |- + An opaque string representing a pagination token. The absence of this token + means there are no more results to fetch and the client should stop paginating. + prev_batch: + type: string + description: |- + An opaque string representing a pagination token. The absence of this token + means this is the start of the result set, i.e. this is the first batch/page. + required: + - chunk + examples: + response: + value: { + "chunk": [ + { + "room_id": "!636q39766251:matrix.org", + "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml", + "content": { + "m.relates_to": { + "rel_type": "org.example.my_relation", + "event_id": "$asfDuShaf7Gafaw" + } + } + } + ], + "next_batch": "page2_token", + "prev_batch": "page1_token" } - } - }], - "next_batch": "page2_token", - "prev_batch": "page1_token" - } - schema: - type: object - properties: - chunk: - title: "ChildEventsChunk" - type: array - description: |- - The child events of the requested event, ordered topologically most-recent first. - items: - allOf: - - "$ref": "definitions/client_event.yaml" - next_batch: - type: string - description: |- - An opaque string representing a pagination token. The absence of this token - means there are no more results to fetch and the client should stop paginating. - prev_batch: - type: string - description: |- - An opaque string representing a pagination token. The absence of this token - means this is the start of the result set, i.e. this is the first batch/page. - required: ['chunk'] - 404: + "404": description: |- The parent event was not found or the user does not have permission to read this event (it might be contained in history that is not accessible to the user). - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Event not found." - } - schema: - "$ref": "definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Event not found." + } tags: - Event relationships # The same as above, with added `/{relType}` @@ -178,26 +183,28 @@ paths: - accessToken: [] parameters: - in: path - type: string name: roomId description: The ID of the room containing the parent event. required: true - x-example: "!636q39766251:matrix.org" + example: "!636q39766251:matrix.org" + schema: + type: string - in: path - type: string name: eventId description: The ID of the parent event whose child events are to be returned. required: true - x-example: "$asfDuShaf7Gafaw" + example: $asfDuShaf7Gafaw + schema: + type: string - in: path - type: string name: relType - description: |- - The [relationship type](/client-server-api/#relationship-types) to search for. + description: The [relationship type](/client-server-api/#relationship-types) to + search for. required: true - x-example: "org.example.my_relation" + example: org.example.my_relation + schema: + type: string - in: query - type: string name: from description: |- The pagination token to start returning results from. If not supplied, results @@ -207,9 +214,10 @@ paths: `start` token from [`/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages), or a `next_batch` token from [`/sync`](/client-server-api/#get_matrixclientv3sync). required: false - x-example: "page2_token" + example: page2_token + schema: + type: string - in: query - type: string name: to description: |- The pagination token to stop returning results at. If not supplied, results @@ -218,9 +226,10 @@ paths: Like `from`, this can be a previous token from a prior call to this endpoint or from `/messages` or `/sync`. required: false - x-example: "page3_token" + example: page3_token + schema: + type: string - in: query - type: integer name: limit description: |- The maximum number of results to return in a single `chunk`. The server can @@ -228,10 +237,10 @@ paths: Similarly, the server should apply a default value when not supplied. required: false - x-example: 20 + example: 20 + schema: + type: integer - in: query - type: string - enum: ["b", "f"] name: dir x-addedInMatrixVersion: "1.4" description: |- @@ -239,71 +248,85 @@ paths: will be returned in chronological order starting at `from`. If it is set to `b`, events will be returned in *reverse* chronological order, again starting at `from`. + schema: + type: string + enum: + - b + - f responses: # note: this endpoint deliberately does not support rate limiting, therefore a # 429 error response is not included. - - 200: + "200": description: |- The paginated child events which point to the parent. If no events are pointing to the parent or the pagination yields no results, an empty `chunk` is returned. - examples: - application/json: { - "chunk": [{ - "room_id": "!636q39766251:matrix.org", - "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml", - "content": { - "m.relates_to": { - "rel_type": "org.example.my_relation", - "event_id": "$asfDuShaf7Gafaw" + content: + application/json: + schema: + type: object + properties: + chunk: + title: ChildEventsChunk + type: array + description: |- + The child events of the requested event, ordered topologically + most-recent first. The events returned will match the `relType` + supplied in the URL. + items: + allOf: + - $ref: definitions/client_event.yaml + next_batch: + type: string + description: |- + An opaque string representing a pagination token. The absence of this token + means there are no more results to fetch and the client should stop paginating. + prev_batch: + type: string + description: |- + An opaque string representing a pagination token. The absence of this token + means this is the start of the result set, i.e. this is the first batch/page. + required: + - chunk + examples: + response: + value: { + "chunk": [ + { + "room_id": "!636q39766251:matrix.org", + "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml", + "content": { + "m.relates_to": { + "rel_type": "org.example.my_relation", + "event_id": "$asfDuShaf7Gafaw" + } + } + } + ], + "next_batch": "page2_token", + "prev_batch": "page1_token" } - } - }], - "next_batch": "page2_token", - "prev_batch": "page1_token" - } - schema: - type: object - properties: - chunk: - title: "ChildEventsChunk" - type: array - description: |- - The child events of the requested event, ordered topologically - most-recent first. The events returned will match the `relType` - supplied in the URL. - items: - allOf: - - "$ref": "definitions/client_event.yaml" - next_batch: - type: string - description: |- - An opaque string representing a pagination token. The absence of this token - means there are no more results to fetch and the client should stop paginating. - prev_batch: - type: string - description: |- - An opaque string representing a pagination token. The absence of this token - means this is the start of the result set, i.e. this is the first batch/page. - required: ['chunk'] - 404: + "404": description: |- The parent event was not found or the user does not have permission to read this event (it might be contained in history that is not accessible to the user). - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Event not found." - } - schema: - "$ref": "definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Event not found." + } tags: - Event relationships # The same as above, with added `/{eventType}` "/rooms/{roomId}/relations/{eventId}/{relType}/{eventType}": get: - summary: Get the child events for a given parent event, with a given `relType` and `eventType`. + summary: Get the child events for a given parent event, with a given `relType` + and `eventType`. description: |- Retrieve all of the child events for a given parent event which relate to the parent using the given `relType` and have the given `eventType`. @@ -320,26 +343,28 @@ paths: - accessToken: [] parameters: - in: path - type: string name: roomId description: The ID of the room containing the parent event. required: true - x-example: "!636q39766251:matrix.org" + example: "!636q39766251:matrix.org" + schema: + type: string - in: path - type: string name: eventId description: The ID of the parent event whose child events are to be returned. required: true - x-example: "$asfDuShaf7Gafaw" + example: $asfDuShaf7Gafaw + schema: + type: string - in: path - type: string name: relType - description: |- - The [relationship type](/client-server-api/#relationship-types) to search for. + description: The [relationship type](/client-server-api/#relationship-types) to + search for. required: true - x-example: "org.example.my_relation" + example: org.example.my_relation + schema: + type: string - in: path - type: string name: eventType description: |- The event type of child events to search for. @@ -347,9 +372,10 @@ paths: Note that in encrypted rooms this will typically always be `m.room.encrypted` regardless of the event type contained within the encrypted payload. required: true - x-example: "m.room.message" + example: m.room.message + schema: + type: string - in: query - type: string name: from description: |- The pagination token to start returning results from. If not supplied, results @@ -359,9 +385,10 @@ paths: `start` token from [`/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages), or a `next_batch` token from [`/sync`](/client-server-api/#get_matrixclientv3sync). required: false - x-example: "page2_token" + example: page2_token + schema: + type: string - in: query - type: string name: to description: |- The pagination token to stop returning results at. If not supplied, results @@ -370,9 +397,10 @@ paths: Like `from`, this can be a previous token from a prior call to this endpoint or from `/messages` or `/sync`. required: false - x-example: "page3_token" + example: page3_token + schema: + type: string - in: query - type: integer name: limit description: |- The maximum number of results to return in a single `chunk`. The server can @@ -380,10 +408,10 @@ paths: Similarly, the server should apply a default value when not supplied. required: false - x-example: 20 + example: 20 + schema: + type: integer - in: query - type: string - enum: ["b", "f"] name: dir x-addedInMatrixVersion: "1.4" description: |- @@ -391,65 +419,92 @@ paths: will be returned in chronological order starting at `from`. If it is set to `b`, events will be returned in *reverse* chronological order, again starting at `from`. + schema: + type: string + enum: + - b + - f responses: # note: this endpoint deliberately does not support rate limiting, therefore a # 429 error response is not included. - - 200: + "200": description: |- The paginated child events which point to the parent. If no events are pointing to the parent or the pagination yields no results, an empty `chunk` is returned. - examples: - application/json: { - "chunk": [{ - "room_id": "!636q39766251:matrix.org", - "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml", - "content": { - "m.relates_to": { - "rel_type": "org.example.my_relation", - "event_id": "$asfDuShaf7Gafaw" + content: + application/json: + schema: + type: object + properties: + chunk: + title: ChildEventsChunk + type: array + description: |- + The child events of the requested event, ordered topologically most-recent + first. The events returned will match the `relType` and `eventType` supplied + in the URL. + items: + allOf: + - $ref: definitions/client_event.yaml + next_batch: + type: string + description: |- + An opaque string representing a pagination token. The absence of this token + means there are no more results to fetch and the client should stop paginating. + prev_batch: + type: string + description: |- + An opaque string representing a pagination token. The absence of this token + means this is the start of the result set, i.e. this is the first batch/page. + required: + - chunk + examples: + response: + value: { + "chunk": [ + { + "room_id": "!636q39766251:matrix.org", + "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml", + "content": { + "m.relates_to": { + "rel_type": "org.example.my_relation", + "event_id": "$asfDuShaf7Gafaw" + } + } + } + ], + "next_batch": "page2_token", + "prev_batch": "page1_token" } - } - }], - "next_batch": "page2_token", - "prev_batch": "page1_token" - } - schema: - type: object - properties: - chunk: - title: "ChildEventsChunk" - type: array - description: |- - The child events of the requested event, ordered topologically most-recent - first. The events returned will match the `relType` and `eventType` supplied - in the URL. - items: - allOf: - - "$ref": "definitions/client_event.yaml" - next_batch: - type: string - description: |- - An opaque string representing a pagination token. The absence of this token - means there are no more results to fetch and the client should stop paginating. - prev_batch: - type: string - description: |- - An opaque string representing a pagination token. The absence of this token - means this is the start of the result set, i.e. this is the first batch/page. - required: ['chunk'] - 404: + "404": description: |- The parent event was not found or the user does not have permission to read this event (it might be contained in history that is not accessible to the user). - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Event not found." - } - schema: - "$ref": "definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Event not found." + } tags: - Event relationships - +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v1 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/report_content.yaml b/data/api/client-server/report_content.yaml index 7f8b3425..5ea7b634 100644 --- a/data/api/client-server/report_content.yaml +++ b/data/api/client-server/report_content.yaml @@ -11,21 +11,10 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server Report Content API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server Report Content API + version: 1.0.0 paths: "/rooms/{roomId}/report/{eventId}": post: @@ -36,43 +25,64 @@ paths: operationId: reportContent parameters: - in: path - type: string name: roomId description: The room in which the event being reported is located. required: true - x-example: "!637q39766251:example.com" + example: "!637q39766251:example.com" + schema: + type: string - in: path - type: string name: eventId description: The event to report. required: true - x-example: "$something:example.org" - - in: body - name: body - required: true + example: $something:example.org schema: - type: object - example: { - "score": -100, - "reason": "this makes me sad" - } - properties: - score: - type: integer - description: |- - The score to rate this content as where -100 is most offensive - and 0 is inoffensive. - reason: - type: string - description: The reason the content is being reported. May be blank. + type: string + requestBody: + content: + application/json: + schema: + type: object + example: { + "score": -100, + "reason": "this makes me sad" + } + properties: + score: + type: integer + description: |- + The score to rate this content as where -100 is most offensive + and 0 is inoffensive. + reason: + type: string + description: The reason the content is being reported. May be blank. + required: true security: - accessToken: [] responses: - 200: + "200": description: The event has been reported successfully. - schema: - type: object - examples: - application/json: {} + content: + application/json: + schema: + type: object + examples: + response: + value: {} tags: - Reporting content +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/room_event_by_timestamp.yaml b/data/api/client-server/room_event_by_timestamp.yaml index 7b360921..19e7302b 100644 --- a/data/api/client-server/room_event_by_timestamp.yaml +++ b/data/api/client-server/room_event_by_timestamp.yaml @@ -11,21 +11,10 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server events in room by date API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v1 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server events in room by date API + version: 1.0.0 paths: "/rooms/{roomId}/timestamp_to_event": get: @@ -60,64 +49,91 @@ paths: - accessToken: [] parameters: - in: path - type: string name: roomId description: The ID of the room to search required: true - x-example: "!636q39766251:matrix.org" + example: "!636q39766251:matrix.org" + schema: + type: string - in: query - type: integer name: ts description: |- The timestamp to search from, as given in milliseconds since the Unix epoch. required: true - x-example: 1432684800000 + example: 1432684800000 + schema: + type: integer - in: query - type: string - enum: [f, b] name: dir - description: |- - The direction in which to search. `f` for forwards, `b` for backwards. + description: The direction in which to search. `f` for forwards, `b` for + backwards. required: true - x-example: f + example: f + schema: + type: string + enum: + - f + - b responses: - 200: - description: |- - An event was found matching the search parameters. - schema: - type: object - properties: - event_id: - type: string - description: |- - The ID of the event found - origin_server_ts: - type: integer - description: |- - The event's timestamp, in milliseconds since the Unix epoch. - This makes it easy to do a quick comparison to see if the - `event_id` fetched is too far out of range to be useful for your - use case. - required: ['event_id', 'origin_server_ts'] - examples: - application/json: { - "event_id": "$143273582443PhrSn:example.org", - "origin_server_ts": 1432735824653 - } - 404: - description: |- - No event was found. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Unable to find event from 1432684800000 in forward direction" - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + "200": + description: An event was found matching the search parameters. + content: + application/json: + schema: + type: object + properties: + event_id: + type: string + description: The ID of the event found + origin_server_ts: + type: integer + description: |- + The event's timestamp, in milliseconds since the Unix epoch. + This makes it easy to do a quick comparison to see if the + `event_id` fetched is too far out of range to be useful for your + use case. + required: + - event_id + - origin_server_ts + examples: + response: + value: { + "event_id": "$143273582443PhrSn:example.org", + "origin_server_ts": 1432735824653 + } + "404": + description: No event was found. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Unable to find event from 1432684800000 in forward direction" + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Room participation +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v1 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/room_initial_sync.yaml b/data/api/client-server/room_initial_sync.yaml index 64e7f4f2..53cb0bee 100644 --- a/data/api/client-server/room_initial_sync.yaml +++ b/data/api/client-server/room_initial_sync.yaml @@ -1,18 +1,7 @@ -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server Rooms API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server Rooms API + version: 1.0.0 paths: "/rooms/{roomId}/initialSync": get: @@ -29,127 +18,161 @@ paths: - accessToken: [] parameters: - in: path - type: string name: roomId description: The room to get the data. required: true - x-example: "!636q39766251:example.com" - responses: - 200: - description: The current state of the room - examples: - application/json: { - "membership": "join", - "messages": { - "chunk": [ - { - "room_id": "!636q39766251:example.com", - "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" - }, - { - "room_id": "!636q39766251:example.com", - "$ref": "../../event-schemas/examples/m.room.message$m.file.yaml" - } - ], - "end": "s3456_9_0", - "start": "t44-3453_9_0" - }, - "room_id": "!636q39766251:example.com", - "state": [ - { - "room_id": "!636q39766251:example.com", - "$ref": "../../event-schemas/examples/m.room.join_rules.yaml" - }, - { - "room_id": "!636q39766251:example.com", - "$ref": "../../event-schemas/examples/m.room.member.yaml" - }, - { - "room_id": "!636q39766251:example.com", - "$ref": "../../event-schemas/examples/m.room.create.yaml" - }, - { - "room_id": "!636q39766251:example.com", - "$ref": "../../event-schemas/examples/m.room.power_levels.yaml" - } - ], - "visibility": "private", - "account_data": [{ - "type": "m.tag", - "content": {"tags": {"work": {"order": "1"}}} - }] - } + example: "!636q39766251:example.com" schema: - title: RoomInfo - type: object - properties: - room_id: - type: string - description: "The ID of this room." - membership: - type: string - description: "The user's membership state in this room." - enum: ["invite", "join", "leave", "ban"] - messages: + type: string + responses: + "200": + description: The current state of the room + content: + application/json: + schema: + title: RoomInfo type: object - title: PaginationChunk - description: "The pagination chunk for this room." properties: - start: + room_id: type: string - description: |- - A token which correlates to the start of `chunk`. Can be passed to - [`/rooms//messages`](#get_matrixclientv3roomsroomidmessages) - to retrieve earlier events. + description: The ID of this room. + membership: + type: string + description: The user's membership state in this room. + enum: + - invite + - join + - leave + - ban + messages: + type: object + title: PaginationChunk + description: The pagination chunk for this room. + properties: + start: + type: string + description: |- + A token which correlates to the start of `chunk`. Can be passed to + [`/rooms//messages`](#get_matrixclientv3roomsroomidmessages) + to retrieve earlier events. - If no earlier events are available, this property may be omitted from - the response. - end: - type: string - description: |- - A token which correlates to the end of `chunk`. Can be passed to - [`/rooms//messages`](#get_matrixclientv3roomsroomidmessages) - to retrieve later events. - chunk: + If no earlier events are available, this property may be omitted from + the response. + end: + type: string + description: |- + A token which correlates to the end of `chunk`. Can be passed to + [`/rooms//messages`](#get_matrixclientv3roomsroomidmessages) + to retrieve later events. + chunk: + type: array + description: |- + If the user is a member of the room this will be a + list of the most recent messages for this room. If + the user has left the room this will be the + messages that preceded them leaving. This array + will consist of at most `limit` elements. + items: + $ref: definitions/client_event.yaml + required: + - end + - chunk + state: type: array description: |- - If the user is a member of the room this will be a - list of the most recent messages for this room. If - the user has left the room this will be the - messages that preceded them leaving. This array - will consist of at most `limit` elements. + If the user is a member of the room this will be the + current state of the room as a list of events. If the + user has left the room this will be the state of the + room when they left it. items: - "$ref": "definitions/client_event.yaml" - required: ["end", "chunk"] - state: - type: array - description: |- - If the user is a member of the room this will be the - current state of the room as a list of events. If the - user has left the room this will be the state of the - room when they left it. - items: - "$ref": "definitions/client_event.yaml" - visibility: - type: string - enum: ["private", "public"] - description: |- - Whether this room is visible to the `/publicRooms` API - or not." - account_data: - type: array - description: |- - The private data that this user has attached to this room. - items: - title: Event - type: object - allOf: - - "$ref": "../../event-schemas/schema/core-event-schema/event.yaml" - required: ["room_id"] - 403: - description: > - You aren't a member of the room and weren't previously a - member of the room. + $ref: definitions/client_event.yaml + visibility: + type: string + enum: + - private + - public + description: |- + Whether this room is visible to the `/publicRooms` API + or not." + account_data: + type: array + description: The private data that this user has attached to this room. + items: + title: Event + type: object + allOf: + - $ref: ../../event-schemas/schema/core-event-schema/event.yaml + required: + - room_id + examples: + response: + value: { + "membership": "join", + "messages": { + "chunk": [ + { + "room_id": "!636q39766251:example.com", + "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" + }, + { + "room_id": "!636q39766251:example.com", + "$ref": "../../event-schemas/examples/m.room.message$m.file.yaml" + } + ], + "end": "s3456_9_0", + "start": "t44-3453_9_0" + }, + "room_id": "!636q39766251:example.com", + "state": [ + { + "room_id": "!636q39766251:example.com", + "$ref": "../../event-schemas/examples/m.room.join_rules.yaml" + }, + { + "room_id": "!636q39766251:example.com", + "$ref": "../../event-schemas/examples/m.room.member.yaml" + }, + { + "room_id": "!636q39766251:example.com", + "$ref": "../../event-schemas/examples/m.room.create.yaml" + }, + { + "room_id": "!636q39766251:example.com", + "$ref": "../../event-schemas/examples/m.room.power_levels.yaml" + } + ], + "visibility": "private", + "account_data": [ + { + "type": "m.tag", + "content": { + "tags": { + "work": { + "order": "1" + } + } + } + } + ] + } + "403": + description: | + You aren't a member of the room and weren't previously a member of the room. tags: - Room participation deprecated: true +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/room_send.yaml b/data/api/client-server/room_send.yaml index 43823c45..638dc86d 100644 --- a/data/api/client-server/room_send.yaml +++ b/data/api/client-server/room_send.yaml @@ -12,21 +12,10 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server message event send API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server message event send API + version: 1.0.0 paths: "/rooms/{roomId}/send/{eventType}/{txnId}": put: @@ -44,58 +33,81 @@ paths: - accessToken: [] parameters: - in: path - type: string name: roomId description: The room to send the event to. required: true - x-example: "!636q39766251:example.com" + example: "!636q39766251:example.com" + schema: + type: string - in: path - type: string name: eventType description: The type of event to send. required: true - x-example: "m.room.message" + example: m.room.message + schema: + type: string - in: path name: txnId - type: string description: |- The [transaction ID](/client-server-api/#transaction-identifiers) for this event. Clients should generate an ID unique across requests with the same access token; it will be used by the server to ensure idempotency of requests. required: true - x-example: "35" - - in: body - name: body - required: true + example: "35" schema: - type: object - example: { + type: string + requestBody: + content: + application/json: + schema: + type: object + example: { "msgtype": "m.text", "body": "hello" } + required: true responses: - 200: - description: "An ID for the sent event." - examples: - application/json: { - "event_id": "$YUwRidLecu:example.com" - } - schema: - type: object - properties: - event_id: - type: string - description: |- - A unique identifier for the event. - required: - - event_id - 400: + "200": + description: An ID for the sent event. + content: + application/json: + schema: + type: object + properties: + event_id: + type: string + description: A unique identifier for the event. + required: + - event_id + examples: + response: + value: { + "event_id": "$YUwRidLecu:example.com" + } + "400": description: |- The request is invalid. A [standard error response](/client-server-api/#standard-error-response) will be returned. As well as the normal common error codes, other reasons for rejection include: - `M_DUPLICATE_ANNOTATION`: The request is an attempt to send a [duplicate annotation](/client-server-api/#avoiding-duplicate-annotations). - schema: - "$ref": "definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: definitions/errors/error.yaml tags: - Room participation +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/room_state.yaml b/data/api/client-server/room_state.yaml index d43bc802..1c03dbdd 100644 --- a/data/api/client-server/room_state.yaml +++ b/data/api/client-server/room_state.yaml @@ -11,21 +11,10 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server state event send API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server state event send API + version: 1.0.0 paths: "/rooms/{roomId}/state/{eventType}/{stateKey}": put: @@ -53,62 +42,58 @@ paths: - accessToken: [] parameters: - in: path - type: string name: roomId description: The room to set the state in required: true - x-example: "!636q39766251:example.com" + example: "!636q39766251:example.com" + schema: + type: string - in: path - type: string name: eventType description: The type of event to send. required: true - x-example: "m.room.member" + example: m.room.member + schema: + type: string - in: path - type: string name: stateKey description: |- The state_key for the state to send. Defaults to the empty string. When an empty string, the trailing slash on this endpoint is optional. required: true - x-example: "@alice:example.com" - - in: body - name: body - required: true + example: "@alice:example.com" schema: - type: object - example: { + type: string + requestBody: + content: + application/json: + schema: + type: object + example: { "membership": "join", "avatar_url": "mxc://localhost/SEsfnsuifSDFSSEF", "displayname": "Alice Margatroid" } + required: true responses: - 200: - description: "An ID for the sent event." - examples: - application/json: { - "event_id": "$YUwRidLecu:example.com" - } - schema: - type: object - properties: - event_id: - type: string - description: |- - A unique identifier for the event. - required: - - event_id - 403: - description: |- - The sender doesn't have permission to send the event into the room. - schema: - $ref: "definitions/errors/error.yaml" - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "You do not have permission to send the event." - } - 400: + "200": + description: An ID for the sent event. + content: + application/json: + schema: + type: object + properties: + event_id: + type: string + description: A unique identifier for the event. + required: + - event_id + examples: + response: + value: { + "event_id": "$YUwRidLecu:example.com" + } + "400": description: |- The sender's request is malformed. @@ -119,12 +104,42 @@ paths: * `M_BAD_ALIAS`: One or more aliases within the `m.room.canonical_alias` event do not point to the room ID for which the state event is to be sent to. - schema: - $ref: "definitions/errors/error.yaml" - examples: - application/json: { - "errcode": "M_BAD_ALIAS", - "error": "The alias '#hello:example.org' does not point to this room." - } + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_BAD_ALIAS", + "error": "The alias '#hello:example.org' does not point to this room." + } + "403": + description: The sender doesn't have permission to send the event into the room. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "You do not have permission to send the event." + } tags: - Room participation +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/room_upgrades.yaml b/data/api/client-server/room_upgrades.yaml index 41b3a7af..296ffe6a 100644 --- a/data/api/client-server/room_upgrades.yaml +++ b/data/api/client-server/room_upgrades.yaml @@ -11,82 +11,99 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server Room Upgrades API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server Room Upgrades API + version: 1.0.0 paths: "/rooms/{roomId}/upgrade": post: summary: Upgrades a room to a new room version. - description: |- - Upgrades the given room to a particular room version. + description: Upgrades the given room to a particular room version. operationId: upgradeRoom security: - accessToken: [] parameters: - in: path - type: string name: roomId required: true description: The ID of the room to upgrade. - x-example: "!oldroom:example.org" - - in: body - name: body - required: true + example: "!oldroom:example.org" schema: - type: object - properties: - new_version: - type: string - description: The new version for the room. - example: {"new_version": "2"} - required: [new_version] + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + new_version: + type: string + description: The new version for the room. + example: { + "new_version": "2" + } + required: + - new_version + required: true responses: - 200: + "200": description: The room was successfully upgraded. - examples: - application/json: { - "replacement_room": "!newroom:example.org" - } - schema: - type: object - properties: - replacement_room: - type: string - description: The ID of the new room. - required: [replacement_room] - 400: + content: + application/json: + schema: + type: object + properties: + replacement_room: + type: string + description: The ID of the new room. + required: + - replacement_room + examples: + response: + value: { + "replacement_room": "!newroom:example.org" + } + "400": description: |- The request was invalid. One way this can happen is if the room version requested is not supported by the homeserver. - examples: - application/json: { - "errcode": "M_UNSUPPORTED_ROOM_VERSION", - "error": "This server does not support that room version" - } - schema: - "$ref": "definitions/errors/error.yaml" - 403: - description: |- - The user is not permitted to upgrade the room. - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "You cannot upgrade this room" - } - schema: - "$ref": "definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_UNSUPPORTED_ROOM_VERSION", + "error": "This server does not support that room version" + } + "403": + description: The user is not permitted to upgrade the room. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "You cannot upgrade this room" + } tags: - Room upgrades +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/rooms.yaml b/data/api/client-server/rooms.yaml index 2ee3fa19..4a192305 100644 --- a/data/api/client-server/rooms.yaml +++ b/data/api/client-server/rooms.yaml @@ -11,21 +11,10 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server Rooms API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server Rooms API + version: 1.0.0 paths: "/rooms/{roomId}/event/{eventId}": get: @@ -38,36 +27,45 @@ paths: - accessToken: [] parameters: - in: path - type: string name: roomId description: The ID of the room the event is in. required: true - x-example: "!636q39766251:matrix.org" + example: "!636q39766251:matrix.org" + schema: + type: string - in: path - type: string name: eventId description: The event ID to get. required: true - x-example: "$asfDuShaf7Gafaw:matrix.org" + example: $asfDuShaf7Gafaw:matrix.org + schema: + type: string responses: - 200: + "200": description: The full event. - examples: - application/json: { - "room_id": "!636q39766251:matrix.org", - "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" - } - schema: - "$ref": "definitions/client_event.yaml" - 404: - description: The event was not found or you do not have permission to read this event. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Event not found." - } - schema: - "$ref": "definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: definitions/client_event.yaml + examples: + response: + value: { + "room_id": "!636q39766251:matrix.org", + "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" + } + "404": + description: The event was not found or you do not have permission to read this + event. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Event not found." + } tags: - Room participation "/rooms/{roomId}/state/{eventType}/{stateKey}": @@ -83,225 +81,260 @@ paths: - accessToken: [] parameters: - in: path - type: string name: roomId description: The room to look up the state in. required: true - x-example: "!636q39766251:example.com" + example: "!636q39766251:example.com" + schema: + type: string - in: path - type: string name: eventType description: The type of state to look up. required: true - x-example: "m.room.name" + example: m.room.name + schema: + type: string - in: path - type: string name: stateKey description: |- The key of the state to look up. Defaults to an empty string. When an empty string, the trailing slash on this endpoint is optional. required: true - x-example: "" - responses: - 200: - description: The content of the state event. - examples: - application/json: { - "name": "Example room name"} + example: "" schema: - type: object - 404: + type: string + responses: + "200": + description: The content of the state event. + content: + application/json: + schema: + type: object + examples: + response: + value: { + "name": "Example room name" + } + "403": + description: | + You aren't a member of the room and weren't previously a member of the room. + "404": description: The room has no state with the given type or key. - 403: - description: > - You aren't a member of the room and weren't previously a - member of the room. tags: - Room participation "/rooms/{roomId}/state": get: summary: Get all state events in the current state of a room. - description: |- - Get the state events for the current state of a room. + description: Get the state events for the current state of a room. operationId: getRoomState security: - accessToken: [] parameters: - in: path - type: string name: roomId description: The room to look up the state for. required: true - x-example: "!636q39766251:example.com" - responses: - 200: - description: The current state of the room - examples: - application/json: [ - { - "room_id": "!636q39766251:example.com", - "$ref": "../../event-schemas/examples/m.room.join_rules.yaml" - }, - { - "room_id": "!636q39766251:example.com", - "$ref": "../../event-schemas/examples/m.room.member.yaml" - }, - { - "room_id": "!636q39766251:example.com", - "$ref": "../../event-schemas/examples/m.room.create.yaml" - }, - { - "room_id": "!636q39766251:example.com", - "$ref": "../../event-schemas/examples/m.room.power_levels.yaml" - } - ] + example: "!636q39766251:example.com" schema: - type: array - title: RoomState - description: |- - If the user is a member of the room this will be the - current state of the room as a list of events. If the user - has left the room then this will be the state of the room - when they left as a list of events. - items: - $ref: "definitions/client_event.yaml" - 403: - description: > - You aren't a member of the room and weren't previously a - member of the room. + type: string + responses: + "200": + description: The current state of the room + content: + application/json: + schema: + type: array + title: RoomState + description: |- + If the user is a member of the room this will be the + current state of the room as a list of events. If the user + has left the room then this will be the state of the room + when they left as a list of events. + items: + $ref: definitions/client_event.yaml + examples: + response: + value: [ + { + "room_id": "!636q39766251:example.com", + "$ref": "../../event-schemas/examples/m.room.join_rules.yaml" + }, + { + "room_id": "!636q39766251:example.com", + "$ref": "../../event-schemas/examples/m.room.member.yaml" + }, + { + "room_id": "!636q39766251:example.com", + "$ref": "../../event-schemas/examples/m.room.create.yaml" + }, + { + "room_id": "!636q39766251:example.com", + "$ref": "../../event-schemas/examples/m.room.power_levels.yaml" + } + ] + "403": + description: | + You aren't a member of the room and weren't previously a member of the room. tags: - Room participation "/rooms/{roomId}/members": get: summary: Get the m.room.member events for the room. - description: - Get the list of members for this room. + description: Get the list of members for this room. operationId: getMembersByRoom parameters: - in: path - type: string name: roomId description: The room to get the member events for. required: true - x-example: "!636q39766251:example.com" + example: "!636q39766251:example.com" + schema: + type: string - in: query name: at - type: string description: |- The point in time (pagination token) to return members for in the room. This token can be obtained from a `prev_batch` token returned for each room by the sync API. Defaults to the current state of the room, as determined by the server. - x-example: "YWxsCgpOb25lLDM1ODcwOA" + example: YWxsCgpOb25lLDM1ODcwOA + schema: + type: string # XXX: As mentioned in MSC1227, replacing `[not_]membership` with a JSON # filter might be a better alternative. # See https://github.com/matrix-org/matrix-doc/issues/1337 - in: query name: membership - type: string - enum: - - join - - invite - - knock - - leave - - ban description: |- The kind of membership to filter for. Defaults to no filtering if unspecified. When specified alongside `not_membership`, the two parameters create an 'or' condition: either the membership *is* the same as `membership` **or** *is not* the same as `not_membership`. - x-example: "join" + example: join + schema: + type: string + enum: + - join + - invite + - knock + - leave + - ban - in: query name: not_membership - type: string - enum: - - join - - invite - - knock - - leave - - ban description: |- The kind of membership to exclude from the results. Defaults to no filtering if unspecified. - x-example: leave + example: leave + schema: + type: string + enum: + - join + - invite + - knock + - leave + - ban security: - accessToken: [] responses: - 200: + "200": description: |- A list of members of the room. If you are joined to the room then this will be the current members of the room. If you have left the room then this will be the members of the room when you left. - examples: - application/json: { - "chunk": [ - { - "room_id": "!636q39766251:example.com", - "$ref": "../../event-schemas/examples/m.room.member.yaml" + content: + application/json: + schema: + type: object + properties: + chunk: + type: array + items: + $ref: definitions/client_event.yaml + examples: + response: + value: { + "chunk": [ + { + "room_id": "!636q39766251:example.com", + "$ref": "../../event-schemas/examples/m.room.member.yaml" + } + ] } - ] - } - schema: - type: object - properties: - chunk: - type: array - items: - $ref: "definitions/client_event.yaml" - 403: - description: > - You aren't a member of the room and weren't previously a - member of the room. + "403": + description: | + You aren't a member of the room and weren't previously a member of the room. tags: - Room participation "/rooms/{roomId}/joined_members": get: summary: Gets the list of currently joined users and their profile data. - description: - This API returns a map of MXIDs to member info objects for members of the room. The current user must be in the room for it to work, unless it is an Application Service in which case any of the AS's users must be in the room. - This API is primarily for Application Services and should be faster to respond than `/members` as it can be implemented more efficiently on the server. + description: This API returns a map of MXIDs to member info objects for members + of the room. The current user must be in the room for it to work, unless + it is an Application Service in which case any of the AS's users must be + in the room. This API is primarily for Application Services and should + be faster to respond than `/members` as it can be implemented more + efficiently on the server. operationId: getJoinedMembersByRoom parameters: - in: path - type: string name: roomId description: The room to get the members of. required: true - x-example: "!636q39766251:example.com" + example: "!636q39766251:example.com" + schema: + type: string security: - accessToken: [] responses: - 200: - description: |- - A map of MXID to room member objects. - examples: - application/json: { - "joined": { - "@bar:example.com": { - "display_name": "Bar", - "avatar_url": "mxc://riot.ovh/printErCATzZijQsSDWorRaK" - } - } - } - schema: - 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). - description: A map from user ID to a RoomMember object. + "200": + description: A map of MXID to room member objects. + content: + application/json: + schema: type: object - 403: - description: > + 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). + description: A map from user ID to a RoomMember object. + type: object + examples: + response: + value: { + "joined": { + "@bar:example.com": { + "display_name": "Bar", + "avatar_url": "mxc://riot.ovh/printErCATzZijQsSDWorRaK" + } + } + } + "403": + description: | You aren't a member of the room. tags: - Room participation +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/search.yaml b/data/api/client-server/search.yaml index 2d45fe2a..981f93aa 100644 --- a/data/api/client-server/search.yaml +++ b/data/api/client-server/search.yaml @@ -11,44 +11,33 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server Search API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server Search API + version: 1.0.0 paths: - "/search": + /search: post: summary: Perform a server-side search. - description: |- - Performs a full text search across different categories. + description: Performs a full text search across different categories. operationId: search security: - accessToken: [] parameters: - in: query name: next_batch - type: string description: |- The point to return events from. If given, this should be a `next_batch` result from a previous call to this endpoint. - x-example: "YWxsCgpOb25lLDM1ODcwOA" - - in: body - name: body - required: true + example: YWxsCgpOb25lLDM1ODcwOA schema: - type: object - example: { + type: string + requestBody: + content: + application/json: + schema: + type: object + example: { "search_categories": { "room_events": { "keys": [ @@ -66,300 +55,323 @@ paths: } } } - properties: - search_categories: - type: object - title: "Categories" - description: Describes which categories to search in and - their criteria. - properties: - room_events: - type: object - title: Room Events Criteria - description: Mapping of category name to search criteria. - properties: - search_term: - type: string - description: The string to search events for - keys: - type: array - items: + properties: + search_categories: + type: object + title: Categories + description: Describes which categories to search in and their criteria. + properties: + room_events: + type: object + title: Room Events Criteria + description: Mapping of category name to search criteria. + properties: + search_term: type: string - enum: ["content.body", "content.name", "content.topic"] - description: The keys to search. Defaults to all. - filter: - type: object - title: Filter - description: |- - This takes a [filter](/client-server-api/#filtering). - allOf: - - $ref: "definitions/room_event_filter.yaml" - order_by: - title: "Ordering" - type: string - enum: ["recent", "rank"] - description: |- - The order in which to search for results. - By default, this is `"rank"`. - event_context: - title: Include Event Context - type: object - description: |- - Configures whether any context for the events - returned are included in the response. - properties: + description: The string to search events for + keys: + type: array + items: + type: string + enum: + - content.body + - content.name + - content.topic + description: The keys to search. Defaults to all. + filter: + type: object + title: Filter + description: This takes a [filter](/client-server-api/#filtering). + allOf: + - $ref: definitions/room_event_filter.yaml + order_by: + title: Ordering + type: string + enum: + - recent + - rank + description: |- + The order in which to search for results. + By default, this is `"rank"`. + event_context: + title: Include Event Context + type: object + description: |- + Configures whether any context for the events + returned are included in the response. + properties: before_limit: - type: integer - title: "Before limit" - description: |- - How many events before the result are - returned. By default, this is `5`. + type: integer + title: Before limit + description: |- + How many events before the result are + returned. By default, this is `5`. after_limit: - type: integer - title: "After limit" - description: |- - How many events after the result are - returned. By default, this is `5`. + type: integer + title: After limit + description: |- + How many events after the result are + returned. By default, this is `5`. include_profile: - type: boolean - title: "Return profile information" - description: |- - Requests that the server returns the - historic profile information for the users - that sent the events that were returned. - By default, this is `false`. - include_state: - type: boolean - title: Include current state - description: |- - Requests the server return the current state for - each room returned. - groupings: + type: boolean + title: Return profile information + description: |- + Requests that the server returns the + historic profile information for the users + that sent the events that were returned. + By default, this is `false`. + include_state: + type: boolean + title: Include current state + description: |- + Requests the server return the current state for + each room returned. + groupings: + type: object + title: Groupings + description: |- + Requests that the server partitions the result set + based on the provided list of keys. + properties: + group_by: + type: array + title: Groups + description: List of groups to request. + items: + type: object + title: Group + description: Configuration for group. + properties: + key: + type: string + title: Group Key + description: Key that defines the group. + enum: + - room_id + - sender + required: + - search_term + required: + - search_categories + required: true + responses: + "200": + description: Results of the search. + content: + application/json: + schema: + type: object + title: Results + required: + - search_categories + properties: + search_categories: + type: object + title: Result Categories + description: Describes which categories to search in and their criteria. + properties: + room_events: type: object - title: Groupings - description: |- - Requests that the server partitions the result set - based on the provided list of keys. + title: Result Room Events + description: Mapping of category name to search criteria. properties: - group_by: + count: + type: integer + description: An approximate count of the total number of results found. + highlights: type: array - title: Groups - description: List of groups to request. + title: Highlights + description: List of words which should be highlighted, useful for stemming + which may change the query terms. + items: + type: string + results: + type: array + title: Results + description: List of results in the requested order. items: type: object - title: Group - description: Configuration for group. + title: Result + description: The result object. properties: - key: - type: string - title: Group Key - description: |- - Key that defines the group. - enum: ["room_id", "sender"] - required: ["search_term"] - required: ["search_categories"] - responses: - 200: - description: Results of the search. - schema: - type: object - title: Results - required: ["search_categories"] - properties: - search_categories: - type: object - title: Result Categories - description: Describes which categories to search in and - their criteria. - properties: - room_events: - type: object - title: Result Room Events - description: Mapping of category name to search criteria. - properties: - count: - type: integer - description: An approximate count of the total number of results found. - highlights: - type: array - title: Highlights - description: List of words which should be highlighted, useful for stemming which may change the query terms. - items: - type: string - results: - type: array - title: Results - description: List of results in the requested order. - items: - type: object - title: Result - description: The result object. - properties: - rank: - type: number - description: A number that describes how closely - this result matches the search. Higher is - closer. - result: - type: object - title: Event - description: The event that matched. - allOf: - - "$ref": "definitions/client_event.yaml" - context: - type: object - title: Event Context - description: Context for result, if requested. - properties: - start: - type: string - title: Start Token - description: |- - Pagination token for the start of the chunk - end: - type: string - title: End Token - description: |- - Pagination token for the end of the chunk - profile_info: + rank: + type: number + description: A number that describes how closely this result matches the search. + Higher is closer. + result: type: object - title: Profile Information - description: |- - The historic profile information of the - users that sent the events returned. + title: Event + description: The event that matched. + allOf: + - $ref: definitions/client_event.yaml + context: + type: object + title: Event Context + description: Context for result, if requested. + properties: + start: + type: string + title: Start Token + description: Pagination token for the start of the chunk + end: + type: string + title: End Token + description: Pagination token for the end of the chunk + profile_info: + type: object + title: Profile Information + description: |- + The historic profile information of the + users that sent the events returned. - The `string` 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 - events_before: - type: array - title: Events Before - description: Events just before the result. - items: - title: Event - type: object - "$ref": "definitions/client_event.yaml" - events_after: - type: array - title: Events After - description: Events just after the result. - items: - title: Event - type: object - "$ref": "definitions/client_event.yaml" - state: - type: object - title: Current state - description: |- - The current state for every room in the results. - 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 - Event` array belongs to. - additionalProperties: - type: array - title: Room State - items: - "$ref": "definitions/client_event.yaml" - groups: - type: object - title: Groups - description: |- - Any groups that were requested. - - The outer `string` key is the group key requested (eg: `room_id` - or `sender`). The inner `string` key is the grouped value (eg: - a room's ID or a user's ID). - additionalProperties: - type: object - title: Group Key - description: The results for a given group. - additionalProperties: + The `string` 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 + events_before: + type: array + title: Events Before + description: Events just before the result. + items: + title: Event + type: object + $ref: definitions/client_event.yaml + events_after: + type: array + title: Events After + description: Events just after the result. + items: + title: Event + type: object + $ref: definitions/client_event.yaml + state: type: object - title: Group Value + title: Current state description: |- - The results for a particular group value. - properties: - next_batch: - type: string - title: Next Batch in Group - description: |- - Token that can be used to get the next batch - of results in the group, by passing as the - `next_batch` parameter to the next call. If - this field is absent, there are no more - results in this group. - order: - type: integer - title: Group Order - description: |- - Key that can be used to order different - groups. - results: - type: array - description: |- - Which results are in this group. - items: - type: string - title: Result Event ID - next_batch: - type: string - title: Next Batch - description: |- - Token that can be used to get the next batch of - results, by passing as the `next_batch` parameter to - the next call. If this field is absent, there are no - more results. - examples: - application/json: { - "search_categories": { - "room_events": { - "groups": { - "room_id": { - "!qPewotXpIctQySfjSy:localhost": { - "order": 1, - "next_batch": "BdgFsdfHSf-dsFD", - "results": [ - "$144429830826TWwbB:localhost" - ] + The current state for every room in the results. + 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 + Event` array belongs to. + additionalProperties: + type: array + title: Room State + items: + $ref: definitions/client_event.yaml + groups: + type: object + title: Groups + description: |- + Any groups that were requested. + + The outer `string` key is the group key requested (eg: `room_id` + or `sender`). The inner `string` key is the grouped value (eg: + a room's ID or a user's ID). + additionalProperties: + type: object + title: Group Key + description: The results for a given group. + additionalProperties: + type: object + title: Group Value + description: The results for a particular group value. + properties: + next_batch: + type: string + title: Next Batch in Group + description: |- + Token that can be used to get the next batch + of results in the group, by passing as the + `next_batch` parameter to the next call. If + this field is absent, there are no more + results in this group. + order: + type: integer + title: Group Order + description: |- + Key that can be used to order different + groups. + results: + type: array + description: Which results are in this group. + items: + type: string + title: Result Event ID + next_batch: + type: string + title: Next Batch + description: |- + Token that can be used to get the next batch of + results, by passing as the `next_batch` parameter to + the next call. If this field is absent, there are no + more results. + examples: + response: + value: { + "search_categories": { + "room_events": { + "groups": { + "room_id": { + "!qPewotXpIctQySfjSy:localhost": { + "order": 1, + "next_batch": "BdgFsdfHSf-dsFD", + "results": [ + "$144429830826TWwbB:localhost" + ] + } } - } - }, - "highlights": [ - "martians", - "men" - ], - "next_batch": "5FdgFsd234dfgsdfFD", - "count": 1224, - "results": [ - { - "rank": 0.00424866, - "result": { - "room_id": "!qPewotXpIctQySfjSy:localhost", - "event_id": "$144429830826TWwbB:localhost", - "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" + }, + "highlights": [ + "martians", + "men" + ], + "next_batch": "5FdgFsd234dfgsdfFD", + "count": 1224, + "results": [ + { + "rank": 0.00424866, + "result": { + "room_id": "!qPewotXpIctQySfjSy:localhost", + "event_id": "$144429830826TWwbB:localhost", + "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" + } } - } - ] + ] + } } } - } - 400: + "400": description: Part of the request was invalid. - 429: + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Search +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/space_hierarchy.yaml b/data/api/client-server/space_hierarchy.yaml index 9469d0c1..f7b98511 100644 --- a/data/api/client-server/space_hierarchy.yaml +++ b/data/api/client-server/space_hierarchy.yaml @@ -11,21 +11,10 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server Space Hierarchy API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v1 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server Space Hierarchy API + version: 1.0.0 paths: "/rooms/{roomId}/hierarchy": get: @@ -44,30 +33,32 @@ paths: - accessToken: [] parameters: - in: path - type: string name: roomId description: The room ID of the space to get a hierarchy for. required: true - x-example: "!space:example.org" + example: "!space:example.org" + schema: + type: string - in: query - type: boolean name: suggested_only description: |- Optional (default `false`) flag to indicate whether or not the server should only consider suggested rooms. Suggested rooms are annotated in their [`m.space.child`](#mspacechild) event contents. - x-example: true + example: true + schema: + type: boolean - in: query - type: integer name: limit description: |- Optional limit for the maximum number of rooms to include per response. Must be an integer greater than zero. Servers should apply a default value, and impose a maximum value to avoid resource exhaustion. - x-example: 20 + example: 20 + schema: + type: integer - in: query - type: integer name: max_depth description: |- Optional limit for how far to go into the space. Must be a non-negative integer. @@ -75,91 +66,117 @@ paths: When reached, no further child rooms will be returned. Servers should apply a default value, and impose a maximum value to avoid resource exhaustion. - x-example: 5 + example: 5 + schema: + type: integer - in: query - type: string name: from description: |- A pagination token from a previous result. If specified, `max_depth` and `suggested_only` cannot be changed from the first request. - x-example: "next_batch_token" - responses: - 200: - description: |- - A portion of the space tree, starting at the provided room ID. - examples: - application/json: { - "rooms": [ - { - "room_id": "!space:example.org", - "avatar_url": "mxc://example.org/abcdef", - "guest_can_join": false, - "name": "The First Space", - "topic": "No other spaces were created first, ever", - "world_readable": true, - "join_rule": "public", - "room_type": "m.space", - "num_joined_members": 42, - "canonical_alias": "#general:example.org", - "children_state": [ - { - "type": "m.space.child", - "state_key": "!a:example.org", - "content": { - "via": ["example.org"] - }, - "sender": "@alice:example.org", - "origin_server_ts": 1629413349153 - } - ] - } - ], - "next_batch": "next_batch_token" - } + example: next_batch_token schema: - type: object - properties: - rooms: - type: array - description: |- - The rooms for the current page, with the current filters. - items: - allOf: - - $ref: "definitions/public_rooms_chunk.yaml" - - type: object - title: ChildRoomsChunk - properties: - # Override x-addedInMatrixVersion for room_type (this endpoint had it first) - room_type: - type: string - description: |- - The `type` of room (from [`m.room.create`](/client-server-api/#mroomcreate)), if any. - children_state: - type: array - description: |- - The [`m.space.child`](#mspacechild) events of the space-room, represented - as [Stripped State Events](#stripped-state) with an added `origin_server_ts` key. + type: string + responses: + "200": + description: A portion of the space tree, starting at the provided room ID. + content: + application/json: + schema: + type: object + properties: + rooms: + type: array + description: The rooms for the current page, with the current filters. + items: + allOf: + - $ref: definitions/public_rooms_chunk.yaml + - type: object + title: ChildRoomsChunk + properties: + room_type: + type: string + description: The `type` of room (from + [`m.room.create`](/client-server-api/#mroomcreate)), + if any. + children_state: + type: array + description: |- + The [`m.space.child`](#mspacechild) events of the space-room, represented + as [Stripped State Events](#stripped-state) with an added `origin_server_ts` key. - If the room is not a space-room, this should be empty. - items: - allOf: - - $ref: "../../event-schemas/schema/core-event-schema/stripped_state.yaml" - - type: object - title: StrippedChildStateEvent - properties: - origin_server_ts: - type: integer - format: int64 - description: The `origin_server_ts` for the event. - required: [origin_server_ts] - required: [children_state] - next_batch: - type: string - description: |- - A token to supply to `from` to keep paginating the responses. Not present when there are - no further results. - required: [rooms] - 403: + If the room is not a space-room, this should be empty. + items: + allOf: + - $ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml + - type: object + title: StrippedChildStateEvent + properties: + origin_server_ts: + type: integer + format: int64 + description: The `origin_server_ts` for the event. + required: + - origin_server_ts + required: + - children_state + next_batch: + type: string + description: |- + A token to supply to `from` to keep paginating the responses. Not present when there are + no further results. + required: + - rooms + examples: + response: + value: { + "rooms": [ + { + "room_id": "!space:example.org", + "avatar_url": "mxc://example.org/abcdef", + "guest_can_join": false, + "name": "The First Space", + "topic": "No other spaces were created first, ever", + "world_readable": true, + "join_rule": "public", + "room_type": "m.space", + "num_joined_members": 42, + "canonical_alias": "#general:example.org", + "children_state": [ + { + "type": "m.space.child", + "state_key": "!a:example.org", + "content": { + "via": [ + "example.org" + ] + }, + "sender": "@alice:example.org", + "origin_server_ts": 1629413349153 + } + ] + } + ], + "next_batch": "next_batch_token" + } + "400": + description: |- + The request was invalid in some way. A meaningful `errcode` + and description error text will be returned. Example reasons for rejection are: + + - The `from` token is unknown to the server. + - `suggested_only` or `max_depth` changed during pagination. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_INVALID_PARAM", + "error": "suggested_only and max_depth cannot change on paginated requests" + } + "403": description: |- The user cannot view or peek on the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejection are: @@ -167,30 +184,36 @@ paths: - The room is not set up for peeking. - The user has been banned from the room. - The room does not exist. - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "You are not allowed to view this room." - } - schema: - "$ref": "definitions/errors/error.yaml" - 400: - description: |- - The request was invalid in some way. A meaningful `errcode` - and description error text will be returned. Example reasons for rejection are: - - - The `from` token is unknown to the server. - - `suggested_only` or `max_depth` changed during pagination. - examples: - application/json: { - "errcode": "M_INVALID_PARAM", - "error": "suggested_only and max_depth cannot change on paginated requests" - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "You are not allowed to view this room." + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Spaces +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v1 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/sso_login_redirect.yaml b/data/api/client-server/sso_login_redirect.yaml index 07278aaf..9f9d758b 100644 --- a/data/api/client-server/sso_login_redirect.yaml +++ b/data/api/client-server/sso_login_redirect.yaml @@ -11,17 +11,12 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server SSO Login API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 + title: Matrix Client-Server SSO Login API + version: 1.0.0 paths: - "/login/sso/redirect": + /login/sso/redirect: get: x-addedInMatrixVersion: "1.1" summary: Redirect the user's browser to the SSO interface. @@ -35,20 +30,22 @@ paths: operationId: redirectToSSO parameters: - in: query - type: string name: redirectUrl description: |- URI to which the user will be redirected after the homeserver has authenticated the user with SSO. required: true + schema: + type: string responses: - 302: + "302": description: A redirect to the SSO interface. headers: Location: - type: "string" + schema: + type: string tags: - - Session management + - Session management "/login/sso/redirect/{idpId}": get: x-addedInMatrixVersion: "1.1" @@ -63,29 +60,44 @@ paths: operationId: redirectToIdP parameters: - in: path - type: string name: idpId required: true description: |- The `id` of the IdP from the `m.login.sso` `identity_providers` array denoting the user's selection. + schema: + type: string - in: query - type: string name: redirectUrl description: |- URI to which the user will be redirected after the homeserver has authenticated the user with SSO. required: true + schema: + type: string responses: - 302: + "302": description: A redirect to the SSO interface. headers: Location: - type: "string" - 404: + schema: + type: string + "404": description: |- The IdP ID was not recognized by the server. The server is encouraged to provide a user-friendly page explaining the error given the user will be navigated to it. tags: - - Session management + - Session management +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 diff --git a/data/api/client-server/sync.yaml b/data/api/client-server/sync.yaml index 487a7019..0b22a96e 100644 --- a/data/api/client-server/sync.yaml +++ b/data/api/client-server/sync.yaml @@ -11,22 +11,12 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server sync API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https -basePath: /_matrix/client/v3 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server sync API + version: 1.0.0 paths: - "/sync": + /sync: get: summary: Synchronise the client's state and receive new messages. description: |- @@ -57,7 +47,6 @@ paths: parameters: - in: query name: filter - type: string description: |- The ID of a filter created using the filter API or a filter JSON object encoded as a string. The server will detect whether it is @@ -68,17 +57,19 @@ paths: long poll requests. See [Filtering](/client-server-api/#filtering) for more information. - x-example: "66696p746572" + example: 66696p746572 + schema: + type: string - in: query name: since - type: string description: |- A point in time to continue a sync from. This should be the `next_batch` token returned by an earlier call to this endpoint. - x-example: "s72594_4483_1934" + example: s72594_4483_1934 + schema: + type: string - in: query name: full_state - type: boolean description: |- Controls whether to include the full state for all rooms the user is a member of. @@ -93,11 +84,11 @@ paths: changed since the point indicated by `since` will be returned. By default, this is `false`. - x-example: "false" + example: "false" + schema: + type: boolean - in: query name: set_presence - type: string - enum: ["offline", "online", "unavailable"] description: |- Controls whether the client is automatically marked as online by polling this API. If this parameter is omitted then the client is @@ -105,10 +96,15 @@ paths: the parameter is set to "offline" then the client is not marked as being online when it uses this API. When set to "unavailable", the client is marked as being idle. - x-example: "offline" + example: offline + schema: + type: string + enum: + - offline + - online + - unavailable - in: query name: timeout - type: integer description: |- The maximum time to wait, in milliseconds, before returning this request. If no events (or other data) become available before this @@ -116,405 +112,436 @@ paths: By default, this is `0`, so the server will return immediately even if the response is empty. - x-example: 30000 - responses: - 200: - description: - The initial snapshot or delta for the client to use to update their - state. + example: 30000 schema: - type: object - properties: - next_batch: - type: string - description: |- - The batch token to supply in the `since` param of the next - `/sync` request. - rooms: - title: Rooms + type: integer + responses: + "200": + description: The initial snapshot or delta for the client to use to update their + state. + content: + application/json: + schema: type: object - description: |- - Updates to rooms. properties: - join: - title: Joined Rooms - type: object + next_batch: + type: string 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 + The batch token to supply in the `since` param of the next + `/sync` request. + rooms: + title: Rooms + type: object + description: Updates to rooms. + properties: + join: + title: Joined Rooms + type: object + description: |- + The rooms that the user has joined, mapped as room ID to + room information. + additionalProperties: + title: Joined Room type: object - description: |- - Information about the room which clients may need to - correctly render it to users. properties: - "m.heroes": - type: array + summary: + title: RoomSummary + type: object 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. + 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. + 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 + 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: |- - 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 + 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). + + 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 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). + 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. - 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: 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`. - 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`. + 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 + 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: - 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 + 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 - 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" - additionalProperties: - 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 + 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 + presence: + title: Presence + type: object + description: The updates to the presence status of other users. + allOf: + - $ref: definitions/event_batch.yaml + account_data: + title: Account Data + type: object + description: The global private data created by this user. + allOf: + - $ref: definitions/event_batch.yaml + to_device: + title: ToDevice 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 - knock: - title: Knocked rooms + Information on the send-to-device messages for the client + device, as defined in [Send-to-Device messaging](/client-server-api/#extensions-to-sync). + device_lists: + title: DeviceLists 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 - leave: - title: Left rooms + Information on end-to-end device updates, as specified in + [End-to-end encryption](/client-server-api/#e2e-extensions-to-sync). + device_one_time_keys_count: + title: One-time keys count 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" - presence: - title: Presence - type: object - description: |- - The updates to the presence status of other users. - allOf: - - $ref: "definitions/event_batch.yaml" - account_data: - title: Account Data - type: object - description: |- - The global private data created by this user. - allOf: - - $ref: "definitions/event_batch.yaml" - to_device: - title: ToDevice - type: object - description: |- - Information on the send-to-device messages for the client - device, as defined in [Send-to-Device messaging](/client-server-api/#extensions-to-sync). - device_lists: - title: DeviceLists - type: object - description: |- - Information on end-to-end device updates, as specified in - [End-to-end encryption](/client-server-api/#e2e-extensions-to-sync). - device_one_time_keys_count: - title: One-time keys count - type: object - additionalProperties: - type: integer - description: |- - Information on end-to-end encryption keys, as specified - in [End-to-end encryption](/client-server-api/#e2e-extensions-to-sync). - required: - - next_batch - examples: - application/json: { - "next_batch": "s72595_4483_1934", - "presence": { - "events": [ - {"$ref": "../../event-schemas/examples/m.presence.yaml"} - ] - }, - "account_data": { - "events": [ - { - "type": "org.example.custom.config", - "content": { - "custom_config_key": "custom_config_value" - } - } - ] - }, - "rooms": { - "join": { - "!726s6s6q:example.com": { - "summary": { - "m.heroes": [ - "@alice:example.com", - "@bob:example.com" - ], - "m.joined_member_count": 2, - "m.invited_member_count": 0 - }, - "state": { - "events": [ - { - "$ref": "../../event-schemas/examples/m.room.member.yaml" + type: integer + description: |- + Information on end-to-end encryption keys, as specified + in [End-to-end encryption](/client-server-api/#e2e-extensions-to-sync). + required: + - next_batch + examples: + response: + value: { + "next_batch": "s72595_4483_1934", + "presence": { + "events": [ + { + "$ref": "../../event-schemas/examples/m.presence.yaml" + } + ] + }, + "account_data": { + "events": [ + { + "type": "org.example.custom.config", + "content": { + "custom_config_key": "custom_config_value" } - ] - }, - "timeline": { - "events": [ - { - "$ref": "../../event-schemas/examples/m.room.member.yaml" + } + ] + }, + "rooms": { + "join": { + "!726s6s6q:example.com": { + "summary": { + "m.heroes": [ + "@alice:example.com", + "@bob:example.com" + ], + "m.joined_member_count": 2, + "m.invited_member_count": 0 }, - { - "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" - } - ], - "limited": true, - "prev_batch": "t34-23535_0_0" - }, - "ephemeral": { - "events": [ - {"$ref": "../../event-schemas/examples/m.typing.yaml"}, - {"$ref": "../../event-schemas/examples/m.receipt.yaml"} - ] - }, - "account_data": { - "events": [ - {"$ref": "../../event-schemas/examples/m.tag.yaml"}, - { - "type": "org.example.custom.room.config", - "content": { - "custom_config_key": "custom_config_value" + "state": { + "events": [ + { + "$ref": "../../event-schemas/examples/m.room.member.yaml" + } + ] + }, + "timeline": { + "events": [ + { + "$ref": "../../event-schemas/examples/m.room.member.yaml" + }, + { + "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" + } + ], + "limited": true, + "prev_batch": "t34-23535_0_0" + }, + "ephemeral": { + "events": [ + { + "$ref": "../../event-schemas/examples/m.typing.yaml" + }, + { + "$ref": "../../event-schemas/examples/m.receipt.yaml" + } + ] + }, + "account_data": { + "events": [ + { + "$ref": "../../event-schemas/examples/m.tag.yaml" + }, + { + "type": "org.example.custom.room.config", + "content": { + "custom_config_key": "custom_config_value" + } + } + ] + }, + "unread_notifications": { + "highlight_count": 1, + "notification_count": 5 + }, + "unread_thread_notifications": { + "$threadroot": { + "highlight_count": 3, + "notification_count": 6 } } - ] - }, - "unread_notifications": { - "highlight_count": 1, - "notification_count": 5 - }, - "unread_thread_notifications": { - "$threadroot": { - "highlight_count": 3, - "notification_count": 6 } - } - } - }, - "invite": { - "!696r7674:example.com": { - "invite_state": { - "events": [ - { - "sender": "@alice:example.com", - "type": "m.room.name", - "state_key": "", - "content": {"name": "My Room Name"} - }, - { - "sender": "@alice:example.com", - "type": "m.room.member", - "state_key": "@bob:example.com", - "content": {"membership": "invite"} + }, + "invite": { + "!696r7674:example.com": { + "invite_state": { + "events": [ + { + "sender": "@alice:example.com", + "type": "m.room.name", + "state_key": "", + "content": { + "name": "My Room Name" + } + }, + { + "sender": "@alice:example.com", + "type": "m.room.member", + "state_key": "@bob:example.com", + "content": { + "membership": "invite" + } + } + ] } - ] - } - } - }, - "knock": { - "!223asd456:example.com": { - "knock_state": { - "events": [ - { - "sender": "@alice:example.com", - "type": "m.room.name", - "state_key": "", - "content": {"name": "My Room Name"} - }, - { - "sender": "@bob:example.com", - "type": "m.room.member", - "state_key": "@bob:example.com", - "content": {"membership": "knock"} + } + }, + "knock": { + "!223asd456:example.com": { + "knock_state": { + "events": [ + { + "sender": "@alice:example.com", + "type": "m.room.name", + "state_key": "", + "content": { + "name": "My Room Name" + } + }, + { + "sender": "@bob:example.com", + "type": "m.room.member", + "state_key": "@bob:example.com", + "content": { + "membership": "knock" + } + } + ] } - ] - } + } + }, + "leave": {} } - }, - "leave": {} - } - } + } tags: - Room participation +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/tags.yaml b/data/api/client-server/tags.yaml index f04a884a..f805e02f 100644 --- a/data/api/client-server/tags.yaml +++ b/data/api/client-server/tags.yaml @@ -12,172 +12,186 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server tag API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server tag API + version: 1.0.0 paths: "/user/{userId}/rooms/{roomId}/tags": get: summary: List the tags for a room. - description: |- - List the tags set by a user on a room. + description: List the tags set by a user on a room. operationId: getRoomTags security: - accessToken: [] parameters: - in: path - type: string name: userId required: true description: |- The id of the user to get tags for. The access token must be authorized to make requests for this user ID. - x-example: "@alice:example.com" + example: "@alice:example.com" + schema: + type: string - in: path - type: string name: roomId required: true - description: |- - The ID of the room to get tags for. - x-example: "!726s6s6q:example.com" - responses: - 200: - description: - The list of tags for the user for the room. + description: The ID of the room to get tags for. + example: "!726s6s6q:example.com" schema: - type: object - properties: - tags: + type: string + responses: + "200": + description: The list of tags for the user for the room. + content: + application/json: + schema: type: object - additionalProperties: - title: Tag - type: object - properties: - order: - type: number - format: float - description: |- - A number in a range `[0,1]` describing a relative - position of the room under the given tag. - additionalProperties: true - examples: - application/json: { - "tags": { - "m.favourite": {"order": 0.1}, - "u.Work": {"order": 0.7}, - "u.Customers": {} - } - } + properties: + tags: + type: object + additionalProperties: + title: Tag + type: object + properties: + order: + type: number + format: float + description: |- + A number in a range `[0,1]` describing a relative + position of the room under the given tag. + additionalProperties: true + examples: + response: + value: { + "tags": { + "m.favourite": { + "order": 0.1 + }, + "u.Work": { + "order": 0.7 + }, + "u.Customers": {} + } + } tags: - User data "/user/{userId}/rooms/{roomId}/tags/{tag}": put: summary: Add a tag to a room. - description: |- - Add a tag to the room. + description: Add a tag to the room. operationId: setRoomTag security: - accessToken: [] parameters: - in: path - type: string name: userId required: true description: |- The id of the user to add a tag for. The access token must be authorized to make requests for this user ID. - x-example: "@alice:example.com" + example: "@alice:example.com" + schema: + type: string - in: path - type: string name: roomId required: true - description: |- - The ID of the room to add a tag to. - x-example: "!726s6s6q:example.com" + description: The ID of the room to add a tag to. + example: "!726s6s6q:example.com" + schema: + type: string - in: path - type: string name: tag required: true - description: |- - The tag to add. - x-example: "u.work" - - in: body - name: body - required: true - description: |- - Extra data for the tag, e.g. ordering. + description: The tag to add. + example: u.work schema: - type: object - properties: - order: - type: number - format: float - description: |- - A number in a range `[0,1]` describing a relative - position of the room under the given tag. - additionalProperties: true - example: { - "order": 0.25 - } + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + order: + type: number + format: float + description: |- + A number in a range `[0,1]` describing a relative + position of the room under the given tag. + additionalProperties: true + example: { + "order": 0.25 + } + description: Extra data for the tag, e.g. ordering. + required: true responses: - 200: - description: - The tag was successfully added. - schema: - type: object - examples: - application/json: {} + "200": + description: The tag was successfully added. + content: + application/json: + schema: + type: object + examples: + response: + value: {} tags: - User data delete: summary: Remove a tag from the room. - description: |- - Remove a tag from the room. + description: Remove a tag from the room. operationId: deleteRoomTag security: - accessToken: [] parameters: - in: path - type: string name: userId required: true description: |- The id of the user to remove a tag for. The access token must be authorized to make requests for this user ID. - x-example: "@alice:example.com" + example: "@alice:example.com" + schema: + type: string - in: path - type: string name: roomId required: true - description: |- - The ID of the room to remove a tag from. - x-example: "!726s6s6q:example.com" + description: The ID of the room to remove a tag from. + example: "!726s6s6q:example.com" + schema: + type: string - in: path - type: string name: tag required: true - description: |- - The tag to remove. - x-example: "u.work" - responses: - 200: - description: - The tag was successfully removed. + description: The tag to remove. + example: u.work schema: - type: object - examples: - application/json: {} + type: string + responses: + "200": + description: The tag was successfully removed. + content: + application/json: + schema: + type: object + examples: + response: + value: {} tags: - User data +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/third_party_lookup.yaml b/data/api/client-server/third_party_lookup.yaml index ba368459..de1b0b63 100644 --- a/data/api/client-server/third_party_lookup.yaml +++ b/data/api/client-server/third_party_lookup.yaml @@ -11,23 +11,12 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server Third-party Lookup API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server Third-party Lookup API + version: 1.0.0 paths: - "/thirdparty/protocols": + /thirdparty/protocols: get: summary: Retrieve metadata about all protocols that a homeserver supports. description: |- @@ -38,41 +27,48 @@ paths: security: - accessToken: [] responses: - 200: + "200": description: The protocols supported by the homeserver. - schema: - $ref: ../application-service/definitions/protocol_metadata.yaml + content: + application/json: + schema: + $ref: ../application-service/definitions/protocol_metadata.yaml tags: - Third-party Lookup "/thirdparty/protocol/{protocol}": get: summary: Retrieve metadata about a specific protocol that the homeserver supports. - description: |- - Fetches the metadata from the homeserver about a particular third-party protocol. + description: Fetches the metadata from the homeserver about a particular + third-party protocol. operationId: getProtocolMetadata security: - accessToken: [] parameters: - in: path name: protocol - type: string - description: |- - The name of the protocol. + description: The name of the protocol. required: true - x-example: "irc" + example: irc + schema: + type: string responses: - 200: + "200": description: The protocol was found and metadata returned. - schema: - $ref: ../application-service/definitions/protocol.yaml - 404: + content: + application/json: + schema: + $ref: ../application-service/definitions/protocol.yaml + "404": description: The protocol is unknown. - examples: - application/json: { - "errcode": "M_NOT_FOUND" - } - schema: - $ref: definitions/errors/error.yaml + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND" + } tags: - Third-party Lookup "/thirdparty/location/{protocol}": @@ -93,29 +89,36 @@ paths: parameters: - in: path name: protocol - type: string description: The protocol used to communicate to the third-party network. required: true - x-example: irc + example: irc + schema: + type: string - in: query name: searchFields - type: string description: |- One or more custom fields to help identify the third-party location. + schema: + type: string responses: - 200: + "200": description: At least one portal room was found. - schema: - $ref: ../application-service/definitions/location_batch.yaml - 404: + content: + application/json: + schema: + $ref: ../application-service/definitions/location_batch.yaml + "404": description: No portal rooms were found. - examples: - application/json: { - "errcode": "M_NOT_FOUND" - } - schema: - $ref: definitions/errors/error.yaml + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND" + } tags: - Third-party Lookup "/thirdparty/user/{protocol}": @@ -130,32 +133,38 @@ paths: parameters: - in: path name: protocol - type: string - description: |- - The name of the protocol. + description: The name of the protocol. required: true - x-example: irc + example: irc + schema: + type: string - in: query name: fields... - type: string - description: |- - One or more custom fields that are passed to the AS to help identify the user. + description: One or more custom fields that are passed to the AS to help + identify the user. + schema: + type: string responses: - 200: + "200": description: The Matrix User IDs found with the given parameters. - schema: - $ref: ../application-service/definitions/user_batch.yaml - 404: + content: + application/json: + schema: + $ref: ../application-service/definitions/user_batch.yaml + "404": description: The Matrix User ID was not found - examples: - application/json: { - "errcode": "M_NOT_FOUND" - } - schema: - $ref: definitions/errors/error.yaml + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND" + } tags: - Third-party Lookup - "/thirdparty/location": + /thirdparty/location: get: summary: Reverse-lookup third-party locations given a Matrix room alias. description: |- @@ -167,54 +176,78 @@ paths: parameters: - in: query name: alias - type: string description: The Matrix room alias to look up. required: true - x-example: "#matrix:matrix.org" + example: "#matrix:matrix.org" + schema: + type: string responses: - 200: - description: |- - All found third-party locations. - schema: - $ref: ../application-service/definitions/location_batch.yaml - 404: + "200": + description: All found third-party locations. + content: + application/json: + schema: + $ref: ../application-service/definitions/location_batch.yaml + "404": description: The Matrix room alias was not found - examples: - application/json: { - "errcode": "M_NOT_FOUND" - } - schema: - $ref: definitions/errors/error.yaml + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND" + } tags: - Third-party Lookup - "/thirdparty/user": + /thirdparty/user: get: summary: Reverse-lookup third-party users given a Matrix User ID. - description: |- - Retrieve an array of third-party users from a Matrix User ID. + description: Retrieve an array of third-party users from a Matrix User ID. operationId: queryUserByID security: - accessToken: [] parameters: - in: query name: userid - type: string description: The Matrix User ID to look up. required: true - x-example: "@bob:matrix.org" + example: "@bob:matrix.org" + schema: + type: string responses: - 200: - description: |- - An array of third-party users. - schema: - $ref: ../application-service/definitions/user_batch.yaml - 404: + "200": + description: An array of third-party users. + content: + application/json: + schema: + $ref: ../application-service/definitions/user_batch.yaml + "404": description: The Matrix User ID was not found - examples: - application/json: { - "errcode": "M_NOT_FOUND" - } - schema: - $ref: definitions/errors/error.yaml + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND" + } tags: - Third-party Lookup +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/third_party_membership.yaml b/data/api/client-server/third_party_membership.yaml index c6ce230e..7105ac84 100644 --- a/data/api/client-server/third_party_membership.yaml +++ b/data/api/client-server/third_party_membership.yaml @@ -11,21 +11,10 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server Room Membership API for third-party identifiers" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server Room Membership API for third-party identifiers + version: 1.0.0 paths: "/rooms/{roomId}/invite": post: @@ -71,56 +60,64 @@ paths: If a token is requested from the identity server, the homeserver will append a `m.room.third_party_invite` event to the room. - operationId: inviteBy3PID security: - accessToken: [] parameters: - in: path - type: string name: roomId description: The room identifier (not alias) to which to invite the user. required: true - x-example: "!d41d8cd:matrix.org" - - in: body - name: body - required: true + example: "!d41d8cd:matrix.org" schema: - type: object - example: { + type: string + requestBody: + content: + application/json: + schema: + type: object + example: { "id_server": "matrix.org", "id_access_token": "abc123_OpaqueString", "medium": "email", "address": "cheeky@monkey.com" } - properties: - id_server: - type: string - description: The hostname+port of the identity server which should be used for third-party identifier lookups. - id_access_token: - type: string - description: |- - An access token previously registered with the identity server. Servers - can treat this as optional to distinguish between r0.5-compatible clients - and this specification version. - medium: - type: string - description: |- - The kind of address being passed in the address field, for example - `email` (see [the list of recognised values](/appendices/#3pid-types)). - address: - type: string - description: The invitee's third-party identifier. - required: ["id_server", "id_access_token", "medium", "address"] + properties: + id_server: + type: string + description: The hostname+port of the identity server which should be used for + third-party identifier lookups. + id_access_token: + type: string + description: |- + An access token previously registered with the identity server. Servers + can treat this as optional to distinguish between r0.5-compatible clients + and this specification version. + medium: + type: string + description: |- + The kind of address being passed in the address field, for example + `email` (see [the list of recognised values](/appendices/#3pid-types)). + address: + type: string + description: The invitee's third-party identifier. + required: + - id_server + - id_access_token + - medium + - address + required: true responses: - 200: + "200": description: The user has been invited to join the room. - examples: - application/json: { - } - schema: - type: object - 403: + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "403": description: |- You do not have permission to invite the user to the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are: @@ -128,14 +125,36 @@ paths: - The invitee is already a member of the room. - The inviter is not currently in the room. - The inviter's power level is insufficient to invite users to the room. - examples: - application/json: { - "errcode": "M_FORBIDDEN", "error": "@cheeky_monkey:matrix.org is banned from the room"} - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "@cheeky_monkey:matrix.org is banned from the room" + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Room membership +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/threads_list.yaml b/data/api/client-server/threads_list.yaml index a118d694..8724b58d 100644 --- a/data/api/client-server/threads_list.yaml +++ b/data/api/client-server/threads_list.yaml @@ -11,21 +11,10 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server Threads List API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v1 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server Threads List API + version: 1.0.0 paths: "/rooms/{roomId}/threads": get: @@ -33,7 +22,7 @@ paths: summary: Fetches a list of the threads in a room. description: |- This API is used to paginate through the list of the thread roots in a given room. - + Optionally, the returned list may be filtered according to whether the requesting user has participated in the thread. operationId: getThreadRoots @@ -41,67 +30,97 @@ paths: - accessToken: [] parameters: - in: path - type: string name: roomId description: The room ID where the thread roots are located. required: true - x-example: "!room:example.org" + example: "!room:example.org" + schema: + type: string - in: query - type: string name: include - enum: [all, participated] description: |- Optional (default `all`) flag to denote which thread roots are of interest to the caller. When `all`, all thread roots found in the room are returned. When `participated`, only thread roots for threads the user has [participated in](/client-server-api/#server-side-aggregation-of-mthread-relationships) will be returned. - x-example: "all" + example: all + schema: + type: string + enum: + - all + - participated - in: query - type: integer name: limit description: |- Optional limit for the maximum number of thread roots to include per response. Must be an integer greater than zero. Servers should apply a default value, and impose a maximum value to avoid resource exhaustion. - x-example: 20 + example: 20 + schema: + type: integer - in: query - type: string name: from description: |- A pagination token from a previous result. When not provided, the server starts paginating from the most recent event visible to the user (as per history visibility rules; topologically). - x-example: "next_batch_token" - responses: - 200: - description: |- - A portion of the available thread roots in the room, based on the filter criteria. - examples: - application/json: { - "chunk": [{ "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" }], - "next_batch": "next_batch_token" - } + example: next_batch_token schema: - type: object - properties: - chunk: - type: array - description: |- - The thread roots, ordered by the `latest_event` in each event's aggregated children. All events - returned include bundled [aggregations](/client-server-api/#aggregations-of-child-events). + type: string + responses: + "200": + description: A portion of the available thread roots in the room, based on the + filter criteria. + content: + application/json: + schema: + type: object + properties: + chunk: + type: array + description: |- + The thread roots, ordered by the `latest_event` in each event's aggregated children. All events + returned include bundled [aggregations](/client-server-api/#aggregations-of-child-events). - If the thread root event was sent by an [ignored user](/client-server-api/#ignoring-users), the - event is returned redacted to the caller. This is to simulate the same behaviour of a client doing - aggregation locally on the thread. - items: - $ref: "definitions/client_event.yaml" - next_batch: - type: string - description: |- - A token to supply to `from` to keep paginating the responses. Not present when there are - no further results. - required: [chunk] - 403: + If the thread root event was sent by an [ignored user](/client-server-api/#ignoring-users), the + event is returned redacted to the caller. This is to simulate the same behaviour of a client doing + aggregation locally on the thread. + items: + $ref: definitions/client_event.yaml + next_batch: + type: string + description: |- + A token to supply to `from` to keep paginating the responses. Not present when there are + no further results. + required: + - chunk + examples: + response: + value: { + "chunk": [ + { + "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" + } + ], + "next_batch": "next_batch_token" + } + "400": + description: |- + The request was invalid in some way. A meaningful `errcode` + and description error text will be returned. Example reasons for rejection are: + + - The `from` token is unknown to the server. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_INVALID_PARAM", + "error": "Unknown pagination token" + } + "403": description: |- The user cannot view or peek on the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejection are: @@ -109,29 +128,36 @@ paths: - The room is not set up for peeking. - The user has been banned from the room. - The room does not exist. - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "You are not allowed to view this room." - } - schema: - "$ref": "definitions/errors/error.yaml" - 400: - description: |- - The request was invalid in some way. A meaningful `errcode` - and description error text will be returned. Example reasons for rejection are: - - - The `from` token is unknown to the server. - examples: - application/json: { - "errcode": "M_INVALID_PARAM", - "error": "Unknown pagination token" - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "You are not allowed to view this room." + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Threads +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v1 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/to_device.yaml b/data/api/client-server/to_device.yaml index 266593e1..d8832fa3 100644 --- a/data/api/client-server/to_device.yaml +++ b/data/api/client-server/to_device.yaml @@ -11,22 +11,10 @@ # 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. - -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server Send-to-device API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server Send-to-device API + version: 1.0.0 paths: "/sendToDevice/{eventType}/{txnId}": put: @@ -39,54 +27,72 @@ paths: - accessToken: [] parameters: - in: path - type: string name: eventType description: The type of event to send. required: true - x-example: "m.new_device" + example: m.new_device + schema: + type: string - in: path name: txnId - type: string description: |- The [transaction ID](/client-server-api/#transaction-identifiers) for this event. Clients should generate an ID unique across requests with the same access token; it will be used by the server to ensure idempotency of requests. required: true - x-example: "35" - - in: body - name: body - required: true + example: "35" schema: - type: object - title: body - properties: - messages: - type: object - description: |- - 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: string + requestBody: + content: + application/json: + schema: + type: object + title: body + properties: + messages: type: object + description: |- + 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 - title: EventContent - description: Message content - example: { - "@alice:example.com": { - "TLLBEANAAG": { - "example_content_key": "value" - } - } - } - required: ["messages"] + additionalProperties: + type: object + title: EventContent + description: Message content + example: + "@alice:example.com": + TLLBEANAAG: + example_content_key: value + required: + - messages + required: true responses: - 200: - description: - The message was successfully sent. - examples: - application/json: {} - schema: - type: object + "200": + description: The message was successfully sent. + content: + application/json: + schema: + type: object + examples: + response: + value: {} tags: - Send-to-Device messaging +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/typing.yaml b/data/api/client-server/typing.yaml index 65a1225d..6d6a7437 100644 --- a/data/api/client-server/typing.yaml +++ b/data/api/client-server/typing.yaml @@ -11,21 +11,10 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server Typing API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server Typing API + version: 1.0.0 paths: "/rooms/{roomId}/typing/{userId}": put: @@ -40,48 +29,71 @@ paths: - accessToken: [] parameters: - in: path - type: string name: userId description: The user who has started to type. required: true - x-example: "@alice:example.com" + example: "@alice:example.com" + schema: + type: string - in: path - type: string name: roomId description: The room in which the user is typing. required: true - x-example: "!wefh3sfukhs:example.com" - - in: body - name: typingState - description: The current typing state. - required: true + example: "!wefh3sfukhs:example.com" schema: - type: object - example: { + type: string + requestBody: + content: + application/json: + schema: + type: object + example: { "typing": true, "timeout": 30000 } - properties: - typing: - type: boolean - description: |- - Whether the user is typing or not. If `false`, the `timeout` - key can be omitted. - timeout: - type: integer - description: The length of time in milliseconds to mark this user as typing. - required: ["typing"] + properties: + typing: + type: boolean + description: |- + Whether the user is typing or not. If `false`, the `timeout` + key can be omitted. + timeout: + type: integer + description: The length of time in milliseconds to mark this user as typing. + required: + - typing + description: The current typing state. + required: true responses: - 200: + "200": description: The new typing state was set. - examples: - application/json: { - } - schema: - type: object # empty json object - 429: + content: + application/json: + schema: + type: object # empty json object + examples: + response: + value: {} + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Room participation +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/users.yaml b/data/api/client-server/users.yaml index ca39e5fe..67854f08 100644 --- a/data/api/client-server/users.yaml +++ b/data/api/client-server/users.yaml @@ -11,23 +11,12 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server User Directory API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server User Directory API + version: 1.0.0 paths: - "/user_directory/search": + /user_directory/search: post: summary: Searches the user directory. description: |- @@ -44,67 +33,93 @@ paths: operationId: searchUserDirectory security: - accessToken: [] - parameters: - - in: body - name: body - required: true - schema: - type: object - properties: - search_term: - type: string - description: The term to search for - example: "foo" - limit: - type: integer - description: The maximum number of results to return. Defaults to 10. - example: 10 - required: ["search_term"] + requestBody: + content: + application/json: + schema: + type: object + properties: + search_term: + type: string + description: The term to search for + example: foo + limit: + type: integer + description: The maximum number of results to return. Defaults to 10. + example: 10 + required: + - search_term + required: true responses: - 200: + "200": description: The results of the search. - examples: - application/json: { - "results": [ - { - "user_id": "@foo:bar.com", - "display_name": "Foo", - "avatar_url": "mxc://bar.com/foo" - } - ], - "limited": false - } - schema: - type: object - required: ["results", "limited"] - properties: - results: - type: array - description: Ordered by rank and then whether or not profile info is available. - items: - title: User - type: object - required: ["user_id"] - properties: - user_id: - type: string - example: "@foo:bar.com" - description: The user's matrix user ID. - display_name: - type: string - example: "Foo" - description: The display name of the user, if one exists. - avatar_url: - type: string - format: uri - example: "mxc://bar.com/foo" - description: The avatar url, as an [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris), if one exists. - limited: - type: boolean - description: Indicates if the result list has been truncated by the limit. - 429: + content: + application/json: + schema: + type: object + required: + - results + - limited + properties: + results: + type: array + description: Ordered by rank and then whether or not profile info is available. + items: + title: User + type: object + required: + - user_id + properties: + user_id: + type: string + example: "@foo:bar.com" + description: The user's matrix user ID. + display_name: + type: string + example: Foo + description: The display name of the user, if one exists. + avatar_url: + type: string + format: uri + example: mxc://bar.com/foo + description: The avatar url, as an [`mxc://` + URI](/client-server-api/#matrix-content-mxc-uris), + if one exists. + limited: + type: boolean + description: Indicates if the result list has been truncated by the limit. + examples: + response: + value: { + "results": [ + { + "user_id": "@foo:bar.com", + "display_name": "Foo", + "avatar_url": "mxc://bar.com/foo" + } + ], + "limited": false + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - User directory +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/versions.yaml b/data/api/client-server/versions.yaml index 58c1fbe0..14785e53 100644 --- a/data/api/client-server/versions.yaml +++ b/data/api/client-server/versions.yaml @@ -11,19 +11,12 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server Versions API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client -produces: - - application/json + title: Matrix Client-Server Versions API + version: 1.0.0 paths: - "/versions": + /versions: get: summary: Gets the versions of the specification supported by the server. description: |- @@ -47,33 +40,52 @@ paths: features in their stable releases. operationId: getVersions responses: - 200: + "200": description: The versions supported by the server. - examples: - application/json: { - "versions": ["r0.0.1", "v1.1"], - "unstable_features": { - "org.example.my_feature": true - } - } - schema: - type: object - properties: - versions: - type: array - description: The supported versions. - items: - type: string - description: The supported versions - unstable_features: + content: + application/json: + schema: type: object - description: |- - Experimental features the server supports. Features not listed here, - or the lack of this property all together, indicate that a feature is - not supported. - additionalProperties: - type: boolean - description: Whether or not the namespaced feature is supported. - required: ['versions'] + properties: + versions: + type: array + description: The supported versions. + items: + type: string + description: The supported versions + unstable_features: + type: object + description: |- + Experimental features the server supports. Features not listed here, + or the lack of this property all together, indicate that a feature is + not supported. + additionalProperties: + type: boolean + description: Whether or not the namespaced feature is supported. + required: + - versions + examples: + response: + value: { + "versions": [ + "r0.0.1", + "v1.1" + ], + "unstable_features": { + "org.example.my_feature": true + } + } tags: - Server administration +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client diff --git a/data/api/client-server/voip.yaml b/data/api/client-server/voip.yaml index 6c0d1816..ea9146ec 100644 --- a/data/api/client-server/voip.yaml +++ b/data/api/client-server/voip.yaml @@ -11,23 +11,12 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server Voice over IP API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server Voice over IP API + version: 1.0.0 paths: - "/voip/turnServer": + /voip/turnServer: get: summary: Obtain TURN server credentials. description: |- @@ -37,42 +26,64 @@ paths: security: - accessToken: [] responses: - 200: + "200": description: The TURN server credentials. - examples: - application/json: { - "username":"1443779631:@user:example.com", - "password":"JlKfBy1QwLrO20385QyAtEyIv0=", - "uris":[ - "turn:turn.example.com:3478?transport=udp", - "turn:10.20.30.40:3478?transport=tcp", - "turns:10.20.30.40:443?transport=tcp" - ], - "ttl":86400 - } - schema: - type: object - properties: - username: - type: string - description: |- - The username to use. - password: - type: string - description: |- - The password to use. - uris: - type: array - items: - type: string - description: A list of TURN URIs - ttl: - type: integer - description: The time-to-live in seconds - required: ["username", "password", "uris", "ttl"] - 429: + content: + application/json: + schema: + type: object + properties: + username: + type: string + description: The username to use. + password: + type: string + description: The password to use. + uris: + type: array + items: + type: string + description: A list of TURN URIs + ttl: + type: integer + description: The time-to-live in seconds + required: + - username + - password + - uris + - ttl + examples: + response: + value: { + "username": "1443779631:@user:example.com", + "password": "JlKfBy1QwLrO20385QyAtEyIv0=", + "uris": [ + "turn:turn.example.com:3478?transport=udp", + "turn:10.20.30.40:3478?transport=tcp", + "turns:10.20.30.40:443?transport=tcp" + ], + "ttl": 86400 + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - VOIP +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/wellknown.yaml b/data/api/client-server/wellknown.yaml index 9fff7ea7..72de3598 100644 --- a/data/api/client-server/wellknown.yaml +++ b/data/api/client-server/wellknown.yaml @@ -11,18 +11,12 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server Server Discovery API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https -basePath: /.well-known -produces: - - application/json + title: Matrix Client-Server Server Discovery API + version: 1.0.0 paths: - "/matrix/client": + /matrix/client: get: summary: Gets Matrix server discovery information about the domain. description: |- @@ -36,11 +30,25 @@ paths: but by another webserver, to be used for discovering the homeserver URL. operationId: getWellknown responses: - 200: + "200": description: Server discovery information. - schema: - "$ref": "definitions/wellknown/full.yaml" - 404: + content: + application/json: + schema: + $ref: definitions/wellknown/full.yaml + "404": description: No server discovery information available. tags: - Server administration +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /.well-known diff --git a/data/api/client-server/whoami.yaml b/data/api/client-server/whoami.yaml index 727f7e64..342cbeb7 100644 --- a/data/api/client-server/whoami.yaml +++ b/data/api/client-server/whoami.yaml @@ -11,21 +11,12 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Client-Server Account Identification API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server Account Identification API + version: 1.0.0 paths: - "/account/whoami": + /account/whoami: get: summary: Gets information about the owner of an access token. description: |- @@ -40,61 +31,85 @@ paths: operationId: getTokenOwner security: - accessToken: [] - parameters: [] responses: - 200: - description: - The token belongs to a known user. - examples: - application/json: { - "user_id": "@joe:example.org", - "device_id": "ABC1234" - } - schema: - type: object - required: ["user_id"] - properties: - user_id: - type: string - description: The user ID that owns the access token. - device_id: - x-addedInMatrixVersion: "1.1" - type: string - description: |- - Device ID associated with the access token. If no device - is associated with the access token (such as in the case - of application services) then this field can be omitted. - Otherwise this is required. - is_guest: - x-addedInMatrixVersion: "1.2" - type: boolean - description: |- - When `true`, the user is a [Guest User](#guest-access). When - not present or `false`, the user is presumed to be a non-guest - user. - 401: - description: - The token is not recognised - examples: - application/json: { - "errcode": "M_UNKNOWN_TOKEN", - "error": "Unrecognised access token." - } - schema: - "$ref": "definitions/errors/error.yaml" - 403: - description: - The appservice cannot masquerade as the user or has not registered them. - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "Application service has not registered this user." - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + "200": + description: The token belongs to a known user. + content: + application/json: + schema: + type: object + required: + - user_id + properties: + user_id: + type: string + description: The user ID that owns the access token. + device_id: + x-addedInMatrixVersion: "1.1" + type: string + description: |- + Device ID associated with the access token. If no device + is associated with the access token (such as in the case + of application services) then this field can be omitted. + Otherwise this is required. + is_guest: + x-addedInMatrixVersion: "1.2" + type: boolean + description: |- + When `true`, the user is a [Guest User](#guest-access). When + not present or `false`, the user is presumed to be a non-guest + user. + examples: + response: + value: { + "user_id": "@joe:example.org", + "device_id": "ABC1234" + } + "401": + description: The token is not recognised + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_UNKNOWN_TOKEN", + "error": "Unrecognised access token." + } + "403": + description: The appservice cannot masquerade as the user or has not registered + them. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "Application service has not registered this user." + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Session management +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/identity/v2_associations.yaml b/data/api/identity/v2_associations.yaml index 4a83a34f..8ed4041a 100644 --- a/data/api/identity/v2_associations.yaml +++ b/data/api/identity/v2_associations.yaml @@ -12,102 +12,108 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Identity Service Establishing Associations API" - version: "2.0.0" -host: localhost:8090 -schemes: - - https -basePath: /_matrix/identity/v2 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Identity Service Establishing Associations API + version: 2.0.0 paths: - "/3pid/getValidated3pid": + /3pid/getValidated3pid: get: summary: Check whether ownership of a 3pid was validated. - description: |- - Determines if a given 3pid has been validated by a user. + description: Determines if a given 3pid has been validated by a user. operationId: getValidated3pidV2 security: - accessToken: [] parameters: - in: query - type: string name: sid description: The Session ID generated by the `requestToken` call. required: true - x-example: 1234 + example: 1234 + schema: + type: string - in: query - type: string name: client_secret description: The client secret passed to the `requestToken` call. required: true - x-example: monkeys_are_GREAT - responses: - 200: - description: Validation information for the session. - examples: - application/json: { - "medium": "email", - "validated_at": 1457622739026, - "address": "louise@bobs.burgers" - } + example: monkeys_are_GREAT schema: - type: object - properties: - medium: - type: string - description: The medium type of the 3pid. - address: - type: string - description: The address of the 3pid being looked up. - validated_at: - type: integer - format: int64 - description: |- - Timestamp, in milliseconds, indicating the time that the 3pid - was validated. - required: ['medium', 'address', 'validated_at'] - 400: + type: string + responses: + "200": + description: Validation information for the session. + content: + application/json: + schema: + type: object + properties: + medium: + type: string + description: The medium type of the 3pid. + address: + type: string + description: The address of the 3pid being looked up. + validated_at: + type: integer + format: int64 + description: |- + Timestamp, in milliseconds, indicating the time that the 3pid + was validated. + required: + - medium + - address + - validated_at + examples: + response: + value: { + "medium": "email", + "validated_at": 1457622739026, + "address": "louise@bobs.burgers" + } + "400": description: |- The session has not been validated. If the session has not been validated, then `errcode` will be `M_SESSION_NOT_VALIDATED`. If the session has timed out, then `errcode` will be `M_SESSION_EXPIRED`. - examples: - application/json: { - "errcode": "M_SESSION_NOT_VALIDATED", - "error": "This validation session has not yet been completed" - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" - 404: - description: The Session ID or client secret were not found. - examples: - application/json: { - "errcode": "M_NO_VALID_SESSION", - "error": "No valid session was found matching that sid and client secret" - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" - 403: + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_SESSION_NOT_VALIDATED", + "error": "This validation session has not yet been completed" + } + "403": description: | The user must do something in order to use this endpoint. One example is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service). - examples: - application/json: { - "errcode": "M_TERMS_NOT_SIGNED", - "error": "Please accept our updated terms of service before continuing" - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" - "/3pid/bind": + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_TERMS_NOT_SIGNED", + "error": "Please accept our updated terms of service before continuing" + } + "404": + description: The Session ID or client secret were not found. + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NO_VALID_SESSION", + "error": "No valid session was found matching that sid and client secret" + } + /3pid/bind: post: summary: Publish an association between a session and a Matrix user ID. description: |- @@ -123,119 +129,136 @@ paths: operationId: bindV2 security: - accessToken: [] - parameters: - - in: body - name: body - schema: - type: object - example: { - "sid": "1234", - "client_secret": "monkeys_are_GREAT", - "mxid": "@ears:matrix.org" - } - properties: - sid: - type: string - description: The Session ID generated by the `requestToken` call. - client_secret: - type: string - description: The client secret passed to the `requestToken` call. - mxid: - type: string - description: The Matrix user ID to associate with the 3pids. - required: ["sid", "client_secret", "mxid"] - responses: - 200: - description: The association was published. - examples: - application/json: { - "address": "louise@bobs.burgers", - "medium": "email", - "mxid": "@ears:matrix.org", - "not_before": 1428825849161, - "not_after": 4582425849161, - "ts": 1428825849161, - "signatures": { - "matrix.org": { - "ed25519:0": "ENiU2YORYUJgE6WBMitU0mppbQjidDLanAusj8XS2nVRHPu+0t42OKA/r6zV6i2MzUbNQ3c3MiLScJuSsOiVDQ" - } + requestBody: + content: + application/json: + schema: + type: object + example: { + "sid": "1234", + "client_secret": "monkeys_are_GREAT", + "mxid": "@ears:matrix.org" } - } - schema: - type: object - properties: - address: - type: string - description: The 3pid address of the user being looked up. - medium: - type: string - description: The medium type of the 3pid. - mxid: - type: string - description: The Matrix user ID associated with the 3pid. - not_before: - type: integer - format: int64 - description: A unix timestamp before which the association is not known to be valid. - not_after: - type: integer - format: int64 - description: A unix timestamp after which the association is not known to be valid. - ts: - type: integer - format: int64 - description: The unix timestamp at which the association was verified. - signatures: + properties: + sid: + type: string + description: The Session ID generated by the `requestToken` call. + client_secret: + type: string + description: The client secret passed to the `requestToken` call. + mxid: + type: string + description: The Matrix user ID to associate with the 3pids. + required: + - sid + - client_secret + - mxid + responses: + "200": + description: The association was published. + content: + application/json: + schema: type: object - description: |- - The signatures of the verifying identity servers which show that the - association should be trusted, if you trust the verifying identity - services. - allOf: - - $ref: "../../schemas/server-signatures.yaml" - required: - - address - - medium - - mxid - - not_before - - not_after - - ts - - signatures - 400: + properties: + address: + type: string + description: The 3pid address of the user being looked up. + medium: + type: string + description: The medium type of the 3pid. + mxid: + type: string + description: The Matrix user ID associated with the 3pid. + not_before: + type: integer + format: int64 + description: A unix timestamp before which the association is not known to be + valid. + not_after: + type: integer + format: int64 + description: A unix timestamp after which the association is not known to be + valid. + ts: + type: integer + format: int64 + description: The unix timestamp at which the association was verified. + signatures: + type: object + description: |- + The signatures of the verifying identity servers which show that the + association should be trusted, if you trust the verifying identity + services. + allOf: + - $ref: ../../schemas/server-signatures.yaml + required: + - address + - medium + - mxid + - not_before + - not_after + - ts + - signatures + examples: + response: + value: { + "address": "louise@bobs.burgers", + "medium": "email", + "mxid": "@ears:matrix.org", + "not_before": 1428825849161, + "not_after": 4582425849161, + "ts": 1428825849161, + "signatures": { + "matrix.org": { + "ed25519:0": "ENiU2YORYUJgE6WBMitU0mppbQjidDLanAusj8XS2nVRHPu+0t42OKA/r6zV6i2MzUbNQ3c3MiLScJuSsOiVDQ" + } + } + } + "400": description: |- The association was not published. If the session has not been validated, then `errcode` will be `M_SESSION_NOT_VALIDATED`. If the session has timed out, then `errcode` will be `M_SESSION_EXPIRED`. - examples: - application/json: { - "errcode": "M_SESSION_NOT_VALIDATED", - "error": "This validation session has not yet been completed" - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" - 404: - description: The Session ID or client secret were not found - examples: - application/json: { - "errcode": "M_NO_VALID_SESSION", - "error": "No valid session was found matching that sid and client secret" - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" - 403: + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_SESSION_NOT_VALIDATED", + "error": "This validation session has not yet been completed" + } + "403": description: | The user must do something in order to use this endpoint. One example is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service). - examples: - application/json: { - "errcode": "M_TERMS_NOT_SIGNED", - "error": "Please accept our updated terms of service before continuing" - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" - "/3pid/unbind": + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_TERMS_NOT_SIGNED", + "error": "Please accept our updated terms of service before continuing" + } + "404": + description: The Session ID or client secret were not found + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NO_VALID_SESSION", + "error": "No valid session was found matching that sid and client secret" + } + /3pid/unbind: post: summary: Remove an association between a session and a Matrix user ID. description: |- @@ -257,65 +280,67 @@ paths: operationId: unbindV2 security: - accessToken: [] - parameters: - - in: body - name: body - schema: - type: object - example: { - "sid": "1234", - "client_secret": "monkeys_are_GREAT", - "mxid": "@ears:example.org", - "threepid": { - "medium": "email", - "address": "monkeys_have_ears@example.org" + requestBody: + content: + application/json: + schema: + type: object + example: { + "sid": "1234", + "client_secret": "monkeys_are_GREAT", + "mxid": "@ears:example.org", + "threepid": { + "medium": "email", + "address": "monkeys_have_ears@example.org" + } } - } - properties: - sid: - type: string - description: The Session ID generated by the `requestToken` call. - client_secret: - type: string - description: The client secret passed to the `requestToken` call. - mxid: - type: string - description: The Matrix user ID to remove from the 3pids. - threepid: - type: object - title: 3PID - description: |- - The 3PID to remove. Must match the 3PID used to generate the session - if using `sid` and `client_secret` to authenticate this request. - properties: - medium: - type: string - description: |- - A medium from the [3PID Types](/appendices/#3pid-types) Appendix, matching the medium - of the identifier to unbind. - address: - type: string - description: The 3PID address to remove. - required: ['medium', 'address'] - required: ["threepid", "mxid"] + properties: + sid: + type: string + description: The Session ID generated by the `requestToken` call. + client_secret: + type: string + description: The client secret passed to the `requestToken` call. + mxid: + type: string + description: The Matrix user ID to remove from the 3pids. + threepid: + type: object + title: 3PID + description: |- + The 3PID to remove. Must match the 3PID used to generate the session + if using `sid` and `client_secret` to authenticate this request. + properties: + medium: + type: string + description: |- + A medium from the [3PID Types](/appendices/#3pid-types) Appendix, matching the medium + of the identifier to unbind. + address: + type: string + description: The 3PID address to remove. + required: + - medium + - address + required: + - threepid + - mxid responses: - 200: + "200": description: The association was successfully removed. - examples: - application/json: {} - schema: - type: object - 400: + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "400": description: |- If the response body is not a JSON Matrix error, the identity server does not support unbinds. If a JSON Matrix error is in the response body, the requesting party should respect the error. - 404: - description: |- - If the response body is not a JSON Matrix error, the identity server - does not support unbinds. If a JSON Matrix error is in the response - body, the requesting party should respect the error. - 403: + "403": description: |- The credentials supplied to authenticate the request were invalid. This may also be returned if the identity server does not support @@ -324,15 +349,38 @@ paths: Another common error code is `M_TERMS_NOT_SIGNED` where the user needs to [agree to more terms](/identity-service-api/#terms-of-service) in order to continue. - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "Invalid homeserver signature" - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" - 501: + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "Invalid homeserver signature" + } + "404": description: |- If the response body is not a JSON Matrix error, the identity server does not support unbinds. If a JSON Matrix error is in the response body, the requesting party should respect the error. + "501": + description: |- + If the response body is not a JSON Matrix error, the identity server + does not support unbinds. If a JSON Matrix error is in the response + body, the requesting party should respect the error. +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8090 + basePath: + default: /_matrix/identity/v2 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/identity/v2_auth.yaml b/data/api/identity/v2_auth.yaml index b5d1a41c..64433f81 100644 --- a/data/api/identity/v2_auth.yaml +++ b/data/api/identity/v2_auth.yaml @@ -11,22 +11,12 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Identity Service Authentication API" - version: "2.0.0" -host: localhost:8090 -schemes: - - https -basePath: /_matrix/identity/v2 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Identity Service Authentication API + version: 2.0.0 paths: - "/account/register": + /account/register: post: summary: Exchanges an OpenID token for an access token. description: |- @@ -34,64 +24,74 @@ paths: access the identity server. The request body is the same as the values returned by `/openid/request_token` in the Client-Server API. operationId: registerAccount - parameters: - - in: body - name: body - schema: - $ref: "../client-server/definitions/openid_token.yaml" + requestBody: + content: + application/json: + schema: + $ref: ../client-server/definitions/openid_token.yaml responses: - 200: + "200": description: |- A token which can be used to authenticate future requests to the identity server. - examples: - application/json: { - "token": "abc123_OpaqueString" - } - schema: - type: object - properties: - token: - type: string - description: |- - An opaque string representing the token to authenticate future - requests to the identity server with. - required: ['token'] - "/account": + content: + application/json: + schema: + type: object + properties: + token: + type: string + description: |- + An opaque string representing the token to authenticate future + requests to the identity server with. + required: + - token + examples: + response: + value: { + "token": "abc123_OpaqueString" + } + /account: get: summary: Gets account holder information for a given token. - description: |- - Gets information about what user owns the access token used in the request. + description: Gets information about what user owns the access token used in the + request. operationId: getAccount security: - accessToken: [] - parameters: [] responses: - 200: + "200": description: The token holder's information. - examples: - application/json: { - "user_id": "@alice:example.org" - } - schema: - type: object - properties: - user_id: - type: string - description: The user ID which registered the token. - required: ['user_id'] - 403: + content: + application/json: + schema: + type: object + properties: + user_id: + type: string + description: The user ID which registered the token. + required: + - user_id + examples: + response: + value: { + "user_id": "@alice:example.org" + } + "403": description: | The user must do something in order to use this endpoint. One example is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service). - examples: - application/json: { - "errcode": "M_TERMS_NOT_SIGNED", - "error": "Please accept our updated terms of service before continuing" - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" - "/account/logout": + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_TERMS_NOT_SIGNED", + "error": "Please accept our updated terms of service before continuing" + } + /account/logout: post: summary: Logs out an access token, rendering it unusable. description: |- @@ -100,32 +100,54 @@ paths: operationId: logout security: - accessToken: [] - parameters: [] responses: - 200: + "200": description: The token was successfully logged out. - examples: - application/json: {} - schema: - type: object - 401: - description: |- - The token is not registered or is otherwise unknown to the server. - examples: - application/json: { - "errcode": "M_UNKNOWN_TOKEN", - "error": "Unrecognised access token" - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" - 403: + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "401": + description: The token is not registered or is otherwise unknown to the server. + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_UNKNOWN_TOKEN", + "error": "Unrecognised access token" + } + "403": description: | The user must do something in order to use this endpoint. One example is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service). - examples: - application/json: { - "errcode": "M_TERMS_NOT_SIGNED", - "error": "Please accept our updated terms of service before continuing" - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_TERMS_NOT_SIGNED", + "error": "Please accept our updated terms of service before continuing" + } +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8090 + basePath: + default: /_matrix/identity/v2 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/identity/v2_email_associations.yaml b/data/api/identity/v2_email_associations.yaml index 600fea41..0bd31b52 100644 --- a/data/api/identity/v2_email_associations.yaml +++ b/data/api/identity/v2_email_associations.yaml @@ -12,22 +12,12 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Identity Service Email Associations API" - version: "2.0.0" -host: localhost:8090 -schemes: - - https -basePath: /_matrix/identity/v2 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Identity Service Email Associations API + version: 2.0.0 paths: - "/validate/email/requestToken": + /validate/email/requestToken: post: summary: Request a token for validating an email address. description: |- @@ -51,41 +41,49 @@ paths: operationId: emailRequestTokenV2 security: - accessToken: [] - parameters: - - in: body - name: body - schema: - $ref: "definitions/request_email_validation.yaml" + requestBody: + content: + application/json: + schema: + $ref: definitions/request_email_validation.yaml responses: - 200: + "200": description: Session created. - schema: - $ref: "definitions/sid.yaml" - 400: + content: + application/json: + schema: + $ref: definitions/sid.yaml + "400": description: | An error occurred. Some possible errors are: - `M_INVALID_EMAIL`: The email address provided was invalid. - `M_EMAIL_SEND_ERROR`: The validation email could not be sent. - examples: - application/json: { - "errcode": "M_INVALID_EMAIL", - "error": "The email address is not valid" - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" - 403: + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_INVALID_EMAIL", + "error": "The email address is not valid" + } + "403": description: | The user must do something in order to use this endpoint. One example is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service). - examples: - application/json: { - "errcode": "M_TERMS_NOT_SIGNED", - "error": "Please accept our updated terms of service before continuing" - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" - "/validate/email/submitToken": + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_TERMS_NOT_SIGNED", + "error": "Please accept our updated terms of service before continuing" + } + /validate/email/submitToken: post: summary: Validate ownership of an email address. description: |- @@ -110,53 +108,63 @@ paths: operationId: emailSubmitTokenPostV2 security: - accessToken: [] - parameters: - - in: body - name: body - schema: - type: object - example: { - "sid": "1234", - "client_secret": "monkeys_are_GREAT", - "token": "atoken" - } - properties: - sid: - type: string - description: The session ID, generated by the `requestToken` call. - client_secret: - type: string - description: The client secret that was supplied to the `requestToken` call. - token: - type: string - description: The token generated by the `requestToken` call and emailed to the user. - required: ["sid", "client_secret", "token"] + requestBody: + content: + application/json: + schema: + type: object + example: { + "sid": "1234", + "client_secret": "monkeys_are_GREAT", + "token": "atoken" + } + properties: + sid: + type: string + description: The session ID, generated by the `requestToken` call. + client_secret: + type: string + description: The client secret that was supplied to the `requestToken` call. + token: + type: string + description: The token generated by the `requestToken` call and emailed to the + user. + required: + - sid + - client_secret + - token responses: - 200: - description: - The success of the validation. - examples: - application/json: { - "success": true - } - schema: - type: object - properties: - success: - type: boolean - description: Whether the validation was successful or not. - required: ['success'] - 403: + "200": + description: The success of the validation. + content: + application/json: + schema: + type: object + properties: + success: + type: boolean + description: Whether the validation was successful or not. + required: + - success + examples: + response: + value: { + "success": true + } + "403": description: | The user must do something in order to use this endpoint. One example is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service). - examples: - application/json: { - "errcode": "M_TERMS_NOT_SIGNED", - "error": "Please accept our updated terms of service before continuing" - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_TERMS_NOT_SIGNED", + "error": "Please accept our updated terms of service before continuing" + } get: summary: Validate ownership of an email address. description: |- @@ -175,42 +183,63 @@ paths: - accessToken: [] parameters: - in: query - type: string name: sid required: true description: The session ID, generated by the `requestToken` call. - x-example: 1234 + example: 1234 + schema: + type: string - in: query - type: string name: client_secret required: true description: The client secret that was supplied to the `requestToken` call. - x-example: monkeys_are_GREAT + example: monkeys_are_GREAT + schema: + type: string - in: query - type: string name: token required: true - description: The token generated by the `requestToken` call and emailed to the user. - x-example: atoken + description: The token generated by the `requestToken` call and emailed to the + user. + example: atoken + schema: + type: string responses: - 200: + "200": description: Email address is validated. - "3xx": + "403": + description: | + The user must do something in order to use this endpoint. One example + is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service). + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_TERMS_NOT_SIGNED", + "error": "Please accept our updated terms of service before continuing" + } + "3XX": description: |- Email address is validated, and the `next_link` parameter was provided to the `requestToken` call. The user must be redirected to the URL provided by the `next_link` parameter. - "4xx": - description: - Validation failed. - 403: - description: | - The user must do something in order to use this endpoint. One example - is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service). - examples: - application/json: { - "errcode": "M_TERMS_NOT_SIGNED", - "error": "Please accept our updated terms of service before continuing" - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" + "4XX": + description: Validation failed. +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8090 + basePath: + default: /_matrix/identity/v2 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/identity/v2_invitation_signing.yaml b/data/api/identity/v2_invitation_signing.yaml index 2308dc7b..ae05c6fd 100644 --- a/data/api/identity/v2_invitation_signing.yaml +++ b/data/api/identity/v2_invitation_signing.yaml @@ -12,22 +12,12 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Identity Service Ephemeral Invitation Signing API" - version: "2.0.0" -host: localhost:8090 -schemes: - - https -basePath: /_matrix/identity/v2 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Identity Service Ephemeral Invitation Signing API + version: 2.0.0 paths: - "/sign-ed25519": + /sign-ed25519: post: summary: Sign invitation details description: |- @@ -38,76 +28,108 @@ paths: operationId: blindlySignStuffV2 security: - accessToken: [] - parameters: - - in: body - name: body - schema: - type: object - example: { - "mxid": "@foo:bar.com", - "token": "sometoken", - "private_key": "base64encodedkey" - } - properties: - mxid: - type: string - description: The Matrix user ID of the user accepting the invitation. - token: - type: string - description: The token from the call to `store-invite`. - private_key: - type: string - description: The private key, encoded as [Unpadded base64](/appendices/#unpadded-base64). - required: ["mxid", "token", "private_key"] + requestBody: + content: + application/json: + schema: + type: object + example: { + "mxid": "@foo:bar.com", + "token": "sometoken", + "private_key": "base64encodedkey" + } + properties: + mxid: + type: string + description: The Matrix user ID of the user accepting the invitation. + token: + type: string + description: The token from the call to `store-invite`. + private_key: + type: string + description: The private key, encoded as [Unpadded + base64](/appendices/#unpadded-base64). + required: + - mxid + - token + - private_key responses: - 200: + "200": description: The signed JSON of the mxid, sender, and token. - schema: - type: object - properties: - mxid: - type: string - description: The Matrix user ID of the user accepting the invitation. - sender: - type: string - description: The Matrix user ID of the user who sent the invitation. - signatures: + content: + application/json: + schema: type: object - description: The signature of the mxid, sender, and token. - allOf: - - $ref: "../../schemas/server-signatures.yaml" - token: - type: string - description: The token for the invitation. - required: ['mxid', 'sender', 'signatures', 'token'] - examples: - application/json: { - "mxid": "@foo:bar.com", - "sender": "@baz:bar.com", - "signatures": { - "my.id.server": { - "ed25519:0": "def987" - } - }, - "token": "abc123" - } - 404: - description: The token was not found. - examples: - application/json: { - "errcode": "M_UNRECOGNIZED", - "error": "Didn't recognize token" - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" - 403: + properties: + mxid: + type: string + description: The Matrix user ID of the user accepting the invitation. + sender: + type: string + description: The Matrix user ID of the user who sent the invitation. + signatures: + type: object + description: The signature of the mxid, sender, and token. + allOf: + - $ref: ../../schemas/server-signatures.yaml + token: + type: string + description: The token for the invitation. + required: + - mxid + - sender + - signatures + - token + examples: + response: + value: { + "mxid": "@foo:bar.com", + "sender": "@baz:bar.com", + "signatures": { + "my.id.server": { + "ed25519:0": "def987" + } + }, + "token": "abc123" + } + "403": description: | The user must do something in order to use this endpoint. One example is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service). - examples: - application/json: { - "errcode": "M_TERMS_NOT_SIGNED", - "error": "Please accept our updated terms of service before continuing" - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_TERMS_NOT_SIGNED", + "error": "Please accept our updated terms of service before continuing" + } + "404": + description: The token was not found. + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_UNRECOGNIZED", + "error": "Didn't recognize token" + } +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8090 + basePath: + default: /_matrix/identity/v2 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/identity/v2_lookup.yaml b/data/api/identity/v2_lookup.yaml index d5e9352c..ce716abd 100644 --- a/data/api/identity/v2_lookup.yaml +++ b/data/api/identity/v2_lookup.yaml @@ -15,22 +15,12 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Identity Service Lookup API" - version: "2.0.0" -host: localhost:8090 -schemes: - - https -basePath: /_matrix/identity/v2 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Identity Service Lookup API + version: 2.0.0 paths: - "/hash_details": + /hash_details: get: summary: Gets hash function information from the server. description: |- @@ -39,33 +29,39 @@ paths: operationId: getHashDetails security: - accessToken: [] - parameters: [] responses: - 200: + "200": description: The hash function information. - examples: - application/json: { - "lookup_pepper": "matrixrocks", - "algorithms": ["none", "sha256"] - } - schema: - type: object - properties: - lookup_pepper: - type: string - description: |- - The pepper the client MUST use in hashing identifiers, and MUST - supply to the `/lookup` endpoint when performing lookups. + content: + application/json: + schema: + type: object + properties: + lookup_pepper: + type: string + description: |- + The pepper the client MUST use in hashing identifiers, and MUST + supply to the `/lookup` endpoint when performing lookups. - Servers SHOULD rotate this string often. - algorithms: - type: array - items: - type: string - description: |- - The algorithms the server supports. Must contain at least `sha256`. - required: ['lookup_pepper', 'algorithms'] - "/lookup": + Servers SHOULD rotate this string often. + algorithms: + type: array + items: + type: string + description: The algorithms the server supports. Must contain at least `sha256`. + required: + - lookup_pepper + - algorithms + examples: + response: + value: { + "lookup_pepper": "matrixrocks", + "algorithms": [ + "none", + "sha256" + ] + } + /lookup: post: summary: Look up Matrix User IDs for a set of 3PIDs. description: |- @@ -75,78 +71,95 @@ paths: operationId: lookupUsersV2 security: - accessToken: [] - parameters: - - in: body - name: body - schema: - type: object - properties: - algorithm: - type: string - description: |- - The algorithm the client is using to encode the `addresses`. This - should be one of the available options from `/hash_details`. - example: "sha256" - pepper: - type: string - description: |- - The pepper from `/hash_details`. This is required even when the - `algorithm` does not make use of it. - example: "matrixrocks" - addresses: - type: array - items: + requestBody: + content: + application/json: + schema: + type: object + properties: + algorithm: type: string - description: |- - The addresses to look up. The format of the entries here depend on - the `algorithm` used. Note that queries which have been incorrectly - hashed or formatted will lead to no matches. + description: |- + The algorithm the client is using to encode the `addresses`. This + should be one of the available options from `/hash_details`. + example: sha256 + pepper: + type: string + description: |- + The pepper from `/hash_details`. This is required even when the + `algorithm` does not make use of it. + example: matrixrocks + addresses: + type: array + items: + type: string + description: |- + The addresses to look up. The format of the entries here depend on + the `algorithm` used. Note that queries which have been incorrectly + hashed or formatted will lead to no matches. - Note that addresses are case sensitive: review the - [3PID Types](/appendices#3pid-types) to verify the intended case an - identifier should be prior to submission/hashing. - example: [ - "4kenr7N9drpCJ4AfalmlGQVsOn3o2RHjkADUpXJWZUc", - "nlo35_T5fzSGZzJApqu8lgIudJvmOQtDaHtr-I4rU7I" - ] - required: ['algorithm', 'pepper', 'addresses'] + Note that addresses are case sensitive: review the + [3PID Types](/appendices#3pid-types) to verify the intended case an + identifier should be prior to submission/hashing. + example: + - 4kenr7N9drpCJ4AfalmlGQVsOn3o2RHjkADUpXJWZUc + - nlo35_T5fzSGZzJApqu8lgIudJvmOQtDaHtr-I4rU7I + required: + - algorithm + - pepper + - addresses responses: - 200: - description: - The associations for any matched `addresses`. - examples: - application/json: { - "mappings": { - "4kenr7N9drpCJ4AfalmlGQVsOn3o2RHjkADUpXJWZUc": "@alice:example.org" - } - } - schema: - type: object - properties: - mappings: + "200": + description: The associations for any matched `addresses`. + content: + application/json: + schema: type: object - description: |- - Any applicable mappings of `addresses` to Matrix User IDs. Addresses - which do not have associations will not be included, which can make - this property be an empty object. - title: AssociatedMappings - additionalProperties: - type: string - required: ['mappings'] - 400: - description: - The client's request was invalid in some way. One possible problem could - be the `pepper` being invalid after the server has rotated it - this is - presented with the `M_INVALID_PEPPER` error code. Clients SHOULD make - a call to `/hash_details` to get a new pepper in this scenario, being - careful to avoid retry loops. - - `M_INVALID_PARAM` can also be returned to indicate the client supplied - an `algorithm` that is unknown to the server. - examples: - application/json: { - "errcode": "M_INVALID_PEPPER", - "error": "Unknown or invalid pepper - has it been rotated?" - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" + properties: + mappings: + type: object + description: |- + Any applicable mappings of `addresses` to Matrix User IDs. Addresses + which do not have associations will not be included, which can make + this property be an empty object. + title: AssociatedMappings + additionalProperties: + type: string + required: + - mappings + examples: + response: + value: { + "mappings": { + "4kenr7N9drpCJ4AfalmlGQVsOn3o2RHjkADUpXJWZUc": "@alice:example.org" + } + } + "400": + description: |- + The client's request was invalid in some way. One possible problem could be the `pepper` being invalid after the server has rotated it - this is presented with the `M_INVALID_PEPPER` error code. Clients SHOULD make a call to `/hash_details` to get a new pepper in this scenario, being careful to avoid retry loops. + `M_INVALID_PARAM` can also be returned to indicate the client supplied an `algorithm` that is unknown to the server. + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_INVALID_PEPPER", + "error": "Unknown or invalid pepper - has it been rotated?" + } +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8090 + basePath: + default: /_matrix/identity/v2 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/identity/v2_phone_associations.yaml b/data/api/identity/v2_phone_associations.yaml index 85b523e4..f887be26 100644 --- a/data/api/identity/v2_phone_associations.yaml +++ b/data/api/identity/v2_phone_associations.yaml @@ -12,22 +12,12 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Identity Service Phone Number Associations API" - version: "2.0.0" -host: localhost:8090 -schemes: - - https -basePath: /_matrix/identity/v2 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Identity Service Phone Number Associations API + version: 2.0.0 paths: - "/validate/msisdn/requestToken": + /validate/msisdn/requestToken: post: summary: Request a token for validating a phone number. description: |- @@ -51,17 +41,19 @@ paths: operationId: msisdnRequestTokenV2 security: - accessToken: [] - parameters: - - in: body - name: body - schema: - $ref: "definitions/request_msisdn_validation.yaml" + requestBody: + content: + application/json: + schema: + $ref: definitions/request_msisdn_validation.yaml responses: - 200: + "200": description: Session created. - schema: - $ref: "definitions/sid.yaml" - 400: + content: + application/json: + schema: + $ref: definitions/sid.yaml + "400": description: | An error occurred. Some possible errors are: @@ -69,25 +61,31 @@ paths: - `M_SEND_ERROR`: The validation SMS could not be sent. - `M_DESTINATION_REJECTED`: The identity server cannot deliver an SMS to the provided country or region. - examples: - application/json: { - "errcode": "M_INVALID_ADDRESS", - "error": "The phone number is not valid" - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" - 403: + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_INVALID_ADDRESS", + "error": "The phone number is not valid" + } + "403": description: | The user must do something in order to use this endpoint. One example is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service). - examples: - application/json: { - "errcode": "M_TERMS_NOT_SIGNED", - "error": "Please accept our updated terms of service before continuing" - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" - "/validate/msisdn/submitToken": + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_TERMS_NOT_SIGNED", + "error": "Please accept our updated terms of service before continuing" + } + /validate/msisdn/submitToken: post: summary: Validate ownership of a phone number. description: |- @@ -112,53 +110,63 @@ paths: operationId: msisdnSubmitTokenPostV2 security: - accessToken: [] - parameters: - - in: body - name: body - schema: - type: object - example: { - "sid": "1234", - "client_secret": "monkeys_are_GREAT", - "token": "atoken" - } - properties: - sid: - type: string - description: The session ID, generated by the `requestToken` call. - client_secret: - type: string - description: The client secret that was supplied to the `requestToken` call. - token: - type: string - description: The token generated by the `requestToken` call and sent to the user. - required: ["sid", "client_secret", "token"] + requestBody: + content: + application/json: + schema: + type: object + example: { + "sid": "1234", + "client_secret": "monkeys_are_GREAT", + "token": "atoken" + } + properties: + sid: + type: string + description: The session ID, generated by the `requestToken` call. + client_secret: + type: string + description: The client secret that was supplied to the `requestToken` call. + token: + type: string + description: The token generated by the `requestToken` call and sent to the + user. + required: + - sid + - client_secret + - token responses: - 200: - description: - The success of the validation. - examples: - application/json: { - "success": true - } - schema: - type: object - properties: - success: - type: boolean - description: Whether the validation was successful or not. - required: ['success'] - 403: + "200": + description: The success of the validation. + content: + application/json: + schema: + type: object + properties: + success: + type: boolean + description: Whether the validation was successful or not. + required: + - success + examples: + response: + value: { + "success": true + } + "403": description: | The user must do something in order to use this endpoint. One example is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service). - examples: - application/json: { - "errcode": "M_TERMS_NOT_SIGNED", - "error": "Please accept our updated terms of service before continuing" - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_TERMS_NOT_SIGNED", + "error": "Please accept our updated terms of service before continuing" + } get: summary: Validate ownership of a phone number. description: |- @@ -177,42 +185,62 @@ paths: - accessToken: [] parameters: - in: query - type: string name: sid required: true description: The session ID, generated by the `requestToken` call. - x-example: 1234 + example: 1234 + schema: + type: string - in: query - type: string name: client_secret required: true description: The client secret that was supplied to the `requestToken` call. - x-example: monkeys_are_GREAT + example: monkeys_are_GREAT + schema: + type: string - in: query - type: string name: token required: true description: The token generated by the `requestToken` call and sent to the user. - x-example: atoken + example: atoken + schema: + type: string responses: - 200: + "200": description: Phone number is validated. - "3xx": + "403": + description: | + The user must do something in order to use this endpoint. One example + is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service). + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_TERMS_NOT_SIGNED", + "error": "Please accept our updated terms of service before continuing" + } + "3XX": description: |- Phone number address is validated, and the `next_link` parameter was provided to the `requestToken` call. The user must be redirected to the URL provided by the `next_link` parameter. - "4xx": - description: - Validation failed. - 403: - description: | - The user must do something in order to use this endpoint. One example - is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service). - examples: - application/json: { - "errcode": "M_TERMS_NOT_SIGNED", - "error": "Please accept our updated terms of service before continuing" - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" + "4XX": + description: Validation failed. +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8090 + basePath: + default: /_matrix/identity/v2 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/identity/v2_ping.yaml b/data/api/identity/v2_ping.yaml index e056e321..8e8044b2 100644 --- a/data/api/identity/v2_ping.yaml +++ b/data/api/identity/v2_ping.yaml @@ -13,19 +13,12 @@ # 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. - -swagger: "2.0" +openapi: 3.1.0 info: - title: "Matrix Identity Service Ping API" - version: "2.0.0" -host: localhost:8090 -schemes: - - https -basePath: /_matrix/identity -produces: - - application/json + title: Matrix Identity Service Ping API + version: 2.0.0 paths: - "/v2": + /v2: get: summary: Checks that an identity server is available at this API endpoint. description: |- @@ -38,9 +31,24 @@ paths: by entities acting as a client for the identity server. operationId: pingV2 responses: - 200: + "200": description: An identity server is ready to serve requests. - examples: - application/json: {} - schema: - type: object + content: + application/json: + schema: + type: object + examples: + response: + value: {} +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8090 + basePath: + default: /_matrix/identity diff --git a/data/api/identity/v2_pubkey.yaml b/data/api/identity/v2_pubkey.yaml index 68facd68..2aaf5f8e 100644 --- a/data/api/identity/v2_pubkey.yaml +++ b/data/api/identity/v2_pubkey.yaml @@ -12,61 +12,58 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Identity Service Public Key API" - version: "2.0.0" -host: localhost:8090 -schemes: - - https -basePath: /_matrix/identity/v2 -consumes: - - application/json -produces: - - application/json + title: Matrix Identity Service Public Key API + version: 2.0.0 paths: "/pubkey/{keyId}": get: summary: Get a public key. - description: |- - Get the public key for the passed key ID. + description: Get the public key for the passed key ID. operationId: getPubKeyV2 parameters: - in: path - type: string name: keyId required: true description: |- The ID of the key. This should take the form algorithm:identifier where algorithm identifies the signing algorithm, and the identifier is an opaque string. - x-example: "ed25519:0" + example: ed25519:0 + schema: + type: string responses: - 200: - description: - The public key exists. - examples: - application/json: { - "public_key": "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c" - } - schema: - type: object - properties: - public_key: - type: string - description: Unpadded Base64 encoded public key. - required: ['public_key'] - 404: - description: - The public key was not found. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "The public key was not found" - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" - "/pubkey/isvalid": + "200": + description: The public key exists. + content: + application/json: + schema: + type: object + properties: + public_key: + type: string + description: Unpadded Base64 encoded public key. + required: + - public_key + examples: + response: + value: { + "public_key": "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c" + } + "404": + description: The public key was not found. + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "The public key was not found" + } + /pubkey/isvalid: get: summary: Check whether a long-term public key is valid. description: |- @@ -75,53 +72,70 @@ paths: operationId: isPubKeyValidV2 parameters: - in: query - type: string name: public_key required: true - description: |- - The unpadded base64-encoded public key to check. - x-example: "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c" - responses: - 200: - description: - The validity of the public key. - examples: - application/json: { - "valid": true - } + description: The unpadded base64-encoded public key to check. + example: VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c schema: - type: object - properties: - valid: - type: boolean - description: Whether the public key is recognised and is currently valid. - required: ['valid'] - "/pubkey/ephemeral/isvalid": + type: string + responses: + "200": + description: The validity of the public key. + content: + application/json: + schema: + type: object + properties: + valid: + type: boolean + description: Whether the public key is recognised and is currently valid. + required: + - valid + examples: + response: + value: { + "valid": true + } + /pubkey/ephemeral/isvalid: get: summary: Check whether a short-term public key is valid. - description: |- - Check whether a short-term public key is valid. + description: Check whether a short-term public key is valid. operationId: isEphemeralPubKeyValidV2 parameters: - in: query - type: string name: public_key required: true - description: |- - The unpadded base64-encoded public key to check. - x-example: "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c" - responses: - 200: - description: - The validity of the public key. - examples: - application/json: { - "valid": true - } + description: The unpadded base64-encoded public key to check. + example: VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c schema: - type: object - properties: - valid: - type: boolean - description: Whether the public key is recognised and is currently valid. - required: ['valid'] + type: string + responses: + "200": + description: The validity of the public key. + content: + application/json: + schema: + type: object + properties: + valid: + type: boolean + description: Whether the public key is recognised and is currently valid. + required: + - valid + examples: + response: + value: { + "valid": true + } +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8090 + basePath: + default: /_matrix/identity/v2 diff --git a/data/api/identity/v2_store_invite.yaml b/data/api/identity/v2_store_invite.yaml index 163081bb..230dd503 100644 --- a/data/api/identity/v2_store_invite.yaml +++ b/data/api/identity/v2_store_invite.yaml @@ -12,22 +12,12 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Identity Service Store Invitations API" - version: "2.0.0" -host: localhost:8090 -schemes: - - https -basePath: /_matrix/identity/v2 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Identity Service Store Invitations API + version: 2.0.0 paths: - "/store-invite": + /store-invite: post: summary: Store pending invitations to a user's 3pid. description: |- @@ -62,142 +52,176 @@ paths: operationId: storeInviteV2 security: - accessToken: [] - parameters: - - in: body - name: body - schema: - type: object - properties: - medium: - type: string - description: The literal string `email`. - example: "email" - address: - type: string - description: The email address of the invited user. - example: "foo@example.com" - room_id: - type: string - description: The Matrix room ID to which the user is invited - example: "!something:example.org" - sender: - type: string - description: The Matrix user ID of the inviting user - example: "@bob:example.com" - room_alias: - type: string - description: |- - The Matrix room alias for the room to which the user is - invited. This should be retrieved from the `m.room.canonical_alias` - state event. - example: "#somewhere:example.org" - room_avatar_url: - type: string - description: |- - The Content URI for the room to which the user is invited. This should - be retrieved from the `m.room.avatar` state event. - example: "mxc://example.org/s0meM3dia" - room_join_rules: - type: string - description: |- - The `join_rule` for the room to which the user is invited. This should - be retrieved from the `m.room.join_rules` state event. - example: "public" - room_name: - type: string - description: |- - The name of the room to which the user is invited. This should be retrieved - from the `m.room.name` state event. - example: "Bob's Emporium of Messages" - sender_display_name: - type: string - description: The display name of the user ID initiating the invite. - example: "Bob Smith" - sender_avatar_url: - type: string - description: The Content URI for the avatar of the user ID initiating the invite. - example: "mxc://example.org/an0th3rM3dia" - room_type: - type: string - description: |- - The `type` from the `m.room.create` event's `content`. If the create event doesn't - have a specified `type`, this field is not included. - example: "m.space" - required: ["medium", "address", "room_id", "sender"] + requestBody: + content: + application/json: + schema: + type: object + properties: + medium: + type: string + description: The literal string `email`. + example: email + address: + type: string + description: The email address of the invited user. + example: foo@example.com + room_id: + type: string + description: The Matrix room ID to which the user is invited + example: "!something:example.org" + sender: + type: string + description: The Matrix user ID of the inviting user + example: "@bob:example.com" + room_alias: + type: string + description: |- + The Matrix room alias for the room to which the user is + invited. This should be retrieved from the `m.room.canonical_alias` + state event. + example: "#somewhere:example.org" + room_avatar_url: + type: string + description: |- + The Content URI for the room to which the user is invited. This should + be retrieved from the `m.room.avatar` state event. + example: mxc://example.org/s0meM3dia + room_join_rules: + type: string + description: |- + The `join_rule` for the room to which the user is invited. This should + be retrieved from the `m.room.join_rules` state event. + example: public + room_name: + type: string + description: |- + The name of the room to which the user is invited. This should be retrieved + from the `m.room.name` state event. + example: Bob's Emporium of Messages + sender_display_name: + type: string + description: The display name of the user ID initiating the invite. + example: Bob Smith + sender_avatar_url: + type: string + description: The Content URI for the avatar of the user ID initiating the + invite. + example: mxc://example.org/an0th3rM3dia + room_type: + type: string + description: |- + The `type` from the `m.room.create` event's `content`. If the create event doesn't + have a specified `type`, this field is not included. + example: m.space + required: + - medium + - address + - room_id + - sender responses: - 200: + "200": description: The invitation was stored. - schema: - type: object - properties: - token: - type: string - description: | - The generated token. Must be a string consisting of the - characters `[0-9a-zA-Z.=_-]`. Its length must not exceed - 255 characters and it must not be empty. - public_keys: - type: array - description: | - A list of [server's long-term public key, generated ephemeral - public key]. - items: - type: object - title: PublicKey - properties: - public_key: - type: string - description: | - The public key, encoded using [unpadded Base64](/appendices/#unpadded-base64). - key_validity_url: - type: string - description: | - The URI of an endpoint where the validity of this key can be checked - by passing it as a `public_key` query parameter. See - [key management](/identity-service-api/#key-management). - required: ['public_key', 'key_validity_url'] - display_name: - type: string - description: The generated (redacted) display name. - required: ['token', 'public_keys', 'display_name'] - examples: - application/json: { - "token": "sometoken", - "public_keys": [ - { - "public_key": "serverPublicKeyBase64", - "key_validity_url": "https://example.com/_matrix/identity/v2/pubkey/isvalid" - }, - { - "public_key": "ephemeralPublicKeyBase64", - "key_validity_url": "https://example.com/_matrix/identity/v2/pubkey/ephemeral/isvalid" - } - ], - "display_name": "f...@b..." - } - 400: + content: + application/json: + schema: + type: object + properties: + token: + type: string + description: | + The generated token. Must be a string consisting of the + characters `[0-9a-zA-Z.=_-]`. Its length must not exceed + 255 characters and it must not be empty. + public_keys: + type: array + description: | + A list of [server's long-term public key, generated ephemeral + public key]. + items: + type: object + title: PublicKey + properties: + public_key: + type: string + description: | + The public key, encoded using [unpadded Base64](/appendices/#unpadded-base64). + key_validity_url: + type: string + description: | + The URI of an endpoint where the validity of this key can be checked + by passing it as a `public_key` query parameter. See + [key management](/identity-service-api/#key-management). + required: + - public_key + - key_validity_url + display_name: + type: string + description: The generated (redacted) display name. + required: + - token + - public_keys + - display_name + examples: + response: + value: { + "token": "sometoken", + "public_keys": [ + { + "public_key": "serverPublicKeyBase64", + "key_validity_url": "https://example.com/_matrix/identity/v2/pubkey/isvalid" + }, + { + "public_key": "ephemeralPublicKeyBase64", + "key_validity_url": "https://example.com/_matrix/identity/v2/pubkey/ephemeral/isvalid" + } + ], + "display_name": "f...@b..." + } + "400": description: | An error has occurred. If the 3pid is already bound to a Matrix user ID, the error code will be `M_THREEPID_IN_USE`. If the medium is unsupported, the error code will be `M_UNRECOGNIZED`. - examples: - application/json: { - "errcode": "M_THREEPID_IN_USE", - "error": "Binding already known", - "mxid": "@alice:example.com" - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" - 403: + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_THREEPID_IN_USE", + "error": "Binding already known", + "mxid": "@alice:example.com" + } + "403": description: | The user must do something in order to use this endpoint. One example is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service). - examples: - application/json: { - "errcode": "M_TERMS_NOT_SIGNED", - "error": "Please accept our updated terms of service before continuing" - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_TERMS_NOT_SIGNED", + "error": "Please accept our updated terms of service before continuing" + } +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8090 + basePath: + default: /_matrix/identity/v2 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/identity/v2_terms.yaml b/data/api/identity/v2_terms.yaml index fcab28b7..f4a45932 100644 --- a/data/api/identity/v2_terms.yaml +++ b/data/api/identity/v2_terms.yaml @@ -11,22 +11,12 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Identity Service Terms of Service API" - version: "2.0.0" -host: localhost:8090 -schemes: - - https -basePath: /_matrix/identity/v2 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Identity Service Terms of Service API + version: 2.0.0 paths: - "/terms": + /terms: get: summary: Gets the terms of service offered by the server. description: |- @@ -34,81 +24,85 @@ paths: to filter through the terms to determine which terms need acceptance from the user. Note that this endpoint does not require authentication. operationId: getTerms - parameters: [] responses: - 200: - description: |- - The terms of service offered by the server. - examples: - application/json: { - "policies": { - "terms_of_service": { - "version": "2.0", - "en": { - "name": "Terms of Service", - "url": "https://example.org/somewhere/terms-2.0-en.html" - }, - "fr": { - "name": "Conditions d'utilisation", - "url": "https://example.org/somewhere/terms-2.0-fr.html" - } - }, - "privacy_policy": { - "version": "1.2", - "en": { - "name": "Privacy Policy", - "url": "https://example.org/somewhere/privacy-1.2-en.html" - }, - "fr": { - "name": "Politique de confidentialité", - "url": "https://example.org/somewhere/privacy-1.2-fr.html" - } - } - } - } - schema: - type: object - properties: - policies: + "200": + description: The terms of service offered by the server. + content: + application/json: + schema: type: object - title: Policy Map - description: |- - The policies the server offers. Mapped from arbitrary ID (unused in - this version of the specification) to a Policy Object. - additionalProperties: - type: object - title: Policy Object - description: |- - The policy. Includes a map of language (ISO 639-2) to language-specific - policy information. - properties: - version: - type: string - description: |- - The version for the policy. There are no requirements on what this - might be and could be "alpha", semantically versioned, or arbitrary. - required: ['version'] - # TODO: TravisR - Make this render - additionalProperties: + properties: + policies: type: object - title: Internationalised Policy + title: Policy Map description: |- - The policy information for the specified language. - properties: - name: - type: string - description: The translated name of the policy. - url: - type: string - description: |- - The URL, which should include the policy ID, version, and language - in it, to be presented to the user as the policy. URLs should have - all three criteria to avoid conflicts when the policy is updated - in the future: for example, if this was "https://example.org/terms.html" - then the server would be unable to update it because the client would - have already added that URL to the `m.accepted_terms` collection. - required: ['name', 'url'] - required: ['policies'] + The policies the server offers. Mapped from arbitrary ID (unused in + this version of the specification) to a Policy Object. + additionalProperties: + type: object + title: Policy Object + description: |- + The policy. Includes a map of language (ISO 639-2) to language-specific + policy information. + properties: + version: + type: string + description: |- + The version for the policy. There are no requirements on what this + might be and could be "alpha", semantically versioned, or arbitrary. + required: + - version + # TODO: TravisR - Make this render + additionalProperties: + type: object + title: Internationalised Policy + description: The policy information for the specified language. + properties: + name: + type: string + description: The translated name of the policy. + url: + type: string + description: |- + The URL, which should include the policy ID, version, and language + in it, to be presented to the user as the policy. URLs should have + all three criteria to avoid conflicts when the policy is updated + in the future: for example, if this was "https://example.org/terms.html" + then the server would be unable to update it because the client would + have already added that URL to the `m.accepted_terms` collection. + required: + - name + - url + required: + - policies + examples: + response: + value: { + "policies": { + "terms_of_service": { + "version": "2.0", + "en": { + "name": "Terms of Service", + "url": "https://example.org/somewhere/terms-2.0-en.html" + }, + "fr": { + "name": "Conditions d'utilisation", + "url": "https://example.org/somewhere/terms-2.0-fr.html" + } + }, + "privacy_policy": { + "version": "1.2", + "en": { + "name": "Privacy Policy", + "url": "https://example.org/somewhere/privacy-1.2-en.html" + }, + "fr": { + "name": "Politique de confidentialité", + "url": "https://example.org/somewhere/privacy-1.2-fr.html" + } + } + } + } post: summary: Indicates acceptance of terms to the server. description: |- @@ -126,24 +120,43 @@ paths: operationId: agreeToTerms security: - accessToken: [] - parameters: - - in: body - name: body - schema: - type: object - properties: - user_accepts: - type: array - items: - type: string - description: The URLs the user is accepting in this request. - example: "https://example.org/somewhere/terms-2.0-en.html" - required: ['user_accepts'] + requestBody: + content: + application/json: + schema: + type: object + properties: + user_accepts: + type: array + items: + type: string + description: The URLs the user is accepting in this request. + example: https://example.org/somewhere/terms-2.0-en.html + required: + - user_accepts responses: - 200: - description: |- - The server has considered the user as having accepted the provided URLs. - examples: - application/json: {} - schema: - type: object + "200": + description: The server has considered the user as having accepted the provided + URLs. + content: + application/json: + schema: + type: object + examples: + response: + value: {} +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8090 + basePath: + default: /_matrix/identity/v2 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/identity/versions.yaml b/data/api/identity/versions.yaml index ff821e22..5338b6f3 100644 --- a/data/api/identity/versions.yaml +++ b/data/api/identity/versions.yaml @@ -11,18 +11,12 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Identity Service Versions API" - version: "1.0.0" -host: localhost:8090 -schemes: - - https -basePath: /_matrix/identity -produces: - - application/json + title: Matrix Identity Service Versions API + version: 1.0.0 paths: - "/versions": + /versions: get: x-addedInMatrixVersion: "1.1" summary: Gets the versions of the specification supported by the server. @@ -36,19 +30,39 @@ paths: All supported versions, including patch versions, are reported by the server. operationId: getVersions responses: - 200: + "200": description: The versions supported by the server. - examples: - application/json: { - "versions": ["r0.2.0", "r0.2.1", "v1.1"] - } - schema: - type: object - properties: - versions: - type: array - description: The supported versions. - items: - type: string - description: The supported versions. - required: ['versions'] + content: + application/json: + schema: + type: object + properties: + versions: + type: array + description: The supported versions. + items: + type: string + description: The supported versions. + required: + - versions + examples: + response: + value: { + "versions": [ + "r0.2.0", + "r0.2.1", + "v1.1" + ] + } +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8090 + basePath: + default: /_matrix/identity diff --git a/data/api/push-gateway/push_notifier.yaml b/data/api/push-gateway/push_notifier.yaml index 96d61bf0..e23d33b0 100644 --- a/data/api/push-gateway/push_notifier.yaml +++ b/data/api/push-gateway/push_notifier.yaml @@ -12,21 +12,12 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Push Notification API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/push/v1 -consumes: - - application/json -produces: - - application/json + title: Matrix Push Notification API + version: 1.0.0 paths: - "/notify": + /notify: post: summary: Notify a push gateway about an event. description: |- @@ -48,182 +39,203 @@ paths: This means that the HTTP path may be different depending on the push gateway. operationId: notify - parameters: - - in: body - name: notification - description: Information about the push notification. - required: true - schema: - type: object - example: { - "notification": { - "event_id": "$3957tyerfgewrf384", - "room_id": "!slw48wfj34rtnrf:example.com", - "type": "m.room.message", - "sender": "@exampleuser:matrix.org", - "sender_display_name": "Major Tom", - "room_name": "Mission Control", - "room_alias": "#exampleroom:matrix.org", - "prio": "high", - "content": { - "msgtype": "m.text", - "body": "I'm floating in a most peculiar way." - }, - "counts": { - "unread" : 2, - "missed_calls": 1 - }, - "devices": [ - { - "app_id": "org.matrix.matrixConsole.ios", - "pushkey": "V2h5IG9uIGVhcnRoIGRpZCB5b3UgZGVjb2RlIHRoaXM/", - "pushkey_ts": 12345678, - "data" : {}, - "tweaks": { - "sound": "bing" + requestBody: + content: + application/json: + schema: + type: object + example: { + "notification": { + "event_id": "$3957tyerfgewrf384", + "room_id": "!slw48wfj34rtnrf:example.com", + "type": "m.room.message", + "sender": "@exampleuser:matrix.org", + "sender_display_name": "Major Tom", + "room_name": "Mission Control", + "room_alias": "#exampleroom:matrix.org", + "prio": "high", + "content": { + "msgtype": "m.text", + "body": "I'm floating in a most peculiar way." + }, + "counts": { + "unread": 2, + "missed_calls": 1 + }, + "devices": [ + { + "app_id": "org.matrix.matrixConsole.ios", + "pushkey": "V2h5IG9uIGVhcnRoIGRpZCB5b3UgZGVjb2RlIHRoaXM/", + "pushkey_ts": 12345678, + "data": {}, + "tweaks": { + "sound": "bing" + } } - } - ] + ] + } } - } - required: ["notification"] - properties: - notification: - type: object - title: Notification - description: Information about the push notification - required: ["devices"] - properties: - event_id: - type: string - description: |- - The Matrix event ID of the event being notified about. - This is required if the notification is about a - particular Matrix event. It may be omitted for notifications - that only contain updated badge counts. This ID can and - should be used to detect duplicate notification requests. - room_id: - type: string - description: |- - The ID of the room in which this event occurred. - Required if the notification relates to a specific - Matrix event. - type: - type: string - description: |- - The type of the event as in the event's `type` field. - sender: - type: string - description: |- - The sender of the event as in the corresponding event field. - sender_display_name: - type: string - description: |- - The current display name of the sender in the room in which - the event occurred. - room_name: - type: string - description: The name of the room in which the event occurred. - room_alias: - type: string - description: An alias to display for the room in which the event occurred. - user_is_target: - type: boolean - description: |- - This is true if the user receiving the notification is the - subject of a member event (i.e. the `state_key` of the - member event is equal to the user's Matrix ID). - prio: - type: string - enum: ["high", "low"] - description: |- - The priority of the notification. If omitted, `high` is - assumed. This may be used by push gateways to deliver less - time-sensitive notifications in a way that will preserve - battery power on mobile devices. - content: - type: object - title: EventContent - description: |- - The `content` field from the event, if present. The pusher - may omit this if the event had no content or for any other - reason. - counts: - type: object - title: Counts - description: |- - This is a dictionary of the current number of unacknowledged - communications for the recipient user. Counts whose value is - zero should be omitted. - properties: - unread: - type: integer - description: |- - The number of unread messages a user has across all of the - rooms they are a member of. - missed_calls: - type: integer - description: |- - The number of unacknowledged missed calls a user has - across all rooms of which they are a member. - devices: - type: array - title: Devices - description: |- - This is an array of devices that the notification should be sent to. - items: + required: + - notification + properties: + notification: + type: object + title: Notification + description: Information about the push notification + required: + - devices + properties: + event_id: + type: string + description: |- + The Matrix event ID of the event being notified about. + This is required if the notification is about a + particular Matrix event. It may be omitted for notifications + that only contain updated badge counts. This ID can and + should be used to detect duplicate notification requests. + room_id: + type: string + description: |- + The ID of the room in which this event occurred. + Required if the notification relates to a specific + Matrix event. + type: + type: string + description: The type of the event as in the event's `type` field. + sender: + type: string + description: The sender of the event as in the corresponding event field. + sender_display_name: + type: string + description: |- + The current display name of the sender in the room in which + the event occurred. + room_name: + type: string + description: The name of the room in which the event occurred. + room_alias: + type: string + description: An alias to display for the room in which the event occurred. + user_is_target: + type: boolean + description: |- + This is true if the user receiving the notification is the + subject of a member event (i.e. the `state_key` of the + member event is equal to the user's Matrix ID). + prio: + type: string + enum: + - high + - low + description: |- + The priority of the notification. If omitted, `high` is + assumed. This may be used by push gateways to deliver less + time-sensitive notifications in a way that will preserve + battery power on mobile devices. + content: type: object - title: Device + title: EventContent + description: |- + The `content` field from the event, if present. The pusher + may omit this if the event had no content or for any other + reason. + counts: + type: object + title: Counts + description: |- + This is a dictionary of the current number of unacknowledged + communications for the recipient user. Counts whose value is + zero should be omitted. properties: - app_id: - type: string - description: |- - The `app_id` given when the pusher was created. - pushkey: - type: string - description: The `pushkey` given when the pusher was created. - pushkey_ts: + unread: type: integer - format: int64 description: |- - The unix timestamp (in seconds) when the - pushkey was last updated. - data: - type: object - title: PusherData + The number of unread messages a user has across all of the + rooms they are a member of. + missed_calls: + type: integer description: |- - A dictionary of additional pusher-specific data. For - 'http' pushers, this is the data dictionary passed in at - pusher creation minus the `url` key. - tweaks: - type: object - title: Tweaks - description: |- - A dictionary of customisations made to the way this - notification is to be presented. These are added by push rules. - required: ['app_id', 'pushkey'] + The number of unacknowledged missed calls a user has + across all rooms of which they are a member. + devices: + type: array + title: Devices + description: This is an array of devices that the notification should be sent + to. + items: + type: object + title: Device + properties: + app_id: + type: string + description: The `app_id` given when the pusher was created. + pushkey: + type: string + description: The `pushkey` given when the pusher was created. + pushkey_ts: + type: integer + format: int64 + description: |- + The unix timestamp (in seconds) when the + pushkey was last updated. + data: + type: object + title: PusherData + description: |- + A dictionary of additional pusher-specific data. For + 'http' pushers, this is the data dictionary passed in at + pusher creation minus the `url` key. + tweaks: + type: object + title: Tweaks + description: |- + A dictionary of customisations made to the way this + notification is to be presented. These are added by push rules. + required: + - app_id + - pushkey + description: Information about the push notification. + required: true responses: - 200: + "200": description: A list of rejected push keys. - examples: - application/json: { - "rejected": [ "V2h5IG9uIGVhcnRoIGRpZCB5b3UgZGVjb2RlIHRoaXM/" ] - } - schema: - type: object # empty json object - properties: - rejected: - type: array - description: |- - A list of all pushkeys given in the notification request that - are not valid. These could have been rejected by an upstream - gateway because they have expired or have never been valid. - Homeservers must cease sending notification requests for these - pushkeys and remove the associated pushers. It may not - necessarily be the notification in the request that failed: - it could be that a previous notification to the same pushkey - failed. May be empty. - items: - type: string - description: A pushkey that has been rejected. - required: ['rejected'] + content: + application/json: + schema: + type: object # empty json object + properties: + rejected: + type: array + description: |- + A list of all pushkeys given in the notification request that + are not valid. These could have been rejected by an upstream + gateway because they have expired or have never been valid. + Homeservers must cease sending notification requests for these + pushkeys and remove the associated pushers. It may not + necessarily be the notification in the request that failed: + it could be that a previous notification to the same pushkey + failed. May be empty. + items: + type: string + description: A pushkey that has been rejected. + required: + - rejected + examples: + response: + value: { + "rejected": [ + "V2h5IG9uIGVhcnRoIGRpZCB5b3UgZGVjb2RlIHRoaXM/" + ] + } +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/push/v1 diff --git a/data/api/server-server/backfill.yaml b/data/api/server-server/backfill.yaml index 6adeb26c..a37e5ed4 100644 --- a/data/api/server-server/backfill.yaml +++ b/data/api/server-server/backfill.yaml @@ -11,21 +11,10 @@ # 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. - -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Federation Events API" - version: "1.0.0" -host: localhost:8448 -schemes: - - https -basePath: /_matrix/federation/v1 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Federation Events API + version: 1.0.0 paths: "/backfill/{roomId}": get: @@ -40,26 +29,30 @@ paths: parameters: - in: path name: roomId - type: string description: The room ID to backfill. required: true - x-example: "!SomeRoom:matrix.org" + example: "!SomeRoom:matrix.org" + schema: + type: string - in: query name: v - type: array - items: - type: string description: The event IDs to backfill from. required: true - x-example: ["$abc123:matrix.org"] + example: + - $abc123:matrix.org + schema: + type: array + items: + type: string - in: query name: limit - type: integer description: The maximum number of PDUs to retrieve, including the given events. required: true - x-example: 2 + example: 2 + schema: + type: integer responses: - 200: + "200": description: |- A transaction containing the PDUs that preceded the given event(s), including the given event(s), up to the given limit. @@ -71,8 +64,10 @@ paths: Due to historical reasons, it is possible that events which were previously accepted would now be rejected by these limitations. The events should be rejected per usual by the `/send`, `/get_missing_events`, and remaining endpoints. - schema: - $ref: "definitions/unlimited_pdu_transaction.yaml" + content: + application/json: + schema: + $ref: definitions/unlimited_pdu_transaction.yaml "/get_missing_events/{roomId}": post: summary: Retrieves events that the sender is missing @@ -86,58 +81,85 @@ paths: parameters: - in: path name: roomId - type: string description: The room ID to search in. required: true - x-example: "!SomeRoom:matrix.org" - - in: body - name: body + example: "!SomeRoom:matrix.org" schema: - type: object - properties: - limit: - type: integer - description: The maximum number of events to retrieve. Defaults to 10. - example: 10 - min_depth: - type: integer - description: The minimum depth of events to retrieve. Defaults to 0. - example: 0 - earliest_events: - type: array - description: |- - The latest event IDs that the sender already has. These are skipped when retrieving - the previous events of `latest_events`. - items: - type: string - example: ["$missing_event:example.org"] - latest_events: - type: array - description: The event IDs to retrieve the previous events for. - items: - type: string - example: ["$event_that_has_the_missing_event_as_a_previous_event:example.org"] - required: ['earliest_events', 'latest_events'] + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + limit: + type: integer + description: The maximum number of events to retrieve. Defaults to 10. + example: 10 + min_depth: + type: integer + description: The minimum depth of events to retrieve. Defaults to 0. + example: 0 + earliest_events: + type: array + description: |- + The latest event IDs that the sender already has. These are skipped when retrieving + the previous events of `latest_events`. + items: + type: string + example: + - $missing_event:example.org + latest_events: + type: array + description: The event IDs to retrieve the previous events for. + items: + type: string + example: + - $event_that_has_the_missing_event_as_a_previous_event:example.org + required: + - earliest_events + - latest_events responses: - 200: + "200": description: |- The previous events for `latest_events`, excluding any `earliest_events`, up to the provided `limit`. - schema: - type: object - properties: - events: - type: array - description: |- - The missing events. The event format varies depending on the room version - check - the [room version specification](/rooms) for precise event formats. - items: - type: object - title: PDU - required: ['events'] - examples: - application/json: { - "events": [ - {"$ref": "examples/minimal_pdu.json"} - ] - } + content: + application/json: + schema: + type: object + properties: + events: + type: array + description: |- + The missing events. The event format varies depending on the room version - check + the [room version specification](/rooms) for precise event formats. + items: + type: object + title: PDU + required: + - events + examples: + response: + value: { + "events": [ + { + "$ref": "examples/minimal_pdu.json" + } + ] + } +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8448 + basePath: + default: /_matrix/federation/v1 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/server-server/definitions/unsigned_pdu_base.yaml b/data/api/server-server/definitions/unsigned_pdu_base.yaml index 20a3e83d..c21149f6 100644 --- a/data/api/server-server/definitions/unsigned_pdu_base.yaml +++ b/data/api/server-server/definitions/unsigned_pdu_base.yaml @@ -56,20 +56,21 @@ properties: maxItems: 2 minItems: 2 items: - - type: string - title: Event ID - example: "$abc123:matrix.org" - - type: object - title: Event Hash - example: { - "sha256": "Base64EncodedSha256HashesShouldBe43BytesLong" - } - properties: - sha256: - type: string - description: The event hash. - example: Base64EncodedSha256HashesShouldBe43BytesLong - required: ['sha256'] + anyOf: + - type: string + title: Event ID + example: "$abc123:matrix.org" + - type: object + title: Event Hash + example: { + "sha256": "Base64EncodedSha256HashesShouldBe43BytesLong" + } + properties: + sha256: + type: string + description: The event hash. + example: Base64EncodedSha256HashesShouldBe43BytesLong + required: ['sha256'] depth: type: integer description: |- @@ -91,20 +92,21 @@ properties: maxItems: 2 minItems: 2 items: - - type: string - title: Event ID - example: "$abc123:matrix.org" - - type: object - title: Event Hash - example: { - "sha256": "Base64EncodedSha256HashesShouldBe43BytesLong" - } - properties: - sha256: - type: string - description: The event hash. - example: Base64EncodedSha256HashesShouldBe43BytesLong - required: ['sha256'] + anyOf: + - type: string + title: Event ID + example: "$abc123:matrix.org" + - type: object + title: Event Hash + example: { + "sha256": "Base64EncodedSha256HashesShouldBe43BytesLong" + } + properties: + sha256: + type: string + description: The event hash. + example: Base64EncodedSha256HashesShouldBe43BytesLong + required: ['sha256'] redacts: type: string description: For redaction events, the ID of the event being redacted. diff --git a/data/api/server-server/event_auth.yaml b/data/api/server-server/event_auth.yaml index ae4db262..99d2b3ac 100644 --- a/data/api/server-server/event_auth.yaml +++ b/data/api/server-server/event_auth.yaml @@ -11,60 +11,68 @@ # 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. - -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Federation Event Authorization API" - version: "1.0.0" -host: localhost:8448 -schemes: - - https -basePath: /_matrix/federation/v1 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Federation Event Authorization API + version: 1.0.0 paths: "/event_auth/{roomId}/{eventId}": get: summary: Get the auth chain for a given event - description: |- - Retrieves the complete auth chain for a given event. + description: Retrieves the complete auth chain for a given event. operationId: getEventAuth security: - signedRequest: [] parameters: - in: path name: roomId - type: string description: The room ID to get the auth chain for. required: true - x-example: "!abc123:matrix.org" + example: "!abc123:matrix.org" + schema: + type: string - in: path name: eventId - type: string description: The event ID to get the auth chain of. required: true - x-example: "$helloworld:example.org" - responses: - 200: - description: The auth chain for the event. + example: $helloworld:example.org schema: - type: object - properties: - auth_chain: - type: array - description: |- - The [PDUs](/server-server-api/#pdus) forming the auth chain - of the given event. The event format varies depending on the - room version - check the [room version specification](/rooms) - for precise event formats. - items: - type: object - title: PDU - properties: {} - example: - $ref: "examples/minimal_pdu.json" - required: ['auth_chain'] + type: string + responses: + "200": + description: The auth chain for the event. + content: + application/json: + schema: + type: object + properties: + auth_chain: + type: array + description: |- + The [PDUs](/server-server-api/#pdus) forming the auth chain + of the given event. The event format varies depending on the + room version - check the [room version specification](/rooms) + for precise event formats. + items: + type: object + title: PDU + properties: {} + example: + $ref: examples/minimal_pdu.json + required: + - auth_chain +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8448 + basePath: + default: /_matrix/federation/v1 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/server-server/events.yaml b/data/api/server-server/events.yaml index 6d7ca45a..009df48b 100644 --- a/data/api/server-server/events.yaml +++ b/data/api/server-server/events.yaml @@ -11,84 +11,80 @@ # 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. - -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Federation Events API" - version: "1.0.0" -host: localhost:8448 -schemes: - - https -basePath: /_matrix/federation/v1 -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Federation Events API + version: 1.0.0 paths: "/state/{roomId}": get: summary: Get all the state of a given room - description: |- - Retrieves a snapshot of a room's state at a given event. + description: Retrieves a snapshot of a room's state at a given event. operationId: getRoomState security: - signedRequest: [] parameters: - in: path name: roomId - type: string description: The room ID to get state for. required: true - x-example: "!abc123:matrix.org" + example: "!abc123:matrix.org" + schema: + type: string - in: query name: event_id - type: string description: An event ID in the room to retrieve the state at. required: true - x-example: "$helloworld:matrix.org" + example: $helloworld:matrix.org + schema: + type: string responses: - 200: + "200": description: |- The fully resolved state for the room, prior to considering any state changes induced by the requested event. Includes the authorization chain for the events. - schema: - type: object - properties: - auth_chain: - type: array - description: |- - The full set of authorization events that make up the state - of the room, and their authorization events, recursively. Note that - events have a different format depending on the room version - - check the [room version specification](/rooms) for precise event formats. - items: - type: object - title: PDU - description: |- - The [PDUs](/server-server-api/#pdus) contained in the auth chain. The event format - varies depending on the room version - check the [room version specification](/rooms) - for precise event formats. - properties: {} - example: - $ref: "examples/minimal_pdu.json" - pdus: - type: array - description: |- - The fully resolved state of the room at the given event. Note that - events have a different format depending on the room version - - check the [room version specification](/rooms) for precise event formats. - items: - type: object - title: PDU - description: |- - The [PDUs](/server-server-api/#pdus) for the fully resolved state of the room. The event format - varies depending on the room version - check the [room version specification](/rooms) - for precise event formats. - properties: {} - example: - $ref: "examples/minimal_pdu.json" - required: ['auth_chain', 'pdus'] + content: + application/json: + schema: + type: object + properties: + auth_chain: + type: array + description: |- + The full set of authorization events that make up the state + of the room, and their authorization events, recursively. Note that + events have a different format depending on the room version - + check the [room version specification](/rooms) for precise event formats. + items: + type: object + title: PDU + description: |- + The [PDUs](/server-server-api/#pdus) contained in the auth chain. The event format + varies depending on the room version - check the [room version specification](/rooms) + for precise event formats. + properties: {} + example: + $ref: examples/minimal_pdu.json + pdus: + type: array + description: |- + The fully resolved state of the room at the given event. Note that + events have a different format depending on the room version - + check the [room version specification](/rooms) for precise event formats. + items: + type: object + title: PDU + description: |- + The [PDUs](/server-server-api/#pdus) for the fully resolved state of the room. The event format + varies depending on the room version - check the [room version specification](/rooms) + for precise event formats. + properties: {} + example: + $ref: examples/minimal_pdu.json + required: + - auth_chain + - pdus "/state_ids/{roomId}": get: summary: Get all the state event IDs of a given room @@ -102,72 +98,84 @@ paths: parameters: - in: path name: roomId - type: string description: The room ID to get state for. required: true - x-example: "!abc123:matrix.org" + example: "!abc123:matrix.org" + schema: + type: string - in: query name: event_id - type: string description: An event ID in the room to retrieve the state at. required: true - x-example: "$helloworld:matrix.org" + example: $helloworld:matrix.org + schema: + type: string responses: - 200: + "200": description: |- The fully resolved state for the room, prior to considering any state changes induced by the requested event. Includes the authorization chain for the events. - schema: - type: object - properties: - auth_chain_ids: - type: array - description: |- - The full set of authorization events that make up the state - of the room, and their authorization events, recursively. - items: - type: string - example: ["$an_event:example.org"] - pdu_ids: - type: array - description: |- - The fully resolved state of the room at the given event. - items: - type: string - example: ["$an_event:example.org"] - required: ['auth_chain_ids', 'pdu_ids'] - 404: + content: + application/json: + schema: + type: object + properties: + auth_chain_ids: + type: array + description: |- + The full set of authorization events that make up the state + of the room, and their authorization events, recursively. + items: + type: string + example: + - $an_event:example.org + pdu_ids: + type: array + description: The fully resolved state of the room at the given event. + items: + type: string + example: + - $an_event:example.org + required: + - auth_chain_ids + - pdu_ids + "404": description: |- The given `event_id` was not found or the server doesn't know about the state at that event to return anything useful. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Could not find event $Rqnc-F-dvnEYJTyHq_iKxU2bZ1CI92-kuZq3a5lr5Zg" - } - schema: - "$ref": "../client-server/definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Could not find event $Rqnc-F-dvnEYJTyHq_iKxU2bZ1CI92-kuZq3a5lr5Zg" + } "/event/{eventId}": get: summary: Get a single event - description: |- - Retrieves a single event. + description: Retrieves a single event. operationId: getEvent security: - signedRequest: [] parameters: - in: path name: eventId - type: string description: The event ID to get. required: true - x-example: "$abc123:matrix.org" - responses: - 200: - description: A transaction containing a single PDU which is the event requested. + example: $abc123:matrix.org schema: - $ref: "definitions/single_pdu_transaction.yaml" + type: string + responses: + "200": + description: A transaction containing a single PDU which is the event requested. + content: + application/json: + schema: + $ref: definitions/single_pdu_transaction.yaml "/timestamp_to_event/{roomId}": get: summary: Get the closest event ID to the given timestamp @@ -202,55 +210,79 @@ paths: - accessToken: [] parameters: - in: path - type: string name: roomId description: The ID of the room to search required: true - x-example: "!636q39766251:matrix.org" + example: "!636q39766251:matrix.org" + schema: + type: string - in: query - type: integer name: ts description: |- The timestamp to search from, as given in milliseconds since the Unix epoch. required: true - x-example: 1432684800000 + example: 1432684800000 + schema: + type: integer - in: query - type: string - enum: [f, b] name: dir - description: |- - The direction in which to search. `f` for forwards, `b` for backwards. + description: The direction in which to search. `f` for forwards, `b` for + backwards. required: true - x-example: f + example: f + schema: + type: string + enum: + - f + - b responses: - 200: - description: |- - An event was found matching the search parameters. - schema: - type: object - properties: - event_id: - type: string - description: |- - The ID of the event found - origin_server_ts: - type: integer - description: |- - The event's timestamp, in milliseconds since the Unix epoch. - required: ['event_id', 'origin_server_ts'] - examples: - application/json: { - "event_id": "$143273582443PhrSn:example.org", - "origin_server_ts": 1432735824653 - } - 404: - description: |- - No event was found. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Unable to find event from 1432684800000 in forward direction" - } - schema: - "$ref": "../client-server/definitions/errors/error.yaml" + "200": + description: An event was found matching the search parameters. + content: + application/json: + schema: + type: object + properties: + event_id: + type: string + description: The ID of the event found + origin_server_ts: + type: integer + description: The event's timestamp, in milliseconds since the Unix epoch. + required: + - event_id + - origin_server_ts + examples: + response: + value: { + "event_id": "$143273582443PhrSn:example.org", + "origin_server_ts": 1432735824653 + } + "404": + description: No event was found. + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Unable to find event from 1432684800000 in forward direction" + } +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8448 + basePath: + default: /_matrix/federation/v1 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/server-server/invites-v1.yaml b/data/api/server-server/invites-v1.yaml index ee439aa2..270682d9 100644 --- a/data/api/server-server/invites-v1.yaml +++ b/data/api/server-server/invites-v1.yaml @@ -11,21 +11,10 @@ # 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. - -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Federation Invite User To Room API" - version: "1.0.0" -host: localhost:8448 -schemes: - - https -basePath: /_matrix/federation/v1 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Federation Invite User To Room API + version: 1.0.0 paths: "/invite/{roomId}/{eventId}": put: @@ -49,134 +38,160 @@ paths: parameters: - in: path name: roomId - type: string description: The room ID that the user is being invited to. required: true - x-example: "!abc123:matrix.org" + example: "!abc123:matrix.org" + schema: + type: string - in: path name: eventId - type: string description: The event ID for the invite event, generated by the inviting server. required: true - x-example: "$abc123:example.org" - - in: body - name: body - type: object - required: true + example: $abc123:example.org schema: - allOf: - - $ref: "definitions/invite_event.yaml" - - type: object - properties: - unsigned: - type: object - title: UnsignedData - description: |- - Information included alongside the event that is not signed. May include more - than what is listed here. - properties: - invite_room_state: - type: array - description: |- - An optional list of [stripped state events](/client-server-api/#stripped-state) - to help the receiver of the invite identify the room. - items: - $ref: "../../event-schemas/schema/core-event-schema/stripped_state.yaml" - example: - $ref: "../../event-schemas/examples/invite_room_state.json" - example: { - "room_id": "!somewhere:example.org", - "type": "m.room.member", - "state_key": "@joe:elsewhere.com", - "origin": "example.org", - "origin_server_ts": 1549041175876, - "sender": "@someone:example.org", - "content": { - "membership": "invite" - }, - "signatures": { - "example.com": { - "ed25519:key_version": "SomeSignatureHere" + type: string + requestBody: + content: + application/json: + schema: + allOf: + - $ref: definitions/invite_event.yaml + - type: object + properties: + unsigned: + type: object + title: UnsignedData + description: |- + Information included alongside the event that is not signed. May include more + than what is listed here. + properties: + invite_room_state: + type: array + description: |- + An optional list of [stripped state events](/client-server-api/#stripped-state) + to help the receiver of the invite identify the room. + items: + $ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml + example: + $ref: ../../event-schemas/examples/invite_room_state.json + type: object + example: { + "room_id": "!somewhere:example.org", + "type": "m.room.member", + "state_key": "@joe:elsewhere.com", + "origin": "example.org", + "origin_server_ts": 1549041175876, + "sender": "@someone:example.org", + "content": { + "membership": "invite" }, + "signatures": { + "example.com": { + "ed25519:key_version": "SomeSignatureHere" + }, + } } - } + required: true responses: - 200: + "200": description: |- The event with the invited server's signature added. All other fields of the events should remain untouched. Note that events have a different format depending on the room version - check the [room version specification](/rooms) for precise event formats. - schema: - type: array - minItems: 2 - maxItems: 2 - items: - - type: integer - description: The value `200`. - example: 200 - - type: object - description: An object containing the signed invite event. - title: Event Container - properties: - event: - $ref: "definitions/invite_event.yaml" - required: ['event'] - examples: - application/json: [ - 200, - { - "event": { - "room_id": "!somewhere:example.org", - "type": "m.room.member", - "state_key": "@someone:example.org", - "origin": "example.org", - "origin_server_ts": 1549041175876, - "sender": "@someone:example.org", - "unsigned": { - "invite_room_state": [ - { - "type": "m.room.name", - "sender": "@bob:example.org", - "state_key": "", + content: + application/json: + schema: + type: array + minItems: 2 + maxItems: 2 + items: + anyOf: + - type: integer + description: The value `200`. + example: 200 + - type: object + description: An object containing the signed invite event. + title: Event Container + properties: + event: + $ref: definitions/invite_event.yaml + required: + - event + examples: + response: + value: [ + 200, + { + "event": { + "room_id": "!somewhere:example.org", + "type": "m.room.member", + "state_key": "@someone:example.org", + "origin": "example.org", + "origin_server_ts": 1549041175876, + "sender": "@someone:example.org", + "unsigned": { + "invite_room_state": [ + { + "type": "m.room.name", + "sender": "@bob:example.org", + "state_key": "", + "content": { + "name": "Example Room" + } + }, + { + "type": "m.room.join_rules", + "sender": "@bob:example.org", + "state_key": "", + "content": { + "join_rule": "invite" + } + } + ] + }, "content": { - "name": "Example Room" - } - }, - { - "type": "m.room.join_rules", - "sender": "@bob:example.org", - "state_key": "", - "content": { - "join_rule": "invite" + "membership": "invite" + }, + "signatures": { + "example.com": { + "ed25519:key_version": "SomeSignatureHere" + }, + "elsewhere.com": { + "ed25519:k3y_versi0n": "SomeOtherSignatureHere" + } } } - ] - }, - "content": { - "membership": "invite" - }, - "signatures": { - "example.com": { - "ed25519:key_version": "SomeSignatureHere" - }, - "elsewhere.com": { - "ed25519:k3y_versi0n": "SomeOtherSignatureHere" } - } - } - } - ] - 403: + ] + "403": description: |- The invite is not allowed. This could be for a number of reasons, including: * The sender is not allowed to send invites to the target user/homeserver. * The homeserver does not permit anyone to invite its users. * The homeserver refuses to participate in the room. - schema: - $ref: "../client-server/definitions/errors/error.yaml" - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "User cannot invite the target user." - } + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "User cannot invite the target user." + } +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8448 + basePath: + default: /_matrix/federation/v1 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/server-server/invites-v2.yaml b/data/api/server-server/invites-v2.yaml index afb8a571..91dfca3a 100644 --- a/data/api/server-server/invites-v2.yaml +++ b/data/api/server-server/invites-v2.yaml @@ -11,21 +11,10 @@ # 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. - -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Federation Invite User To Room API" - version: "1.0.0" -host: localhost:8448 -schemes: - - https -basePath: /_matrix/federation/v2 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Federation Invite User To Room API + version: 1.0.0 paths: "/invite/{roomId}/{eventId}": put: @@ -53,101 +42,51 @@ paths: parameters: - in: path name: roomId - type: string description: The room ID that the user is being invited to. required: true - x-example: "!abc123:matrix.org" + example: "!abc123:matrix.org" + schema: + type: string - in: path name: eventId - type: string description: The event ID for the invite event, generated by the inviting server. required: true - x-example: "$abc123:example.org" - - in: body - name: body - type: object - required: true + example: $abc123:example.org schema: - type: object - properties: - room_version: - type: string - description: The version of the room where the user is being invited to. - example: "2" - event: - $ref: "definitions/invite_event.yaml" - invite_room_state: - type: array - description: |- - An optional list of [stripped state events](/client-server-api/#stripped-state) - to help the receiver of the invite identify the room. - items: - $ref: "../../event-schemas/schema/core-event-schema/stripped_state.yaml" - example: - $ref: "../../event-schemas/examples/invite_room_state.json" - required: ['room_version', 'event'] - example: { - "room_version": "2", - "event": { - "room_id": "!somewhere:example.org", - "type": "m.room.member", - "state_key": "@joe:elsewhere.com", - "origin": "example.org", - "origin_server_ts": 1549041175876, - "sender": "@someone:example.org", - "content": { - "membership": "invite" - }, - "signatures": { - "example.com": { - "ed25519:key_version": "SomeSignatureHere" - }, - } - } - } - responses: - 200: - description: |- - The event with the invited server's signature added. All other fields of the events - should remain untouched. Note that events have a different format depending on the - room version - check the [room version specification](/rooms) for precise event formats. - schema: - type: object - description: An object containing the signed invite event. - title: Event Container - properties: - event: - $ref: "definitions/invite_event.yaml" - required: ['event'] - examples: - application/json: { - "event": { + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + room_version: + type: string + description: The version of the room where the user is being invited to. + example: "2" + event: + $ref: definitions/invite_event.yaml + invite_room_state: + type: array + description: |- + An optional list of [stripped state events](/client-server-api/#stripped-state) + to help the receiver of the invite identify the room. + items: + $ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml + example: + $ref: ../../event-schemas/examples/invite_room_state.json + required: + - room_version + - event + example: { + "room_version": "2", + "event": { "room_id": "!somewhere:example.org", "type": "m.room.member", - "state_key": "@someone:example.org", + "state_key": "@joe:elsewhere.com", "origin": "example.org", "origin_server_ts": 1549041175876, "sender": "@someone:example.org", - "unsigned": { - "invite_room_state": [ - { - "type": "m.room.name", - "sender": "@bob:example.org", - "state_key": "", - "content": { - "name": "Example Room" - } - }, - { - "type": "m.room.join_rules", - "sender": "@bob:example.org", - "state_key": "", - "content": { - "join_rule": "invite" - } - } - ] - }, "content": { "membership": "invite" }, @@ -155,27 +94,71 @@ paths: "example.com": { "ed25519:key_version": "SomeSignatureHere" }, - "elsewhere.com": { - "ed25519:k3y_versi0n": "SomeOtherSignatureHere" - } } } } - 403: + required: true + responses: + "200": description: |- - The invite is not allowed. This could be for a number of reasons, including: - - * The sender is not allowed to send invites to the target user/homeserver. - * The homeserver does not permit anyone to invite its users. - * The homeserver refuses to participate in the room. - schema: - $ref: "../client-server/definitions/errors/error.yaml" - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "User cannot invite the target user." - } - 400: + The event with the invited server's signature added. All other fields of the events + should remain untouched. Note that events have a different format depending on the + room version - check the [room version specification](/rooms) for precise event formats. + content: + application/json: + schema: + type: object + description: An object containing the signed invite event. + title: Event Container + properties: + event: + $ref: definitions/invite_event.yaml + required: + - event + examples: + response: + value: { + "event": { + "room_id": "!somewhere:example.org", + "type": "m.room.member", + "state_key": "@someone:example.org", + "origin": "example.org", + "origin_server_ts": 1549041175876, + "sender": "@someone:example.org", + "unsigned": { + "invite_room_state": [ + { + "type": "m.room.name", + "sender": "@bob:example.org", + "state_key": "", + "content": { + "name": "Example Room" + } + }, + { + "type": "m.room.join_rules", + "sender": "@bob:example.org", + "state_key": "", + "content": { + "join_rule": "invite" + } + } + ] + }, + "content": { + "membership": "invite" + }, + "signatures": { + "example.com": { + "ed25519:key_version": "SomeSignatureHere" + }, + "elsewhere.com": { + "ed25519:k3y_versi0n": "SomeOtherSignatureHere" + } + } + } + } + "400": description: |- The request is invalid or the room the server is attempting to join has a version that is not listed in the `ver` @@ -183,19 +166,54 @@ paths: The error should be passed through to clients so that they may give better feedback to users. - schema: - allOf: - - $ref: "../client-server/definitions/errors/error.yaml" - - type: object - properties: - room_version: - type: string - description: |- - The version of the room. Required if the `errcode` - is `M_INCOMPATIBLE_ROOM_VERSION`. - examples: - application/json: { - "errcode": "M_INCOMPATIBLE_ROOM_VERSION", - "error": "Your homeserver does not support the features required to join this room", - "room_version": "3" - } + content: + application/json: + schema: + allOf: + - $ref: ../client-server/definitions/errors/error.yaml + - type: object + properties: + room_version: + type: string + description: |- + The version of the room. Required if the `errcode` + is `M_INCOMPATIBLE_ROOM_VERSION`. + examples: + response: + value: { + "errcode": "M_INCOMPATIBLE_ROOM_VERSION", + "error": "Your homeserver does not support the features required to join this room", + "room_version": "3" + } + "403": + description: |- + The invite is not allowed. This could be for a number of reasons, including: + + * The sender is not allowed to send invites to the target user/homeserver. + * The homeserver does not permit anyone to invite its users. + * The homeserver refuses to participate in the room. + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "User cannot invite the target user." + } +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8448 + basePath: + default: /_matrix/federation/v2 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/server-server/joins-v1.yaml b/data/api/server-server/joins-v1.yaml index c9480c49..d04e2ced 100644 --- a/data/api/server-server/joins-v1.yaml +++ b/data/api/server-server/joins-v1.yaml @@ -12,21 +12,10 @@ # 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. - -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Federation Join Room API" - version: "1.0.0" -host: localhost:8448 -schemes: - - https -basePath: /_matrix/federation/v1 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Federation Join Room API + version: 1.0.0 paths: "/make_join/{roomId}/{userId}": get: @@ -40,118 +29,128 @@ paths: parameters: - in: path name: roomId - type: string description: The room ID that is about to be joined. required: true - x-example: "!abc123:matrix.org" + example: "!abc123:matrix.org" + schema: + type: string - in: path name: userId - type: string description: The user ID the join event will be for. required: true - x-example: "@someone:example.org" - - in: query - type: array - items: + example: "@someone:example.org" + schema: type: string + - in: query name: ver description: |- The room versions the sending server has support for. Defaults to `[1]`. - x-example: ["1", "2"] + example: + - "1" + - "2" + schema: + type: array + items: + type: string responses: - 200: + "200": description: |- A template to be used for the rest of the [Joining Rooms](/server-server-api/#joining-rooms) handshake. Note that events have a different format depending on the room version - check the [room version specification](/rooms) for precise event formats. **The response body here describes the common event fields in more detail and may be missing other required fields for a PDU.** - schema: - type: object - properties: - room_version: - type: string - description: |- - The version of the room where the server is trying to join. If not provided, - the room version is assumed to be either "1" or "2". - example: "2" - event: - description: |- - An unsigned template event. Note that events have a different format - depending on the room version - check the [room version specification](/rooms) - for precise event formats. + content: + application/json: + schema: type: object - title: Event Template properties: - sender: + room_version: type: string - description: The user ID of the joining member. - example: "@someone:example.org" - origin: - type: string - description: The name of the resident homeserver. - example: "matrix.org" - origin_server_ts: - type: integer - format: int64 - description: A timestamp added by the resident homeserver. - example: 1234567890 - type: - type: string - description: The value `m.room.member`. - example: "m.room.member" - state_key: - type: string - description: The user ID of the joining member. - example: "@someone:example.org" - content: + description: |- + The version of the room where the server is trying to join. If not provided, + the room version is assumed to be either "1" or "2". + example: "2" + event: + description: |- + An unsigned template event. Note that events have a different format + depending on the room version - check the [room version specification](/rooms) + for precise event formats. type: object - title: Membership Event Content - description: The content of the event. - example: {"membership": "join"} + title: Event Template properties: - membership: + sender: type: string - description: The value `join`. - example: "join" - join_authorised_via_users_server: + description: The user ID of the joining member. + example: "@someone:example.org" + origin: type: string - x-addedInMatrixVersion: "1.2" - description: |- - Required if the room is [restricted](/client-server-api/#restricted-rooms) - and is joining through one of the conditions available. If the - user is responding to an invite, this is not required. + description: The name of the resident homeserver. + example: matrix.org + origin_server_ts: + type: integer + format: int64 + description: A timestamp added by the resident homeserver. + example: 1234567890 + type: + type: string + description: The value `m.room.member`. + example: m.room.member + state_key: + type: string + description: The user ID of the joining member. + example: "@someone:example.org" + content: + type: object + title: Membership Event Content + description: The content of the event. + example: + membership: join + properties: + membership: + type: string + description: The value `join`. + example: join + join_authorised_via_users_server: + type: string + x-addedInMatrixVersion: "1.2" + description: |- + Required if the room is [restricted](/client-server-api/#restricted-rooms) + and is joining through one of the conditions available. If the + user is responding to an invite, this is not required. - An arbitrary user ID belonging to the resident server in - the room being joined that is able to issue invites to other - users. This is used in later validation of the auth rules for - the `m.room.member` event. - required: ['membership'] - required: - - state_key - - origin - - origin_server_ts - - type - - content - - sender - examples: - application/json: { - "room_version": "2", - "event": { - "room_id": "!somewhere:example.org", - "type": "m.room.member", - "state_key": "@someone:example.org", - "origin": "example.org", - "origin_server_ts": 1549041175876, - "sender": "@someone:example.org", - "content": { - "membership": "join", - "join_authorised_via_users_server": "@anyone:resident.example.org" - } - } - } - 400: + An arbitrary user ID belonging to the resident server in + the room being joined that is able to issue invites to other + users. This is used in later validation of the auth rules for + the `m.room.member` event. + required: + - membership + required: + - state_key + - origin + - origin_server_ts + - type + - content + - sender + examples: + response: + value: { + "room_version": "2", + "event": { + "room_id": "!somewhere:example.org", + "type": "m.room.member", + "state_key": "@someone:example.org", + "origin": "example.org", + "origin_server_ts": 1549041175876, + "sender": "@someone:example.org", + "content": { + "membership": "join", + "join_authorised_via_users_server": "@anyone:resident.example.org" + } + } + } + "400": description: |- The request is invalid, the room the server is attempting to join has a version that is not listed in the `ver` @@ -177,45 +176,53 @@ paths: resident server would be unable to meet the auth rules governing `join_authorised_via_users_server` on the resulting `m.room.member` event. - schema: - allOf: - - $ref: "../client-server/definitions/errors/error.yaml" - - type: object - properties: - room_version: - type: string - description: |- - The version of the room. Required if the `errcode` - is `M_INCOMPATIBLE_ROOM_VERSION`. - examples: - application/json: { - "errcode": "M_INCOMPATIBLE_ROOM_VERSION", - "error": "Your homeserver does not support the features required to join this room", - "room_version": "3" - } - 403: - schema: - $ref: "../client-server/definitions/errors/error.yaml" + content: + application/json: + schema: + allOf: + - $ref: ../client-server/definitions/errors/error.yaml + - type: object + properties: + room_version: + type: string + description: |- + The version of the room. Required if the `errcode` + is `M_INCOMPATIBLE_ROOM_VERSION`. + examples: + response: + value: { + "errcode": "M_INCOMPATIBLE_ROOM_VERSION", + "error": "Your homeserver does not support the features required to join this room", + "room_version": "3" + } + "403": description: |- The room that the joining server is attempting to join does not permit the user to join. - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "You are not invited to this room", - } - 404: - schema: - $ref: "../client-server/definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "You are not invited to this room" + } + "404": description: |- The room that the joining server is attempting to join is unknown to the receiving server. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Unknown room", - } - + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Unknown room" + } "/send_join/{roomId}/{eventId}": put: deprecated: true @@ -237,150 +244,167 @@ paths: parameters: - in: path name: roomId - type: string description: The room ID that is about to be joined. required: true - x-example: "!abc123:matrix.org" + example: "!abc123:matrix.org" + schema: + type: string - in: path name: eventId - type: string description: The event ID for the join event. required: true - x-example: "$abc123:example.org" - - in: body - name: body - type: object - required: true + example: $abc123:example.org schema: - type: object - properties: - sender: - type: string - description: The user ID of the joining member. - example: "@someone:example.org" - origin: - type: string - description: The name of the joining homeserver. - example: "matrix.org" - origin_server_ts: - type: integer - format: int64 - description: A timestamp added by the joining homeserver. - example: 1234567890 - type: - type: string - description: The value `m.room.member`. - example: "m.room.member" - state_key: - type: string - description: The user ID of the joining member. - example: "@someone:example.org" - content: - type: object - title: Membership Event Content - description: The content of the event. - example: {"membership": "join"} - properties: - membership: - type: string - description: The value `join`. - example: "join" - join_authorised_via_users_server: - type: string - x-addedInMatrixVersion: "1.2" - description: |- - Required if the room is [restricted](/client-server-api/#restricted-rooms) - and is joining through one of the conditions available. If the - user is responding to an invite, this is not required. + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + sender: + type: string + description: The user ID of the joining member. + example: "@someone:example.org" + origin: + type: string + description: The name of the joining homeserver. + example: matrix.org + origin_server_ts: + type: integer + format: int64 + description: A timestamp added by the joining homeserver. + example: 1234567890 + type: + type: string + description: The value `m.room.member`. + example: m.room.member + state_key: + type: string + description: The user ID of the joining member. + example: "@someone:example.org" + content: + type: object + title: Membership Event Content + description: The content of the event. + example: + membership: join + properties: + membership: + type: string + description: The value `join`. + example: join + join_authorised_via_users_server: + type: string + x-addedInMatrixVersion: "1.2" + description: |- + Required if the room is [restricted](/client-server-api/#restricted-rooms) + and is joining through one of the conditions available. If the + user is responding to an invite, this is not required. - An arbitrary user ID belonging to the resident server in - the room being joined that is able to issue invites to other - users. This is used in later validation of the auth rules for - the `m.room.member` event. + An arbitrary user ID belonging to the resident server in + the room being joined that is able to issue invites to other + users. This is used in later validation of the auth rules for + the `m.room.member` event. - The resident server which owns the provided user ID must have a - valid signature on the event. If the resident server is receiving - the `/send_join` request, the signature must be added before sending - or persisting the event to other servers. - required: ['membership'] - required: - - state_key - - sender - - origin - - origin_server_ts - - type - - content - example: { - "room_id": "!somewhere:example.org", - "type": "m.room.member", - "state_key": "@someone:example.org", - "origin": "example.org", - "origin_server_ts": 1549041175876, - "sender": "@someone:example.org", - "content": { - "membership": "join", - "join_authorised_via_users_server": "@anyone:resident.example.org" - } - } + The resident server which owns the provided user ID must have a + valid signature on the event. If the resident server is receiving + the `/send_join` request, the signature must be added before sending + or persisting the event to other servers. + required: + - membership + required: + - state_key + - sender + - origin + - origin_server_ts + - type + - content + required: true responses: - 200: - description: |- - The join event has been accepted into the room. - schema: - type: array - minItems: 2 - maxItems: 2 - items: - - type: integer - description: The value `200`. - example: 200 - - type: object - title: Room State - description: The state for the room. - properties: - origin: - type: string - description: The resident server's DNS name. - auth_chain: - type: array - description: |- - The auth chain for the entire current room state prior to the join event. + "200": + description: The join event has been accepted into the room. + content: + application/json: + schema: + type: array + minItems: 2 + maxItems: 2 + items: + anyOf: + - type: integer + description: The value `200`. + example: 200 + - type: object + title: Room State + description: The state for the room. + properties: + origin: + type: string + description: The resident server's DNS name. + auth_chain: + type: array + description: |- + The auth chain for the entire current room state prior to the join event. - Note that events have a different format depending on the room version - check the - [room version specification](/rooms) for precise event formats. - items: - type: object - title: PDU - description: |- - The [PDUs](/server-server-api/#pdus) that make up the auth chain. The event format varies depending - on the room version - check the [room version specification](/rooms) for precise event formats. - schema: - type: object - properties: {} - state: - type: array - description: |- - The resolved current room state prior to the join event. + Note that events have a different format depending on the room version - check the + [room version specification](/rooms) for precise event formats. + items: + type: object + title: PDU + description: |- + The [PDUs](/server-server-api/#pdus) that make up the auth chain. The event format varies depending + on the room version - check the [room version specification](/rooms) for precise event formats. + state: + type: array + description: |- + The resolved current room state prior to the join event. - The event format varies depending on the room version - check the [room version specification](/rooms) - for precise event formats. - items: - type: object - title: PDU - description: |- - The [PDUs](/server-server-api/#pdus) for the fully resolved state of the room. The event format varies depending - on the room version - check the [room version specification](/rooms) for precise event formats. - schema: - type: object - properties: {} - required: ["auth_chain", "state", "origin"] - examples: - application/json: [ - 200, - { - "origin": "matrix.org", - "auth_chain": [{"$ref": "examples/minimal_pdu.json"}], - "state": [{"$ref": "examples/minimal_pdu.json"}], - "event": {"$ref": "examples/pdu_v4_join_membership.json"} - } - ] + The event format varies depending on the room version - check the [room version specification](/rooms) + for precise event formats. + items: + type: object + title: PDU + description: |- + The [PDUs](/server-server-api/#pdus) for the fully resolved state of the room. The event format varies depending + on the room version - check the [room version specification](/rooms) for precise event formats. + required: + - auth_chain + - state + - origin + examples: + response: + value: [ + 200, + { + "origin": "matrix.org", + "auth_chain": [ + { + "$ref": "examples/minimal_pdu.json" + } + ], + "state": [ + { + "$ref": "examples/minimal_pdu.json" + } + ], + "event": { + "$ref": "examples/pdu_v4_join_membership.json" + } + } + ] +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8448 + basePath: + default: /_matrix/federation/v1 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/server-server/joins-v2.yaml b/data/api/server-server/joins-v2.yaml index 3a8a47b1..32819193 100644 --- a/data/api/server-server/joins-v2.yaml +++ b/data/api/server-server/joins-v2.yaml @@ -12,21 +12,10 @@ # 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. - -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Federation Join Room API" - version: "1.0.0" -host: localhost:8448 -schemes: - - https -basePath: /_matrix/federation/v2 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Federation Join Room API + version: 1.0.0 paths: # Note: there is no v2 of make_join (yet) "/send_join/{roomId}/{eventId}": @@ -55,19 +44,20 @@ paths: parameters: - in: path name: roomId - type: string description: The room ID that is about to be joined. required: true - x-example: "!abc123:matrix.org" + example: "!abc123:matrix.org" + schema: + type: string - in: path name: eventId - type: string description: The event ID for the join event. required: true - x-example: "$abc123:example.org" + example: $abc123:example.org + schema: + type: string - in: query name: omit_members - type: boolean description: |- If `true`, indicates that that calling server can accept a reduced response, in which membership events are omitted from `state` and @@ -83,83 +73,180 @@ paths: response `state` field, and include the auth chains for these membership events in the response `auth_chain` field. x-addedInMatrixVersion: "1.6" - - in: body - name: body - type: object - required: true schema: - type: object - properties: - sender: - type: string - description: The user ID of the joining member. - example: "@someone:example.org" - origin: - type: string - description: The name of the joining homeserver. - example: "matrix.org" - origin_server_ts: - type: integer - format: int64 - description: A timestamp added by the joining homeserver. - example: 1234567890 - type: - type: string - description: The value `m.room.member`. - example: "m.room.member" - state_key: - type: string - description: The user ID of the joining member. - example: "@someone:example.org" - content: + type: boolean + requestBody: + content: + application/json: + schema: + type: object + properties: + sender: + type: string + description: The user ID of the joining member. + example: "@someone:example.org" + origin: + type: string + description: The name of the joining homeserver. + example: matrix.org + origin_server_ts: + type: integer + format: int64 + description: A timestamp added by the joining homeserver. + example: 1234567890 + type: + type: string + description: The value `m.room.member`. + example: m.room.member + state_key: + type: string + description: The user ID of the joining member. + example: "@someone:example.org" + content: + type: object + title: Membership Event Content + description: The content of the event. + example: + membership: join + properties: + membership: + type: string + description: The value `join`. + example: join + join_authorised_via_users_server: + type: string + x-addedInMatrixVersion: "1.2" + description: |- + Required if the room is [restricted](/client-server-api/#restricted-rooms) + and is joining through one of the conditions available. If the + user is responding to an invite, this is not required. + + An arbitrary user ID belonging to the resident server in + the room being joined that is able to issue invites to other + users. This is used in later validation of the auth rules for + the `m.room.member` event. + + The resident server which owns the provided user ID must have a + valid signature on the event. If the resident server is receiving + the `/send_join` request, the signature must be added before sending + or persisting the event to other servers. + required: + - membership + required: + - state_key + - sender + - origin + - origin_server_ts + - type + - content + example: { + "room_id": "!somewhere:example.org", + "type": "m.room.member", + "state_key": "@someone:example.org", + "origin": "example.org", + "origin_server_ts": 1549041175876, + "sender": "@someone:example.org", + "content": { + "membership": "join", + "join_authorised_via_users_server": "@anyone:resident.example.org" + } + } + required: true + responses: + "200": + description: The join event has been accepted into the room. + content: + application/json: + schema: type: object - title: Membership Event Content - description: The content of the event. - example: {"membership": "join"} properties: - membership: - type: string - description: The value `join`. - example: "join" - join_authorised_via_users_server: + origin: type: string + description: The resident server's DNS name. + members_omitted: + type: boolean + description: "`true` if `m.room.member` events have been omitted from `state`." + x-addedInMatrixVersion: "1.6" + auth_chain: + type: array + description: |- + All events in the auth chain for the new join event, as well + as those in the auth chains for any events returned in + `state`. + + If the `omit_members` query parameter was set to `true`, then + any events that are returned in `state` may be omitted from + `auth_chain`, whether or not membership events are omitted + from `state`. + + Note that events have a different format depending on the room version - check the + [room version specification](/rooms) for precise event formats. + items: + type: object + title: PDU + x-changedInMatrixVersion: + "1.6": |- + reworded to include only consider state events returned in + `state`, and to allow elision of redundant events. + state: + type: array + description: |- + The resolved current room state prior to the join event. + + If the request had `omit_members` set to `true`, events of + type `m.room.member` may be omitted from the response to + reduce the size of the response. If this is done, + `members_omitted` must be set to `true`. + items: + type: object + title: PDU + x-changedInMatrixVersion: + "1.6": permit omission of membership events. + event: + type: object + title: SignedMembershipEvent x-addedInMatrixVersion: "1.2" description: |- - Required if the room is [restricted](/client-server-api/#restricted-rooms) - and is joining through one of the conditions available. If the - user is responding to an invite, this is not required. + Required if the room version [supports restricted join rules](/rooms/#feature-matrix). The signed + copy of the membership event sent to other servers by the resident server, including the resident + server's signature. + servers_in_room: + type: array + x-addedInMatrixVersion: "1.6" + description: |- + **Required** if `members_omitted` is true. - An arbitrary user ID belonging to the resident server in - the room being joined that is able to issue invites to other - users. This is used in later validation of the auth rules for - the `m.room.member` event. - - The resident server which owns the provided user ID must have a - valid signature on the event. If the resident server is receiving - the `/send_join` request, the signature must be added before sending - or persisting the event to other servers. - required: ['membership'] - required: - - state_key - - sender - - origin - - origin_server_ts - - type - - content - example: { - "room_id": "!somewhere:example.org", - "type": "m.room.member", - "state_key": "@someone:example.org", - "origin": "example.org", - "origin_server_ts": 1549041175876, - "sender": "@someone:example.org", - "content": { - "membership": "join", - "join_authorised_via_users_server": "@anyone:resident.example.org" - } - } - responses: - 400: + A list of the servers active in the room (ie, those with joined members) before the join. + items: + type: string + required: + - auth_chain + - state + - origin + examples: + response: + value: { + "origin": "matrix.org", + "auth_chain": [ + { + "$ref": "examples/minimal_pdu.json" + } + ], + "state": [ + { + "$ref": "examples/minimal_pdu.json" + } + ], + "event": { + "$ref": "examples/pdu_v4_join_membership.json" + }, + "members_omitted": true, + "servers_in_room": [ + "matrix.org", + "example.com" + ] + } + "400": description: |- The request is invalid in some way. @@ -182,103 +269,42 @@ paths: resident server would be unable to meet the auth rules governing `join_authorised_via_users_server` on the resulting `m.room.member` event. - schema: - $ref: "../client-server/definitions/errors/error.yaml" - examples: - application/json: { - "errcode": "M_UNABLE_TO_GRANT_JOIN", - "error": "This server cannot send invites to you." - } - 403: - schema: - $ref: "../client-server/definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_UNABLE_TO_GRANT_JOIN", + "error": "This server cannot send invites to you." + } + "403": description: |- The room that the joining server is attempting to join does not permit the user to join. - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "You are not invited to this room", - } - 200: - description: |- - The join event has been accepted into the room. - schema: - type: object - properties: - origin: - type: string - description: The resident server's DNS name. - members_omitted: - type: boolean - description: "`true` if `m.room.member` events have been omitted from `state`." - x-addedInMatrixVersion: "1.6" - auth_chain: - type: array - description: |- - All events in the auth chain for the new join event, as well - as those in the auth chains for any events returned in - `state`. - - If the `omit_members` query parameter was set to `true`, then - any events that are returned in `state` may be omitted from - `auth_chain`, whether or not membership events are omitted - from `state`. - - Note that events have a different format depending on the room version - check the - [room version specification](/rooms) for precise event formats. - items: - type: object - title: PDU - schema: - type: object - properties: {} - x-changedInMatrixVersion: - "1.6": |- - reworded to include only consider state events returned in - `state`, and to allow elision of redundant events. - state: - type: array - description: |- - The resolved current room state prior to the join event. - - If the request had `omit_members` set to `true`, events of - type `m.room.member` may be omitted from the response to - reduce the size of the response. If this is done, - `members_omitted` must be set to `true`. - items: - type: object - title: PDU - schema: - type: object - properties: {} - x-changedInMatrixVersion: - "1.6": |- - permit omission of membership events. - event: - type: object - title: SignedMembershipEvent - x-addedInMatrixVersion: "1.2" - description: |- - Required if the room version [supports restricted join rules](/rooms/#feature-matrix). The signed - copy of the membership event sent to other servers by the resident server, including the resident - server's signature. - servers_in_room: - type: array - x-addedInMatrixVersion: "1.6" - description: |- - **Required** if `members_omitted` is true. - - A list of the servers active in the room (ie, those with joined members) before the join. - items: - type: string - required: ["auth_chain", "state", "origin"] - examples: - application/json: { - "origin": "matrix.org", - "auth_chain": [{"$ref": "examples/minimal_pdu.json"}], - "state": [{"$ref": "examples/minimal_pdu.json"}], - "event": {"$ref": "examples/pdu_v4_join_membership.json"}, - "members_omitted": true, - "servers_in_room": ["matrix.org", "example.com"] - } + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "You are not invited to this room" + } +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8448 + basePath: + default: /_matrix/federation/v2 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/server-server/keys_query.yaml b/data/api/server-server/keys_query.yaml index 5857ce31..ed9e6302 100644 --- a/data/api/server-server/keys_query.yaml +++ b/data/api/server-server/keys_query.yaml @@ -11,19 +11,10 @@ # 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. - -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Federation Key Exchange API" - version: "1.0.0" -host: localhost:8448 -schemes: - - https -basePath: /_matrix/key/v2 -consumes: - - application/json -produces: - - application/json + title: Matrix Federation Key Exchange API + version: 1.0.0 paths: "/query/{serverName}": get: @@ -35,88 +26,106 @@ paths: parameters: - in: path name: serverName - type: string description: The server's DNS name to query required: true - x-example: matrix.org + example: matrix.org + schema: + type: string - in: query name: minimum_valid_until_ts - type: integer - format: int64 description: |- A millisecond POSIX timestamp in milliseconds indicating when the returned certificates will need to be valid until to be useful to the requesting server. If not supplied, the current time as determined by the notary server is used. required: false - x-example: 1234567890 + example: 1234567890 + schema: + type: integer + format: int64 responses: - 200: + "200": description: |- The keys for the server, or an empty array if the server could not be reached and no cached keys were available. - schema: - $ref: "definitions/keys_query_response.yaml" - "/query": + content: + application/json: + schema: + $ref: definitions/keys_query_response.yaml + /query: post: summary: Query for several server's keys description: |- Query for keys from multiple servers in a batch format. The receiving (notary) server must sign the keys returned by the queried servers. operationId: bulkPerspectivesKeyQuery - parameters: - - in: body - name: body - schema: - type: object - example: { - "server_keys": { - "example.org": { - "ed25519:abc123": { - "minimum_valid_until_ts": 1234567890 + requestBody: + content: + application/json: + schema: + type: object + example: { + "server_keys": { + "example.org": { + "ed25519:abc123": { + "minimum_valid_until_ts": 1234567890 + } } } } - } - properties: - server_keys: - type: object - description: |- - The query criteria. The outer `string` key on the object is the - server name (eg: `matrix.org`). The inner `string` key is the - Key ID to query for the particular server. If no key IDs are given - to be queried, the notary server should query for all keys. If no - servers are given, the notary server must return an empty `server_keys` - array in the response. - - The notary server may return multiple keys regardless of the Key IDs - given. - additionalProperties: + properties: + server_keys: type: object - name: ServerName - description: The server names to query. + description: |- + The query criteria. The outer `string` key on the object is the + server name (eg: `matrix.org`). The inner `string` key is the + Key ID to query for the particular server. If no key IDs are given + to be queried, the notary server should query for all keys. If no + servers are given, the notary server must return an empty `server_keys` + array in the response. + + The notary server may return multiple keys regardless of the Key IDs + given. additionalProperties: type: object - title: Query Criteria - description: The server key IDs to query. - properties: - minimum_valid_until_ts: - type: integer - format: int64 - description: |- - A millisecond POSIX timestamp in milliseconds indicating when - the returned certificates will need to be valid until to be - useful to the requesting server. + description: The server names to query. + additionalProperties: + type: object + title: Query Criteria + description: The server key IDs to query. + properties: + minimum_valid_until_ts: + type: integer + format: int64 + description: |- + A millisecond POSIX timestamp in milliseconds indicating when + the returned certificates will need to be valid until to be + useful to the requesting server. - If not supplied, the current time as determined by the notary - server is used. - example: 1234567890 - required: ['server_keys'] + If not supplied, the current time as determined by the notary + server is used. + example: 1234567890 + required: + - server_keys responses: - 200: + "200": description: |- The keys for the queried servers, signed by the notary server. Servers which are offline and have no cached keys will not be included in the result. This may result in an empty array. - schema: - $ref: "definitions/keys_query_response.yaml" + content: + application/json: + schema: + $ref: definitions/keys_query_response.yaml +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8448 + basePath: + default: /_matrix/key/v2 diff --git a/data/api/server-server/keys_server.yaml b/data/api/server-server/keys_server.yaml index bee520f3..8929458d 100644 --- a/data/api/server-server/keys_server.yaml +++ b/data/api/server-server/keys_server.yaml @@ -11,19 +11,12 @@ # 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. - -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Federation Key Exchange API" - version: "1.0.0" -host: localhost:8448 -schemes: - - https -basePath: /_matrix/key/v2 -produces: - - application/json + title: Matrix Federation Key Exchange API + version: 1.0.0 paths: - "/server": + /server: get: summary: Get the homeserver's public key(s) description: |- @@ -44,7 +37,21 @@ paths: checked. operationId: getServerKey responses: - 200: + "200": description: The homeserver's keys - schema: - $ref: "definitions/keys.yaml" + content: + application/json: + schema: + $ref: definitions/keys.yaml +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8448 + basePath: + default: /_matrix/key/v2 diff --git a/data/api/server-server/knocks.yaml b/data/api/server-server/knocks.yaml index de17f44d..266e3368 100644 --- a/data/api/server-server/knocks.yaml +++ b/data/api/server-server/knocks.yaml @@ -11,21 +11,10 @@ # 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. - -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Federation Knock Room API" - version: "1.0.0" -host: localhost:8448 -schemes: - - https -basePath: /_matrix/federation/v1 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Federation Knock Room API + version: 1.0.0 paths: "/make_knock/{roomId}/{userId}": get: @@ -40,107 +29,115 @@ paths: parameters: - in: path name: roomId - type: string description: The room ID that is about to be knocked. required: true - x-example: "!abc123:example.org" + example: "!abc123:example.org" + schema: + type: string - in: path name: userId - type: string description: The user ID the knock event will be for. required: true - x-example: "@someone:example.org" - - in: query - type: array - items: + example: "@someone:example.org" + schema: type: string + - in: query name: ver - description: |- - The room versions the sending server has support for. + description: The room versions the sending server has support for. required: true # knocking was supported in v7 - x-example: ["1", "7"] + example: + - "1" + - "7" + schema: + type: array + items: + type: string responses: - 200: + "200": description: |- A template to be used for the rest of the [Knocking Rooms](/server-server-api/#knocking-rooms) handshake. Note that events have a different format depending on room version - check the [room version specification](/rooms) for precise event formats. **The response body here describes the common event fields in more detail and may be missing other required fields for a PDU.** - schema: - type: object - properties: - room_version: - type: string - description: |- - The version of the room where the server is trying to knock. - example: "7" - event: - description: |- - An unsigned template event. Note that events have a different format - depending on the room version - check the [room version specification](/rooms) - for precise event formats. + content: + application/json: + schema: type: object - title: Event Template properties: - sender: + room_version: type: string - description: The user ID of the knocking member. - example: "@someone:example.org" - origin: - type: string - description: The name of the resident homeserver. - example: "matrix.org" - origin_server_ts: - type: integer - format: int64 - description: A timestamp added by the resident homeserver. - example: 1234567890 - type: - type: string - description: The value `m.room.member`. - example: "m.room.member" - state_key: - type: string - description: The user ID of the knocking member. - example: "@someone:example.org" - content: + description: The version of the room where the server is trying to knock. + example: "7" + event: + description: |- + An unsigned template event. Note that events have a different format + depending on the room version - check the [room version specification](/rooms) + for precise event formats. type: object - title: Membership Event Content - description: The content of the event. - example: {"membership": "knock"} + title: Event Template properties: - membership: + sender: type: string - description: The value `knock`. - example: "knock" - required: ['membership'] + description: The user ID of the knocking member. + example: "@someone:example.org" + origin: + type: string + description: The name of the resident homeserver. + example: matrix.org + origin_server_ts: + type: integer + format: int64 + description: A timestamp added by the resident homeserver. + example: 1234567890 + type: + type: string + description: The value `m.room.member`. + example: m.room.member + state_key: + type: string + description: The user ID of the knocking member. + example: "@someone:example.org" + content: + type: object + title: Membership Event Content + description: The content of the event. + example: + membership: knock + properties: + membership: + type: string + description: The value `knock`. + example: knock + required: + - membership + required: + - state_key + - origin + - origin_server_ts + - type + - content + - sender required: - - state_key - - origin - - origin_server_ts - - type - - content - - sender - required: - - room_version # knocking was added in v7 - - event - examples: - application/json: { - "room_version": "7", - "event": { - "room_id": "!somewhere:example.org", - "type": "m.room.member", - "state_key": "@someone:example.org", - "origin": "example.org", - "origin_server_ts": 1549041175876, - "sender": "@someone:example.org", - "content": { - "membership": "knock" - } - } - } - 400: + - room_version # knocking was added in v7 + - event + examples: + response: + value: { + "room_version": "7", + "event": { + "room_id": "!somewhere:example.org", + "type": "m.room.member", + "state_key": "@someone:example.org", + "origin": "example.org", + "origin_server_ts": 1549041175876, + "sender": "@someone:example.org", + "content": { + "membership": "knock" + } + } + } + "400": description: |- The request is invalid or the room the server is attempting to knock upon has a version that is not listed in the `ver` @@ -148,47 +145,55 @@ paths: The error should be passed through to clients so that they may give better feedback to users. - schema: - allOf: - - $ref: "../client-server/definitions/errors/error.yaml" - - type: object - properties: - room_version: - type: string - description: |- - The version of the room. Required if the `errcode` - is `M_INCOMPATIBLE_ROOM_VERSION`. - examples: - application/json: { - "errcode": "M_INCOMPATIBLE_ROOM_VERSION", - "error": "Your homeserver does not support the features required to knock on this room", - "room_version": "7" - } - 404: - description: |- - The room that the knocking server is attempting to knock upon is unknown - to the receiving server. - schema: - allOf: - - $ref: "../client-server/definitions/errors/error.yaml" - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Unknown room", - } - 403: + content: + application/json: + schema: + allOf: + - $ref: ../client-server/definitions/errors/error.yaml + - type: object + properties: + room_version: + type: string + description: |- + The version of the room. Required if the `errcode` + is `M_INCOMPATIBLE_ROOM_VERSION`. + examples: + response: + value: { + "errcode": "M_INCOMPATIBLE_ROOM_VERSION", + "error": "Your homeserver does not support the features required to knock on this room", + "room_version": "7" + } + "403": description: |- The knocking server or user is not permitted to knock on the room, such as when the server/user is banned or the room is not set up for receiving knocks. - schema: - allOf: - - $ref: "../client-server/definitions/errors/error.yaml" - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "You are not permitted to knock on this room", - } - + content: + application/json: + schema: + allOf: + - $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "You are not permitted to knock on this room" + } + "404": + description: |- + The room that the knocking server is attempting to knock upon is unknown + to the receiving server. + content: + application/json: + schema: + allOf: + - $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Unknown room" + } "/send_knock/{roomId}/{eventId}": put: x-addedInMatrixVersion: "1.1" @@ -207,117 +212,147 @@ paths: parameters: - in: path name: roomId - type: string description: The room ID that is about to be knocked upon. required: true - x-example: "!abc123:example.org" + example: "!abc123:example.org" + schema: + type: string - in: path name: eventId - type: string description: The event ID for the knock event. required: true - x-example: "$abc123:example.org" - - in: body - name: body - type: object - required: true + example: $abc123:example.org schema: - type: object - properties: - sender: - type: string - description: The user ID of the knocking member. - example: "@someone:example.org" - origin: - type: string - description: The name of the knocking homeserver. - example: "matrix.org" - origin_server_ts: - type: integer - format: int64 - description: A timestamp added by the knocking homeserver. - example: 1234567890 - type: - type: string - description: The value `m.room.member`. - example: "m.room.member" - state_key: - type: string - description: The user ID of the knocking member. - example: "@someone:example.org" - content: - type: object - title: Membership Event Content - description: The content of the event. - example: {"membership": "knock"} - properties: - membership: - type: string - description: The value `knock`. - example: "knock" - required: ['membership'] - required: - - state_key - - sender - - origin - - origin_server_ts - - type - - content - example: { - "room_id": "!somewhere:example.org", - "type": "m.room.member", - "state_key": "@someone:example.org", - "origin": "example.org", - "origin_server_ts": 1549041175876, - "sender": "@someone:example.org", - "content": { - "membership": "knock" + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + sender: + type: string + description: The user ID of the knocking member. + example: "@someone:example.org" + origin: + type: string + description: The name of the knocking homeserver. + example: matrix.org + origin_server_ts: + type: integer + format: int64 + description: A timestamp added by the knocking homeserver. + example: 1234567890 + type: + type: string + description: The value `m.room.member`. + example: m.room.member + state_key: + type: string + description: The user ID of the knocking member. + example: "@someone:example.org" + content: + type: object + title: Membership Event Content + description: The content of the event. + example: + membership: knock + properties: + membership: + type: string + description: The value `knock`. + example: knock + required: + - membership + required: + - state_key + - sender + - origin + - origin_server_ts + - type + - content + example: { + "room_id": "!somewhere:example.org", + "type": "m.room.member", + "state_key": "@someone:example.org", + "origin": "example.org", + "origin_server_ts": 1549041175876, + "sender": "@someone:example.org", + "content": { + "membership": "knock" + } } - } + required: true responses: - 200: + "200": description: |- Information about the room to pass along to clients regarding the knock. - schema: - type: object - properties: - knock_room_state: - type: array - items: - $ref: "../../event-schemas/schema/core-event-schema/stripped_state.yaml" - description: |- - A list of [stripped state events](/client-server-api/#stripped-state) - to help the initiator of the knock identify the room. - example: - $ref: "../../event-schemas/examples/knock_room_state.json" - required: ['knock_room_state'] - examples: - application/json: { - "knock_room_state": {"$ref": "../../event-schemas/examples/knock_room_state.json"} - } - 404: - description: |- - The room that the knocking server is attempting to knock upon is unknown - to the receiving server. - schema: - allOf: - - $ref: "../client-server/definitions/errors/error.yaml" - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Unknown room", - } - 403: + content: + application/json: + schema: + type: object + properties: + knock_room_state: + type: array + items: + $ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml + description: |- + A list of [stripped state events](/client-server-api/#stripped-state) + to help the initiator of the knock identify the room. + example: + $ref: ../../event-schemas/examples/knock_room_state.json + required: + - knock_room_state + examples: + response: + value: { + "knock_room_state": { + "$ref": "../../event-schemas/examples/knock_room_state.json" + } + } + "403": description: |- The knocking server or user is not permitted to knock on the room, such as when the server/user is banned or the room is not set up for receiving knocks. - schema: - allOf: - - $ref: "../client-server/definitions/errors/error.yaml" - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "You are not permitted to knock on this room", - } - + content: + application/json: + schema: + allOf: + - $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "You are not permitted to knock on this room" + } + "404": + description: |- + The room that the knocking server is attempting to knock upon is unknown + to the receiving server. + content: + application/json: + schema: + allOf: + - $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Unknown room" + } +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8448 + basePath: + default: /_matrix/federation/v1 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/server-server/leaving-v1.yaml b/data/api/server-server/leaving-v1.yaml index 5264d38c..ee616323 100644 --- a/data/api/server-server/leaving-v1.yaml +++ b/data/api/server-server/leaving-v1.yaml @@ -12,21 +12,10 @@ # 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. - -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Federation Leave Room API" - version: "1.0.0" -host: localhost:8448 -schemes: - - https -basePath: /_matrix/federation/v1 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Federation Leave Room API + version: 1.0.0 paths: "/make_leave/{roomId}/{userId}": get: @@ -40,105 +29,115 @@ paths: parameters: - in: path name: roomId - type: string description: The room ID that is about to be left. required: true - x-example: "!abc123:matrix.org" + example: "!abc123:matrix.org" + schema: + type: string - in: path name: userId - type: string description: The user ID the leave event will be for. required: true - x-example: "@someone:example.org" + example: "@someone:example.org" + schema: + type: string responses: - 200: + "200": description: |- A template to be used to call `/send_leave`. Note that events have a different format depending on the room version - check the [room version specification](/rooms) for precise event formats. **The response body here describes the common event fields in more detail and may be missing other required fields for a PDU.** - schema: - type: object - properties: - room_version: - type: string - description: |- - The version of the room where the server is trying to leave. If not provided, - the room version is assumed to be either "1" or "2". - example: "2" - event: - description: |- - An unsigned template event. Note that events have a different format - depending on the room version - check the [room version specification](/rooms) - for precise event formats. + content: + application/json: + schema: type: object - title: Event Template properties: - sender: + room_version: type: string - description: The user ID of the leaving member. - example: "@someone:example.org" - origin: - type: string - description: The name of the resident homeserver. - example: "matrix.org" - origin_server_ts: - type: integer - format: int64 - description: A timestamp added by the resident homeserver. - example: 1234567890 - type: - type: string - description: The value `m.room.member`. - example: "m.room.member" - state_key: - type: string - description: The user ID of the leaving member. - example: "@someone:example.org" - content: + description: |- + The version of the room where the server is trying to leave. If not provided, + the room version is assumed to be either "1" or "2". + example: "2" + event: + description: |- + An unsigned template event. Note that events have a different format + depending on the room version - check the [room version specification](/rooms) + for precise event formats. type: object - title: Membership Event Content - description: The content of the event. - example: {"membership": "leave"} + title: Event Template properties: - membership: + sender: type: string - description: The value `leave`. - example: "leave" - required: ['membership'] - required: - - state_key - - sender - - origin - - origin_server_ts - - type - - content - examples: - application/json: { - "room_version": "2", - "event": { - "room_id": "!somewhere:example.org", - "type": "m.room.member", - "state_key": "@someone:example.org", - "origin": "example.org", - "origin_server_ts": 1549041175876, - "sender": "@someone:example.org", - "content": { - "membership": "leave" - } - } - } - 403: - description: |- - The request is not authorized. This could mean that the user is not in the room. - schema: - $ref: "../client-server/definitions/errors/error.yaml" - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "User is not in the room." - } + description: The user ID of the leaving member. + example: "@someone:example.org" + origin: + type: string + description: The name of the resident homeserver. + example: matrix.org + origin_server_ts: + type: integer + format: int64 + description: A timestamp added by the resident homeserver. + example: 1234567890 + type: + type: string + description: The value `m.room.member`. + example: m.room.member + state_key: + type: string + description: The user ID of the leaving member. + example: "@someone:example.org" + content: + type: object + title: Membership Event Content + description: The content of the event. + example: + membership: leave + properties: + membership: + type: string + description: The value `leave`. + example: leave + required: + - membership + required: + - state_key + - sender + - origin + - origin_server_ts + - type + - content + examples: + response: + value: { + "room_version": "2", + "event": { + "room_id": "!somewhere:example.org", + "type": "m.room.member", + "state_key": "@someone:example.org", + "origin": "example.org", + "origin_server_ts": 1549041175876, + "sender": "@someone:example.org", + "content": { + "membership": "leave" + } + } + } + "403": + description: The request is not authorized. This could mean that the user is not + in the room. + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "User is not in the room." + } "/send_leave/{roomId}/{eventId}": put: deprecated: true @@ -160,93 +159,108 @@ paths: parameters: - in: path name: roomId - type: string description: The room ID that is about to be left. required: true - x-example: "!abc123:matrix.org" + example: "!abc123:matrix.org" + schema: + type: string - in: path name: eventId - type: string description: The event ID for the leave event. required: true - x-example: "$abc123:example.org" - - in: body - name: body - type: object - required: true + example: $abc123:example.org schema: - type: object - properties: - sender: - type: string - description: The user ID of the leaving member. - example: "@someone:example.org" - origin: - type: string - description: The name of the leaving homeserver. - example: "matrix.org" - origin_server_ts: - type: integer - format: int64 - description: A timestamp added by the leaving homeserver. - example: 1234567890 - type: - type: string - description: The value `m.room.member`. - example: "m.room.member" - state_key: - type: string - description: The user ID of the leaving member. - example: "@someone:example.org" - content: - type: object - title: Membership Event Content - description: The content of the event. - example: {"membership": "leave"} - properties: - membership: - type: string - description: The value `leave`. - example: "leave" - required: ['membership'] - depth: - type: integer - description: This field must be present but is ignored; it may be 0. - example: 12 - required: - - state_key - - sender - - origin - - origin_server_ts - - type - - depth - - content - example: { - "room_id": "!somewhere:example.org", - "type": "m.room.member", - "state_key": "@someone:example.org", - "origin": "example.org", - "origin_server_ts": 1549041175876, - "sender": "@someone:example.org", - "content": { - "membership": "leave" - } - } + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + sender: + type: string + description: The user ID of the leaving member. + example: "@someone:example.org" + origin: + type: string + description: The name of the leaving homeserver. + example: matrix.org + origin_server_ts: + type: integer + format: int64 + description: A timestamp added by the leaving homeserver. + example: 1234567890 + type: + type: string + description: The value `m.room.member`. + example: m.room.member + state_key: + type: string + description: The user ID of the leaving member. + example: "@someone:example.org" + content: + type: object + title: Membership Event Content + description: The content of the event. + example: + membership: leave + properties: + membership: + type: string + description: The value `leave`. + example: leave + required: + - membership + depth: + type: integer + description: This field must be present but is ignored; it may be 0. + example: 12 + required: + - state_key + - sender + - origin + - origin_server_ts + - type + - depth + - content + required: true responses: - 200: + "200": description: |- An empty response to indicate the event was accepted into the graph by the receiving homeserver. - schema: - type: array - minItems: 2 - maxItems: 2 - items: - - type: integer - description: The value `200`. - example: 200 - - type: object - title: Empty Object - description: An empty object. - examples: - application/json: [200, {}] + content: + application/json: + schema: + type: array + minItems: 2 + maxItems: 2 + items: + anyOf: + - type: integer + description: The value `200`. + example: 200 + - type: object + title: Empty Object + description: An empty object. + examples: + response: + value: [ + 200, + {} + ] +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8448 + basePath: + default: /_matrix/federation/v1 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/server-server/leaving-v2.yaml b/data/api/server-server/leaving-v2.yaml index dd96eaaa..75248b53 100644 --- a/data/api/server-server/leaving-v2.yaml +++ b/data/api/server-server/leaving-v2.yaml @@ -12,21 +12,10 @@ # 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. - -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Federation Leave Room API" - version: "1.0.0" -host: localhost:8448 -schemes: - - https -basePath: /_matrix/federation/v2 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Federation Leave Room API + version: 1.0.0 paths: # Note: there is no v2 of make_leave (yet) "/send_leave/{roomId}/{eventId}": @@ -55,86 +44,108 @@ paths: parameters: - in: path name: roomId - type: string description: The room ID that is about to be left. required: true - x-example: "!abc123:matrix.org" + example: "!abc123:matrix.org" + schema: + type: string - in: path name: eventId - type: string description: The event ID for the leave event. required: true - x-example: "$abc123:example.org" - - in: body - name: body - type: object - required: true + example: $abc123:example.org schema: - type: object - properties: - sender: - type: string - description: The user ID of the leaving member. - example: "@someone:example.org" - origin: - type: string - description: The name of the leaving homeserver. - example: "matrix.org" - origin_server_ts: - type: integer - format: int64 - description: A timestamp added by the leaving homeserver. - example: 1234567890 - type: - type: string - description: The value `m.room.member`. - example: "m.room.member" - state_key: - type: string - description: The user ID of the leaving member. - example: "@someone:example.org" - content: - type: object - title: Membership Event Content - description: The content of the event. - example: {"membership": "leave"} - properties: - membership: - type: string - description: The value `leave`. - example: "leave" - required: ['membership'] - depth: - type: integer - description: This field must be present but is ignored; it may be 0. - example: 12 - required: - - state_key - - sender - - origin - - origin_server_ts - - type - - depth - - content - example: { - "room_id": "!somewhere:example.org", - "type": "m.room.member", - "state_key": "@someone:example.org", - "origin": "example.org", - "origin_server_ts": 1549041175876, - "sender": "@someone:example.org", - "content": { - "membership": "leave" + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + sender: + type: string + description: The user ID of the leaving member. + example: "@someone:example.org" + origin: + type: string + description: The name of the leaving homeserver. + example: matrix.org + origin_server_ts: + type: integer + format: int64 + description: A timestamp added by the leaving homeserver. + example: 1234567890 + type: + type: string + description: The value `m.room.member`. + example: m.room.member + state_key: + type: string + description: The user ID of the leaving member. + example: "@someone:example.org" + content: + type: object + title: Membership Event Content + description: The content of the event. + example: + membership: leave + properties: + membership: + type: string + description: The value `leave`. + example: leave + required: + - membership + depth: + type: integer + description: This field must be present but is ignored; it may be 0. + example: 12 + required: + - state_key + - sender + - origin + - origin_server_ts + - type + - depth + - content + example: { + "room_id": "!somewhere:example.org", + "type": "m.room.member", + "state_key": "@someone:example.org", + "origin": "example.org", + "origin_server_ts": 1549041175876, + "sender": "@someone:example.org", + "content": { + "membership": "leave" + } } - } + required: true responses: - 200: + "200": description: |- An empty response to indicate the event was accepted into the graph by the receiving homeserver. - schema: - type: object - title: Empty Object - description: An empty object. - examples: - application/json: {} + content: + application/json: + schema: + type: object + title: Empty Object + description: An empty object. + examples: + response: + value: {} +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8448 + basePath: + default: /_matrix/federation/v2 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/server-server/openid.yaml b/data/api/server-server/openid.yaml index 0761618d..ce7d8866 100644 --- a/data/api/server-server/openid.yaml +++ b/data/api/server-server/openid.yaml @@ -12,19 +12,12 @@ # 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. - -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Federation OpenID API" - version: "1.0.0" -host: localhost:8448 -schemes: - - https -basePath: /_matrix/federation/v1 -produces: - - application/json + title: Matrix Federation OpenID API + version: 1.0.0 paths: - "/openid/userinfo": + /openid/userinfo: get: summary: Exchange an OpenID token for user information description: |- @@ -35,29 +28,46 @@ paths: parameters: - in: query name: access_token - type: string - description: |- - The OpenID access token to get information about the owner for. + description: The OpenID access token to get information about the owner for. required: true - x-example: SomeT0kenHere + example: SomeT0kenHere + schema: + type: string responses: - 200: - description: |- - Information about the user who generated the OpenID access token. - schema: - type: object - properties: - sub: - type: string - description: The Matrix User ID who generated the token. - example: "@alice:example.com" - required: ['sub'] - 401: + "200": + description: Information about the user who generated the OpenID access token. + content: + application/json: + schema: + type: object + properties: + sub: + type: string + description: The Matrix User ID who generated the token. + example: "@alice:example.com" + required: + - sub + "401": description: The token was not recognized or has expired. - schema: - $ref: "../client-server/definitions/errors/error.yaml" - examples: - application/json: { - "errcode": "M_UNKNOWN_TOKEN", - "error": "Access token unknown or expired" - } + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_UNKNOWN_TOKEN", + "error": "Access token unknown or expired" + } +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8448 + basePath: + default: /_matrix/federation/v1 diff --git a/data/api/server-server/public_rooms.yaml b/data/api/server-server/public_rooms.yaml index 3079b7c2..dd909f8f 100644 --- a/data/api/server-server/public_rooms.yaml +++ b/data/api/server-server/public_rooms.yaml @@ -11,21 +11,12 @@ # 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. - -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Federation Public Rooms API" - version: "1.0.0" -host: localhost:8448 -schemes: - - https -basePath: /_matrix/federation/v1 -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Federation Public Rooms API + version: 1.0.0 paths: - "/publicRooms": + /publicRooms: get: summary: Get all the public rooms for a homeserver description: |- @@ -38,36 +29,41 @@ paths: parameters: - in: query name: limit - type: integer - description: |- - The maximum number of rooms to return. Defaults to 0 (no limit). - x-example: 10 + description: The maximum number of rooms to return. Defaults to 0 (no limit). + example: 10 + schema: + type: integer - in: query name: since - type: string description: |- A pagination token from a previous call to this endpoint to fetch more rooms. - x-example: "GetMoreRoomsTokenHere" + example: GetMoreRoomsTokenHere + schema: + type: string - in: query name: include_all_networks - type: boolean description: |- Whether or not to include all networks/protocols defined by application services on the homeserver. Defaults to false. - x-example: false + example: false + schema: + type: boolean - in: query name: third_party_instance_id - type: string description: |- The specific third-party network/protocol to request from the homeserver. Can only be used if `include_all_networks` is false. - x-example: "irc" - responses: - 200: - description: The public room list for the homeserver. + example: irc schema: - $ref: "../client-server/definitions/public_rooms_response.yaml" + type: string + responses: + "200": + description: The public room list for the homeserver. + content: + application/json: + schema: + $ref: ../client-server/definitions/public_rooms_response.yaml post: summary: Gets the public rooms on the server with optional filter. description: |- @@ -81,32 +77,27 @@ paths: operationId: queryPublicRooms security: - signedRequest: [] - parameters: - - in: body - name: body - required: true - description: |- - Options for which rooms to return, or empty object to use defaults. - schema: - type: object - properties: - limit: - type: integer - description: |- - Limit the number of results returned. - since: - type: string - description: |- - A pagination token from a previous request, allowing servers - to get the next (or previous) batch of rooms. The direction - of pagination is specified solely by which token is supplied, - rather than via an explicit flag. - filter: - type: object - title: "Filter" - description: |- - Filter to apply to the results. - properties: + requestBody: + content: + application/json: + schema: + type: object + properties: + limit: + type: integer + description: Limit the number of results returned. + since: + type: string + description: |- + A pagination token from a previous request, allowing servers + to get the next (or previous) batch of rooms. The direction + of pagination is specified solely by which token is supplied, + rather than via an explicit flag. + filter: + type: object + title: Filter + description: Filter to apply to the results. + properties: generic_search_term: type: string description: |- @@ -122,85 +113,109 @@ paths: for. To include rooms without a room type, specify `null` within this list. When not specified, all applicable rooms (regardless of type) are returned. - include_all_networks: - type: boolean - description: |- - Whether or not to include all known networks/protocols from - application services on the homeserver. Defaults to false. - example: false - third_party_instance_id: - type: string - description: |- - The specific third-party network/protocol to request from the - homeserver. Can only be used if `include_all_networks` is false. - example: "irc" - example: { - "limit": 10, - "filter": { - "generic_search_term": "foo", - "room_types": [null, "m.space"] - }, - "include_all_networks": false, - "third_party_instance_id": "irc" - } + include_all_networks: + type: boolean + description: |- + Whether or not to include all known networks/protocols from + application services on the homeserver. Defaults to false. + example: false + third_party_instance_id: + type: string + description: |- + The specific third-party network/protocol to request from the + homeserver. Can only be used if `include_all_networks` is false. + example: irc + example: { + "limit": 10, + "filter": { + "generic_search_term": "foo", + "room_types": [ + null, + "m.space" + ] + }, + "include_all_networks": false, + "third_party_instance_id": "irc" + } + description: Options for which rooms to return, or empty object to use defaults. + required: true responses: - 200: + "200": description: A list of the rooms on the server. - schema: - type: object - description: A list of the rooms on the server. - required: ["chunk"] - properties: - chunk: - title: "PublicRoomsChunks" - type: array - description: A paginated chunk of public rooms. - items: - allOf: - - $ref: "../client-server/definitions/public_rooms_chunk.yaml" - - type: object - properties: - # Override description of join_rule - join_rule: - type: string - description: |- - The room's join rule. When not present, the room is assumed to - be `public`. Note that rooms with `invite` join rules are not - expected here, but rooms with `knock` rules are given their - near-public nature. - next_batch: - type: string - description: |- - A pagination token for the response. The absence of this token - means there are no more results to fetch and the client should - stop paginating. - prev_batch: - type: string - description: |- - A pagination token that allows fetching previous results. The - absence of this token means there are no results before this - batch, i.e. this is the first batch. - total_room_count_estimate: - type: integer - description: |- - An estimate on the total number of public rooms, if the - server has an estimate. - examples: - application/json: { - "chunk": [ - { - "avatar_url": "mxc://bleecker.street/CHEDDARandBRIE", - "guest_can_join": false, - "name": "CHEESE", - "num_joined_members": 37, - "room_id": "!ol19s:bleecker.street", - "topic": "Tasty tasty cheese", - "world_readable": true, - "join_rule": "public", - "room_type": "m.space" - } - ], - "next_batch": "p190q", - "prev_batch": "p1902", - "total_room_count_estimate": 115 - } + content: + application/json: + schema: + type: object + description: A list of the rooms on the server. + required: + - chunk + properties: + chunk: + title: PublicRoomsChunks + type: array + description: A paginated chunk of public rooms. + items: + allOf: + - $ref: ../client-server/definitions/public_rooms_chunk.yaml + - type: object + properties: + # Override description of join_rule + join_rule: + type: string + description: |- + The room's join rule. When not present, the room is assumed to + be `public`. Note that rooms with `invite` join rules are not + expected here, but rooms with `knock` rules are given their + near-public nature. + next_batch: + type: string + description: |- + A pagination token for the response. The absence of this token + means there are no more results to fetch and the client should + stop paginating. + prev_batch: + type: string + description: |- + A pagination token that allows fetching previous results. The + absence of this token means there are no results before this + batch, i.e. this is the first batch. + total_room_count_estimate: + type: integer + description: |- + An estimate on the total number of public rooms, if the + server has an estimate. + examples: + response: + value: { + "chunk": [ + { + "avatar_url": "mxc://bleecker.street/CHEDDARandBRIE", + "guest_can_join": false, + "name": "CHEESE", + "num_joined_members": 37, + "room_id": "!ol19s:bleecker.street", + "topic": "Tasty tasty cheese", + "world_readable": true, + "join_rule": "public", + "room_type": "m.space" + } + ], + "next_batch": "p190q", + "prev_batch": "p1902", + "total_room_count_estimate": 115 + } +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8448 + basePath: + default: /_matrix/federation/v1 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/server-server/query.yaml b/data/api/server-server/query.yaml index 42b64ea8..23a6dffd 100644 --- a/data/api/server-server/query.yaml +++ b/data/api/server-server/query.yaml @@ -12,19 +12,10 @@ # 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. - -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Federation Query API" - version: "1.0.0" -host: localhost:8448 -schemes: - - https -basePath: /_matrix/federation/v1 -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Federation Query API + version: 1.0.0 paths: "/query/{queryType}": get: @@ -39,15 +30,16 @@ paths: parameters: - in: path name: queryType - type: string description: The type of query to make required: true - x-example: profile + example: profile + schema: + type: string responses: - 200: - description: |- - The query response. The schema varies depending on the query being made. - "/query/directory": + "200": + description: The query response. The schema varies depending on the query being + made. + /query/directory: get: summary: Query for the room ID and resident homeservers for a room alias description: |- @@ -63,50 +55,57 @@ paths: parameters: - in: query name: room_alias - type: string description: The room alias to query. required: true - x-example: "#room_alias:example.org" + example: "#room_alias:example.org" + schema: + type: string responses: - 200: - description: |- - The corresponding room ID and list of known resident homeservers for the room. - schema: - type: object - properties: - room_id: - type: string - description: The room ID mapped to the queried room alias. - x-example: "!roomid1234:example.org" - servers: - type: array - description: |- - An array of server names that are likely to hold the given room. This - list may or may not include the server answering the query. - items: - type: string - required: - - "room_id" - - "servers" - examples: - application/json: { - "room_id": "!roomid1234:example.org", - "servers": [ - "example.org", - "example.com", - "another.example.com:8449", - ] - } - 404: + "200": + description: The corresponding room ID and list of known resident homeservers + for the room. + content: + application/json: + schema: + type: object + properties: + room_id: + type: string + description: The room ID mapped to the queried room alias. + example: "!roomid1234:example.org" + servers: + type: array + description: |- + An array of server names that are likely to hold the given room. This + list may or may not include the server answering the query. + items: + type: string + required: + - room_id + - servers + examples: + response: + value: { + "room_id": "!roomid1234:example.org", + "servers": [ + "example.org", + "example.com", + "another.example.com:8449" + ] + } + "404": description: The room alias was not found. - schema: - $ref: "../client-server/definitions/errors/error.yaml" - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Room alias not found." - } - "/query/profile": + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Room alias not found." + } + /query/profile: get: summary: Query for profile information about a given user description: |- @@ -122,20 +121,24 @@ paths: parameters: - in: query name: user_id - type: string description: The user ID to query. required: true - x-example: "@someone:example.org" + example: "@someone:example.org" + schema: + type: string - in: query name: field - type: string - enum: ['displayname', 'avatar_url'] description: |- The field to query. If specified, the server will only return the given field in the response. If not specified, the server will return the full profile for the user. + schema: + type: string + enum: + - displayname + - avatar_url responses: - 200: + "200": description: |- The profile for the user. If a `field` is specified in the request, only the matching field should be included in the response. If no `field` was specified, @@ -144,32 +147,53 @@ paths: If the user does not have a particular field set on their profile, the server should exclude it from the response body or give it the value `null`. - schema: - type: object - properties: - displayname: - type: string - description: |- - The display name of the user. May be omitted if the user does not have a - display name set. - x-example: "John Doe" - avatar_url: - type: string - description: |- - The avatar URL for the user's avatar. May be omitted if the user does not - have an avatar set. - x-example: "mxc://matrix.org/MyC00lAvatar" - examples: - application/json: { - "displayname": "John Doe", - "avatar_url": "mxc://matrix.org/MyC00lAvatar" - } - 404: + content: + application/json: + schema: + type: object + properties: + displayname: + type: string + description: |- + The display name of the user. May be omitted if the user does not have a + display name set. + example: John Doe + avatar_url: + type: string + description: |- + The avatar URL for the user's avatar. May be omitted if the user does not + have an avatar set. + example: mxc://matrix.org/MyC00lAvatar + examples: + response: + value: { + "displayname": "John Doe", + "avatar_url": "mxc://matrix.org/MyC00lAvatar" + } + "404": description: The user does not exist or does not have a profile. - schema: - $ref: "../client-server/definitions/errors/error.yaml" - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "User does not exist." - } + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "User does not exist." + } +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8448 + basePath: + default: /_matrix/federation/v1 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/server-server/space_hierarchy.yaml b/data/api/server-server/space_hierarchy.yaml index 296fb657..aa98158f 100644 --- a/data/api/server-server/space_hierarchy.yaml +++ b/data/api/server-server/space_hierarchy.yaml @@ -11,20 +11,10 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Federation Space Hierarchy API" - version: "1.0.0" -host: localhost:8448 -schemes: - - https -basePath: /_matrix/federation/v1 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Federation Space Hierarchy API + version: 1.0.0 paths: "/hierarchy/{roomId}": get: @@ -45,163 +35,199 @@ paths: - signedRequest: [] parameters: - in: path - type: string name: roomId description: The room ID of the space to get a hierarchy for. required: true - x-example: "!space:example.org" + example: "!space:example.org" + schema: + type: string - in: query - type: boolean name: suggested_only description: |- Optional (default `false`) flag to indicate whether or not the server should only consider suggested rooms. Suggested rooms are annotated in their [`m.space.child`](/client-server-api/#mspacechild) event contents. - x-example: true - responses: - 200: - description: |- - The space room and its children. - examples: - application/json: { - "room": { - "room_id": "!space:example.org", - "avatar_url": "mxc://example.org/abcdef", - "guest_can_join": false, - "name": "The First Space", - "topic": "No other spaces were created first, ever", - "world_readable": true, - "join_rule": "public", - "room_type": "m.space", - "num_joined_members": 42, - "canonical_alias": "#general:example.org", - "allowed_room_ids": [], - "children_state": [ - { - "type": "m.space.child", - "state_key": "!a:example.org", - "content": { - "via": ["remote.example.org"] - }, - "sender": "@alice:example.org", - "origin_server_ts": 1629413349153 - } - ] - }, - "inaccessible_children": [ - "!secret:example.org" - ], - "children": [ - { - "room_id": "!second_room:example.org", - "avatar_url": "mxc://example.org/abcdef2", - "guest_can_join": false, - "name": "The ~~First~~ Second Space", - "topic": "Hello world", - "world_readable": true, - "join_rule": "restricted", - "room_type": "m.space", - "num_joined_members": 42, - "canonical_alias": "#general:example.org", - "allowed_room_ids": [ - "!upstream:example.org" - ], - "children_state": [ - { - "type": "m.space.child", - "state_key": "!b:example.org", - "content": { - "via": ["remote.example.org"] - }, - "sender": "@alice:example.org", - "origin_server_ts": 1629422222222 - } - ] - } - ] - } + example: true schema: - type: object - properties: - room: - description: A summary of the room requested. - allOf: - - $ref: "../client-server/definitions/public_rooms_chunk.yaml" - - type: object - properties: - room_type: - type: string - description: |- - The `type` of room (from [`m.room.create`](/client-server-api/#mroomcreate)), if any. - allowed_room_ids: - type: array - items: - type: string - description: |- - If the room is a [restricted room](#restricted-rooms), these are the room IDs which - are specified by the join rules. Empty or omitted otherwise. - children_state: - type: array - description: |- - The [`m.space.child`](/client-server-api/#mspacechild) events of the space-room, represented - as [Stripped State Events](/client-server-api/#stripped-state) with an added - `origin_server_ts` key. - - If the room is not a space-room, this should be empty. - items: - allOf: - - $ref: "../../event-schemas/schema/core-event-schema/stripped_state.yaml" - - type: object - properties: - origin_server_ts: - type: integer - format: int64 - description: The `origin_server_ts` for the event. - required: [origin_server_ts] - required: [children_state] - children: - type: array - description: |- - A summary of the space's children. Rooms which the requesting server cannot peek/join will - be excluded. - items: - allOf: - - $ref: "../client-server/definitions/public_rooms_chunk.yaml" - - type: object - properties: - room_type: - type: string - description: |- - The `type` of room (from [`m.room.create`](/client-server-api/#mroomcreate)), if any. - allowed_room_ids: - type: array - items: + type: boolean + responses: + "200": + description: The space room and its children. + content: + application/json: + schema: + type: object + properties: + room: + description: A summary of the room requested. + allOf: + - $ref: ../client-server/definitions/public_rooms_chunk.yaml + - type: object + properties: + room_type: type: string - description: |- - If the room is a [restricted room](#restricted-rooms), these are the room IDs which - are specified by the join rules. Empty or omitted otherwise. - required: [room_type, allowed_room_ids, children_state] - inaccessible_children: - type: array - items: - type: string - description: |- - The list of room IDs the requesting server doesn't have a viable way to peek/join. Rooms which - the responding server cannot provide details on will be outright excluded from the response instead. + description: The `type` of room (from + [`m.room.create`](/client-server-api/#mroomcreate)), + if any. + allowed_room_ids: + type: array + items: + type: string + description: |- + If the room is a [restricted room](#restricted-rooms), these are the room IDs which + are specified by the join rules. Empty or omitted otherwise. + children_state: + type: array + description: |- + The [`m.space.child`](/client-server-api/#mspacechild) events of the space-room, represented + as [Stripped State Events](/client-server-api/#stripped-state) with an added + `origin_server_ts` key. - Assuming both the requesting and responding server are well behaved, the requesting server should - consider these room IDs as not accessible from anywhere. They should not be re-requested. - required: [room, children, inaccessible_children] - 404: + If the room is not a space-room, this should be empty. + items: + allOf: + - $ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml + - type: object + properties: + origin_server_ts: + type: integer + format: int64 + description: The `origin_server_ts` for the event. + required: + - origin_server_ts + required: + - children_state + children: + type: array + description: |- + A summary of the space's children. Rooms which the requesting server cannot peek/join will + be excluded. + items: + allOf: + - $ref: ../client-server/definitions/public_rooms_chunk.yaml + - type: object + properties: + room_type: + type: string + description: The `type` of room (from + [`m.room.create`](/client-server-api/#mroomcreate)), + if any. + allowed_room_ids: + type: array + items: + type: string + description: |- + If the room is a [restricted room](#restricted-rooms), these are the room IDs which + are specified by the join rules. Empty or omitted otherwise. + required: + - room_type + - allowed_room_ids + - children_state + inaccessible_children: + type: array + items: + type: string + description: |- + The list of room IDs the requesting server doesn't have a viable way to peek/join. Rooms which + the responding server cannot provide details on will be outright excluded from the response instead. + + Assuming both the requesting and responding server are well behaved, the requesting server should + consider these room IDs as not accessible from anywhere. They should not be re-requested. + required: + - room + - children + - inaccessible_children + examples: + response: + value: { + "room": { + "room_id": "!space:example.org", + "avatar_url": "mxc://example.org/abcdef", + "guest_can_join": false, + "name": "The First Space", + "topic": "No other spaces were created first, ever", + "world_readable": true, + "join_rule": "public", + "room_type": "m.space", + "num_joined_members": 42, + "canonical_alias": "#general:example.org", + "allowed_room_ids": [], + "children_state": [ + { + "type": "m.space.child", + "state_key": "!a:example.org", + "content": { + "via": [ + "remote.example.org" + ] + }, + "sender": "@alice:example.org", + "origin_server_ts": 1629413349153 + } + ] + }, + "inaccessible_children": [ + "!secret:example.org" + ], + "children": [ + { + "room_id": "!second_room:example.org", + "avatar_url": "mxc://example.org/abcdef2", + "guest_can_join": false, + "name": "The ~~First~~ Second Space", + "topic": "Hello world", + "world_readable": true, + "join_rule": "restricted", + "room_type": "m.space", + "num_joined_members": 42, + "canonical_alias": "#general:example.org", + "allowed_room_ids": [ + "!upstream:example.org" + ], + "children_state": [ + { + "type": "m.space.child", + "state_key": "!b:example.org", + "content": { + "via": [ + "remote.example.org" + ] + }, + "sender": "@alice:example.org", + "origin_server_ts": 1629422222222 + } + ] + } + ] + } + "404": description: |- The room is not known to the server or the requesting server is unable to peek/join it (if it were to attempt this). - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Room does not exist." - } - schema: - "$ref": "../client-server/definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Room does not exist." + } tags: - Spaces +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8448 + basePath: + default: /_matrix/federation/v1 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/server-server/third_party_invite.yaml b/data/api/server-server/third_party_invite.yaml index 55e4d628..3eac4811 100644 --- a/data/api/server-server/third_party_invite.yaml +++ b/data/api/server-server/third_party_invite.yaml @@ -11,21 +11,10 @@ # 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. - -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Federation Third-party Invites API" - version: "1.0.0" -host: localhost:8448 -schemes: - - https -basePath: /_matrix/federation/v1 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Federation Third-party Invites API + version: 1.0.0 paths: "/exchange_third_party_invite/{roomId}": put: @@ -41,166 +30,163 @@ paths: parameters: - in: path name: roomId - type: string description: The room ID to exchange a third-party invite in required: true - x-example: "!abc123:matrix.org" - - in: body - name: body - type: object - description: A partial `m.room.member` event - required: true + example: "!abc123:matrix.org" schema: - type: object - properties: - type: - type: string - description: The event type. Must be `m.room.member` - example: "m.room.member" - room_id: - type: string - description: |- - The room ID the event is for. Must match the ID given in - the path. - example: "!abc123:matrix.org" - sender: - type: string - description: |- - The user ID of the user who sent the original `m.room.third_party_invite` - event. - example: "@joe:matrix.org" - state_key: - type: string - description: The user ID of the invited user - example: "@someone:example.org" - content: - type: object - description: The event content - title: Event Content - properties: - membership: - type: string - description: The membership state. Must be `invite` - example: invite - third_party_invite: - type: object - description: The third-party invite - title: Third-party Invite - properties: - display_name: - type: string - description: |- - A name which can be displayed to represent the user instead of their - third-party identifier. - example: "alice" - signed: - type: object - description: |- - A block of content which has been signed, which servers can use to - verify the event. - title: Invite Signatures - properties: - signatures: - type: object - title: Signatures - additionalProperties: + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + type: + type: string + description: The event type. Must be `m.room.member` + example: m.room.member + room_id: + type: string + description: |- + The room ID the event is for. Must match the ID given in + the path. + example: "!abc123:matrix.org" + sender: + type: string + description: |- + The user ID of the user who sent the original `m.room.third_party_invite` + event. + example: "@joe:matrix.org" + state_key: + type: string + description: The user ID of the invited user + example: "@someone:example.org" + content: + type: object + description: The event content + title: Event Content + properties: + membership: + type: string + description: The membership state. Must be `invite` + example: invite + third_party_invite: + type: object + description: The third-party invite + title: Third-party Invite + properties: + display_name: + type: string + description: |- + A name which can be displayed to represent the user instead of their + third-party identifier. + example: alice + signed: + type: object + description: |- + A block of content which has been signed, which servers can use to + verify the event. + title: Invite Signatures + properties: + signatures: type: object + title: Signatures additionalProperties: - type: string - description: |- - The server signatures for this event. + type: object + additionalProperties: + type: string + description: |- + The server signatures for this event. - The signature is calculated using the process - described at [Signing JSON](/appendices/#signing-json). - example: { - "magic.forest": { - "ed25519:3": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg" - } - } - mxid: - type: string - description: The invited matrix user ID - example: "@alice:localhost" - token: - type: string - description: The token used to verify the event - example: abc123 - required: ['signatures', 'mxid', 'token'] - example: { - "mxid": "@alice:localhost", - "token": "abc123", - "signatures": { - "magic.forest": { - "ed25519:3": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg" - } - } - } - required: ['display_name', 'signed'] - example: { - "display_name": "alice", - "signed": { - "mxid": "@alice:localhost", - "token": "abc123", - "signatures": { - "magic.forest": { - "ed25519:3": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg" - } - } + The signature is calculated using the process + described at [Signing JSON](/appendices/#signing-json). + example: + magic.forest: + ed25519:3: fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg + mxid: + type: string + description: The invited matrix user ID + example: "@alice:localhost" + token: + type: string + description: The token used to verify the event + example: abc123 + required: + - signatures + - mxid + - token + example: + mxid: "@alice:localhost" + token: abc123 + signatures: + magic.forest: + ed25519:3: fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg + required: + - display_name + - signed + example: + display_name: alice + signed: + mxid: "@alice:localhost" + token: abc123 + signatures: + magic.forest: + ed25519:3: fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg + required: + - membership + - third_party_invite + example: + membership: invite + third_party_invite: + display_name: alice + signed: + mxid: "@alice:localhost" + token: abc123 + signatures: + magic.forest: + ed25519:3: fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg + required: + - type + - room_id + - sender + - state_key + - content + example: { + "type": "m.room.member", + "room_id": "!abc123:matrix.org", + "sender": "@joe:matrix.org", + "state_key": "@someone:example.org", + "content": { + "membership": "invite", + "third_party_invite": { + "display_name": "alice", + "signed": { + "mxid": "@alice:localhost", + "token": "abc123", + "signatures": { + "magic.forest": { + "ed25519:3": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg" } } - required: ['membership', 'third_party_invite'] - example: { - "membership": "invite", - "third_party_invite": { - "display_name": "alice", - "signed": { - "mxid": "@alice:localhost", - "token": "abc123", - "signatures": { - "magic.forest": { - "ed25519:3": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg" - } - } - } - } - } - required: - - type - - room_id - - sender - - state_key - - content - example: { - "type": "m.room.member", - "room_id": "!abc123:matrix.org", - "sender": "@joe:matrix.org", - "state_key": "@someone:example.org", - "content": { - "membership": "invite", - "third_party_invite": { - "display_name": "alice", - "signed": { - "mxid": "@alice:localhost", - "token": "abc123", - "signatures": { - "magic.forest": { - "ed25519:3": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg" - } } } } } - } + description: A partial `m.room.member` event + required: true responses: - 200: + "200": description: The invite has been issued successfully. - examples: - application/json: {} - schema: - type: object - description: An empty object - example: {} - "/3pid/onbind": + content: + application/json: + schema: + type: object + description: An empty object + example: {} + examples: + response: + value: {} + /3pid/onbind: put: summary: |- Notifies the server that a third-party identifier has been bound to one @@ -210,116 +196,137 @@ paths: has bound a third-party identifier successfully, including any pending room invites the identity server has been made aware of. operationId: onBindThirdPartyIdentifier - parameters: - - in: body - name: body - type: object - required: true - schema: - type: object - properties: - medium: - type: string - description: |- - The type of third-party identifier. Currently only "email" is - a possible value. - example: "email" - address: - type: string - description: |- - The third-party identifier itself. For example, an email address. - example: "alice@example.com" - mxid: - type: string - description: The user that is now bound to the third-party identifier. - example: "@alice:matrix.org" - invites: - type: array - description: |- - A list of pending invites that the third-party identifier has received. - items: - type: object - title: Third-party Invite - properties: - medium: - type: string - description: |- - The type of third-party invite issues. Currently only - "email" is used. - example: "email" - address: - type: string - description: |- - The third-party identifier that received the invite. - example: "alice@example.com" - mxid: - type: string - description: The now-bound user ID that received the invite. - example: "@alice:matrix.org" - room_id: - type: string - description: The room ID the invite is valid for. - example: "!somewhere:example.org" - sender: - type: string - description: The user ID that sent the invite. - example: "@bob:matrix.org" - # TODO (TravisR): Make this reusable when doing IS spec changes - # also make sure it isn't lying about anything, like the key version - signed: - type: object - title: Identity Server Signatures - description: |- - Signature from the identity server using a long-term private - key. - properties: - mxid: - type: string - description: |- - The user ID that has been bound to the third-party - identifier. - example: "@alice:matrix.org" - token: - type: string - # TODO: What is this actually? - description: A token. - example: "Hello World" - signatures: - type: object - title: Identity Server Signature - description: |- - The signature from the identity server. The `string` key - is the identity server's domain name, such as vector.im - additionalProperties: + requestBody: + content: + application/json: + schema: + type: object + properties: + medium: + type: string + description: |- + The type of third-party identifier. Currently only "email" is + a possible value. + example: email + address: + type: string + description: The third-party identifier itself. For example, an email address. + example: alice@example.com + mxid: + type: string + description: The user that is now bound to the third-party identifier. + example: "@alice:matrix.org" + invites: + type: array + description: A list of pending invites that the third-party identifier has + received. + items: + type: object + title: Third-party Invite + properties: + medium: + type: string + description: |- + The type of third-party invite issues. Currently only + "email" is used. + example: email + address: + type: string + description: The third-party identifier that received the invite. + example: alice@example.com + mxid: + type: string + description: The now-bound user ID that received the invite. + example: "@alice:matrix.org" + room_id: + type: string + description: The room ID the invite is valid for. + example: "!somewhere:example.org" + sender: + type: string + description: The user ID that sent the invite. + example: "@bob:matrix.org" + # TODO (TravisR): Make this reusable when doing IS spec changes + # also make sure it isn't lying about anything, like the key version + signed: + type: object + title: Identity Server Signatures + description: |- + Signature from the identity server using a long-term private + key. + properties: + mxid: + type: string + description: |- + The user ID that has been bound to the third-party + identifier. + example: "@alice:matrix.org" + token: + type: string + # TODO: What is this actually? + description: A token. + example: Hello World + signatures: type: object - title: Identity Server Domain Signature - description: The signature for the identity server. - properties: - "ed25519:0": - type: string - description: The signature. - example: "SomeSignatureGoesHere" - required: ['ed25519:0'] - example: { - "vector.im": { - "ed25519:0": "SomeSignatureGoesHere" - } - } - required: ['mxid', 'token', 'signatures'] - required: - - medium - - address - - mxid - - room_id - - sender - - signed - required: ['medium', 'address', 'mxid', 'invites'] + title: Identity Server Signature + description: |- + The signature from the identity server. The `string` key + is the identity server's domain name, such as vector.im + additionalProperties: + type: object + title: Identity Server Domain Signature + description: The signature for the identity server. + properties: + ed25519:0: + type: string + description: The signature. + example: SomeSignatureGoesHere + required: + - ed25519:0 + example: + vector.im: + ed25519:0: SomeSignatureGoesHere + required: + - mxid + - token + - signatures + required: + - medium + - address + - mxid + - room_id + - sender + - signed + required: + - medium + - address + - mxid + - invites + required: true responses: - 200: + "200": description: The homeserver has processed the notification. - examples: - application/json: {} - schema: - type: object - description: An empty object - example: {} + content: + application/json: + schema: + type: object + description: An empty object + example: {} + examples: + response: + value: {} +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8448 + basePath: + default: /_matrix/federation/v1 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/server-server/transactions.yaml b/data/api/server-server/transactions.yaml index d2aab20d..1ca2ed3c 100644 --- a/data/api/server-server/transactions.yaml +++ b/data/api/server-server/transactions.yaml @@ -11,21 +11,10 @@ # 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. - -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Federation Transaction API" - version: "1.0.0" -host: localhost:8448 -schemes: - - https -basePath: /_matrix/federation/v1 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Federation Transaction API + version: 1.0.0 paths: "/send/{txnId}": put: @@ -46,60 +35,80 @@ paths: parameters: - in: path name: txnId - type: string - description: |- - The transaction ID. - required: true - x-example: S0meTransacti0nId - - in: body - name: body - type: object + description: The transaction ID. required: true + example: S0meTransacti0nId schema: - allOf: - - $ref: "definitions/transaction.yaml" - - type: object - properties: - edus: - type: array - description: |- - List of ephemeral messages. May be omitted if there are no ephemeral - messages to be sent. Must not include more than 100 EDUs. - items: - $ref: "definitions/edu_with_example.yaml" + type: string + requestBody: + content: + application/json: + schema: + allOf: + - $ref: definitions/transaction.yaml + - type: object + properties: + edus: + type: array + description: |- + List of ephemeral messages. May be omitted if there are no ephemeral + messages to be sent. Must not include more than 100 EDUs. + items: + $ref: definitions/edu_with_example.yaml + type: object + required: true responses: - 200: + "200": description: |- The result of processing the transaction. The server is to use this response even in the event of one or more PDUs failing to be processed. - schema: - type: object - title: PDU Processing Results - description: The results for the processing of each PDU in the transaction. - properties: - pdus: + content: + application/json: + schema: type: object - 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." - required: ['pdus'] - examples: - application/json: { - "pdus": { - "$successful_event:example.org": {}, - "$failed_event:example.org": { - "error": "You are not allowed to send a message to this room." - } - } - } + title: PDU Processing Results + description: The results for the processing of each PDU in the transaction. + properties: + pdus: + type: object + 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. + required: + - pdus + examples: + response: + value: { + "pdus": { + "$successful_event:example.org": {}, + "$failed_event:example.org": { + "error": "You are not allowed to send a message to this room." + } + } + } +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8448 + basePath: + default: /_matrix/federation/v1 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/server-server/user_devices.yaml b/data/api/server-server/user_devices.yaml index 14242867..a0022f56 100644 --- a/data/api/server-server/user_devices.yaml +++ b/data/api/server-server/user_devices.yaml @@ -12,21 +12,10 @@ # 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. - -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Federation User Device Management API" - version: "1.0.0" -host: localhost:8448 -schemes: - - https -basePath: /_matrix/federation/v1 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Federation User Device Management API + version: 1.0.0 paths: "/user/devices/{userId}": get: @@ -38,80 +27,97 @@ paths: parameters: - in: path name: userId - type: string required: true description: |- The user ID to retrieve devices for. Must be a user local to the receiving homeserver. - x-example: "@alice:example.org" - responses: - 200: - description: The user's devices. + example: "@alice:example.org" schema: - type: object - properties: - user_id: - type: string - description: The user ID devices were requested for. - example: "@alice:example.org" - stream_id: - type: integer - description: |- - A unique ID for a given user_id which describes the version of - the returned device list. This is matched with the `stream_id` - field in `m.device_list_update` EDUs in order to incrementally - update the returned device_list. - example: 5 - devices: - type: array - description: The user's devices. May be empty. - items: - type: object - title: User Device - properties: - device_id: - type: string - description: The device ID. - example: "JLAFKJWSCS" - keys: + type: string + responses: + "200": + description: The user's devices. + content: + application/json: + schema: + type: object + properties: + user_id: + type: string + description: The user ID devices were requested for. + example: "@alice:example.org" + stream_id: + type: integer + description: |- + A unique ID for a given user_id which describes the version of + the returned device list. This is matched with the `stream_id` + field in `m.device_list_update` EDUs in order to incrementally + update the returned device_list. + example: 5 + devices: + type: array + description: The user's devices. May be empty. + items: type: object - description: Identity keys for the device. - allOf: - - $ref: "../client-server/definitions/device_keys.yaml" - device_display_name: - type: string - description: Optional display name for the device. - example: "Alice's Mobile Phone" - required: ['device_id', 'keys'] - master_key: - type: object - description: |- - The user\'s master cross-signing key. - allOf: - - $ref: ../client-server/definitions/cross_signing_key.yaml - - example: { - "user_id": "@alice:example.com", - "usage": ["master"], - "keys": { - "ed25519:base64+master+public+key": "base64+master+public+key", - } - } - self_signing_key: - type: object - description: |- - The user\'s self-signing key. - allOf: - - $ref: ../client-server/definitions/cross_signing_key.yaml - - example: { - "user_id": "@alice:example.com", - "usage": ["self_signing"], - "keys": { - "ed25519:base64+self+signing+public+key": "base64+self+signing+master+public+key", - }, - "signatures": { - "@alice:example.com": { - "ed25519:base64+master+public+key": "signature+of+self+signing+key" - } - } - } - required: ['user_id', 'stream_id', 'devices'] + title: User Device + properties: + device_id: + type: string + description: The device ID. + example: JLAFKJWSCS + keys: + type: object + description: Identity keys for the device. + allOf: + - $ref: ../client-server/definitions/device_keys.yaml + device_display_name: + type: string + description: Optional display name for the device. + example: Alice's Mobile Phone + required: + - device_id + - keys + master_key: + type: object + description: The user\'s master cross-signing key. + allOf: + - $ref: ../client-server/definitions/cross_signing_key.yaml + - example: + user_id: "@alice:example.com" + usage: + - master + keys: + ed25519:base64+master+public+key: base64+master+public+key + self_signing_key: + type: object + description: The user\'s self-signing key. + allOf: + - $ref: ../client-server/definitions/cross_signing_key.yaml + - example: + user_id: "@alice:example.com" + usage: + - self_signing + keys: + ed25519:base64+self+signing+public+key: base64+self+signing+master+public+key + signatures: + "@alice:example.com": + ed25519:base64+master+public+key: signature+of+self+signing+key + required: + - user_id + - stream_id + - devices +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8448 + basePath: + default: /_matrix/federation/v1 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/server-server/user_keys.yaml b/data/api/server-server/user_keys.yaml index fe84cbbd..60995a74 100644 --- a/data/api/server-server/user_keys.yaml +++ b/data/api/server-server/user_keys.yaml @@ -12,246 +12,240 @@ # 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. - -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Federation User Key Management API" - version: "1.0.0" -host: localhost:8448 -schemes: - - https -basePath: /_matrix/federation/v1 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Federation User Key Management API + version: 1.0.0 paths: - "/user/keys/claim": + /user/keys/claim: post: summary: Claims one-time encryption keys for a user. - description: |- - Claims one-time keys for use in pre-key messages. + description: Claims one-time keys for use in pre-key messages. operationId: claimUserEncryptionKeys security: - signedRequest: [] - parameters: - - in: body - name: body - type: object - required: true - schema: - type: object - properties: - one_time_keys: - type: object - description: |- - The keys to be claimed. A map from user ID, to a map from - device ID to algorithm name. - additionalProperties: + requestBody: + content: + application/json: + schema: + type: object + properties: + one_time_keys: type: object - additionalProperties: - type: string - description: algorithm - example: "signed_curve25519" - example: { - "@alice:example.com": { - "JLAFKJWSCS": "signed_curve25519" - } - } - required: - - one_time_keys - responses: - 200: - description: The claimed keys. - schema: - type: object - properties: - one_time_keys: - type: object - description: |- - One-time keys for the queried devices. A map from user ID, to a - map from devices to a map from `:` to the key object. - - 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 + description: |- + The keys to be claimed. A map from user ID, to a map from + device ID to algorithm name. additionalProperties: type: object - # Key + additionalProperties: + type: string + description: algorithm + example: signed_curve25519 + example: + "@alice:example.com": + JLAFKJWSCS: signed_curve25519 + required: + - one_time_keys + required: true + responses: + "200": + description: The claimed keys. + content: + application/json: + schema: + type: object + properties: + one_time_keys: + type: object + description: |- + One-time keys for the queried devices. A map from user ID, to a + map from devices to a map from `:` to the key object. + + See the [Client-Server Key Algorithms](/client-server-api/#key-algorithms) section for more information on + the Key Object format. + # User additionalProperties: type: object - title: KeyObject - properties: - key: - type: string - description: The key, encoded using unpadded base64. - signatures: + # Device + additionalProperties: + type: object + # Key + additionalProperties: type: object - title: Signatures - additionalProperties: - type: object - additionalProperties: + title: KeyObject + properties: + key: type: string - description: |- - Signature of the key object. + description: The key, encoded using unpadded base64. + signatures: + type: object + title: Signatures + additionalProperties: + 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'] - example: { - "@alice:example.com": { - "JLAFKJWSCS": { - "signed_curve25519:AAAAHg": { - "key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs", - "signatures": { - "@alice:example.com": { - "ed25519:JLAFKJWSCS": "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw" + The signature is calculated using the process described at [Signing JSON](/appendices/#signing-json). + 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. + description: Returns the current devices and identity keys for the given users. + operationId: queryUserEncryptionKeys + security: + - signedRequest: [] + requestBody: + content: + application/json: + schema: + type: object + properties: + device_keys: + type: object + description: |- + 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 + example: + "@alice:example.com": [] + required: + - device_keys + required: true + responses: + "200": + description: The device information. + content: + application/json: + schema: + type: object + properties: + device_keys: + type: object + description: |- + Information on the queried devices. A map from user ID, to a + map from device ID to device information. For each device, + 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. + master_keys: + x-addedInMatrixVersion: "1.1" + type: object + description: |- + Information on the master cross-signing keys of the queried users. + A map from user ID, to master key information. For each key, the + information returned will be the same as uploaded via + `/keys/device_signing/upload`, along with the signatures + uploaded via `/keys/signatures/upload` that the user is + allowed to see. + additionalProperties: + allOf: + - $ref: ../client-server/definitions/cross_signing_key.yaml + example: + "@alice:example.com": + user_id: "@alice:example.com" + usage: + - master + keys: + ed25519:base64+master+public+key: base64+master+public+key + self_signing_keys: + x-addedInMatrixVersion: "1.1" + type: object + description: |- + Information on the self-signing keys of the queried users. A map + 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: + allOf: + - $ref: ../client-server/definitions/cross_signing_key.yaml + example: + "@alice:example.com": + user_id: "@alice:example.com" + usage: + - self_signing + keys: + ed25519:base64+self+signing+public+key: base64+self+signing+master+public+key + signatures: + "@alice:example.com": + ed25519:base64+master+public+key: signature+of+self+signing+key + required: + - device_keys + examples: + response: + value: { + "device_keys": { + "@alice:example.com": { + "JLAFKJWSCS": { + "user_id": "@alice:example.com", + "device_id": "JLAFKJWSCS", + "algorithms": [ + "m.olm.v1.curve25519-aes-sha2", + "m.megolm.v1.aes-sha2" + ], + "keys": { + "curve25519:JLAFKJWSCS": "3C5BFWi2Y8MaVvjM8M22DBmh24PmgR0nPvJOIArzgyI", + "ed25519:JLAFKJWSCS": "lEuiRJBit0IG6nUf5pUzWTUEsRVVe/HJkoKuEww9ULI" + }, + "signatures": { + "@alice:example.com": { + "ed25519:JLAFKJWSCS": "dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA" + } + }, + "unsigned": { + "device_display_name": "Alice's mobile phone" } } } } } - } - required: ['one_time_keys'] - "/user/keys/query": - post: - summary: Download device identity keys. - description: |- - Returns the current devices and identity keys for the given users. - operationId: queryUserEncryptionKeys - security: - - signedRequest: [] - parameters: - - in: body - name: body - type: object - required: true - schema: - type: object - properties: - device_keys: - type: object - description: |- - 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" - example: { - "@alice:example.com": [] - } - required: ['device_keys'] - responses: - 200: - description: The device information. - schema: - type: object - properties: - device_keys: - type: object - description: |- - Information on the queried devices. A map from user ID, to a - map from device ID to device information. For each device, - 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. - master_keys: - x-addedInMatrixVersion: "1.1" - type: object - description: |- - Information on the master cross-signing keys of the queried users. - A map from user ID, to master key information. For each key, the - information returned will be the same as uploaded via - `/keys/device_signing/upload`, along with the signatures - uploaded via `/keys/signatures/upload` that the user is - allowed to see. - additionalProperties: - allOf: - - $ref: ../client-server/definitions/cross_signing_key.yaml - example: { - "@alice:example.com": { - "user_id": "@alice:example.com", - "usage": ["master"], - "keys": { - "ed25519:base64+master+public+key": "base64+master+public+key", - } - } - } - self_signing_keys: - x-addedInMatrixVersion: "1.1" - type: object - description: |- - Information on the self-signing keys of the queried users. A map - 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: - allOf: - - $ref: ../client-server/definitions/cross_signing_key.yaml - example: { - "@alice:example.com": { - "user_id": "@alice:example.com", - "usage": ["self_signing"], - "keys": { - "ed25519:base64+self+signing+public+key": "base64+self+signing+master+public+key", - }, - "signatures": { - "@alice:example.com": { - "ed25519:base64+master+public+key": "signature+of+self+signing+key" - } - } - } - } - required: ['device_keys'] - examples: - application/json: { - "device_keys": { - "@alice:example.com": { - "JLAFKJWSCS": { - "user_id": "@alice:example.com", - "device_id": "JLAFKJWSCS", - "algorithms": [ - "m.olm.v1.curve25519-aes-sha2", - "m.megolm.v1.aes-sha2" - ], - "keys": { - "curve25519:JLAFKJWSCS": "3C5BFWi2Y8MaVvjM8M22DBmh24PmgR0nPvJOIArzgyI", - "ed25519:JLAFKJWSCS": "lEuiRJBit0IG6nUf5pUzWTUEsRVVe/HJkoKuEww9ULI" - }, - "signatures": { - "@alice:example.com": { - "ed25519:JLAFKJWSCS": "dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA" - } - }, - "unsigned": { - "device_display_name": "Alice's mobile phone" - } - } - } - } - } +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8448 + basePath: + default: /_matrix/federation/v1 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/server-server/version.yaml b/data/api/server-server/version.yaml index 929f7b91..2ec59bf8 100644 --- a/data/api/server-server/version.yaml +++ b/data/api/server-server/version.yaml @@ -11,44 +11,52 @@ # 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. - -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Federation Version API" - version: "1.0.0" -host: localhost:8448 -schemes: - - https -basePath: /_matrix/federation/v1 -produces: - - application/json + title: Matrix Federation Version API + version: 1.0.0 paths: - "/version": + /version: get: summary: Get the implementation name and version of this homeserver. description: Get the implementation name and version of this homeserver. operationId: getVersion responses: - 200: - description: - The implementation name and version of this homeserver. - examples: - application/json: { - "server": { - "name": "My_Homeserver_Implementation", - "version": "ArbitraryVersionNumber" - } - } - schema: - type: object - properties: - server: - title: Server + "200": + description: The implementation name and version of this homeserver. + content: + application/json: + schema: type: object properties: - name: - type: string - description: Arbitrary name that identify this implementation. - version: - type: string - description: Version of this implementation. The version format depends on the implementation. + server: + title: Server + type: object + properties: + name: + type: string + description: Arbitrary name that identify this implementation. + version: + type: string + description: Version of this implementation. The version format depends on the + implementation. + examples: + response: + value: { + "server": { + "name": "My_Homeserver_Implementation", + "version": "ArbitraryVersionNumber" + } + } +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8448 + basePath: + default: /_matrix/federation/v1 diff --git a/data/api/server-server/wellknown.yaml b/data/api/server-server/wellknown.yaml index c1a060d9..717462f9 100644 --- a/data/api/server-server/wellknown.yaml +++ b/data/api/server-server/wellknown.yaml @@ -11,43 +11,53 @@ # 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. -swagger: '2.0' +openapi: 3.1.0 info: - title: "Matrix Federation Server Discovery API" - version: "1.0.0" -host: localhost:443 -schemes: - - https -basePath: /.well-known -produces: - - application/json + title: Matrix Federation Server Discovery API + version: 1.0.0 paths: - "/matrix/server": + /matrix/server: get: - summary: Gets information about the delegated server for server-server communication. + summary: Gets information about the delegated server for server-server + communication. description: |- Gets information about the delegated server for server-server communication between Matrix homeservers. Servers should follow 30x redirects, carefully avoiding redirect loops, and use normal X.509 certificate validation. operationId: getWellKnown responses: - 200: - description: - The delegated server information. The `Content-Type` for this response SHOULD - be `application/json`, however servers parsing the response should assume that - the body is JSON regardless of type. Failures parsing the JSON or invalid data - provided in the resulting parsed JSON should not result in discovery failure - - consult the server discovery process for information on how to continue. - examples: - application/json: { - "m.server": "delegated.example.com:1234" - } - schema: - type: object - properties: - "m.server": - type: string - description: |- - The server name to delegate server-server communications to, with optional - port. The delegated server name uses the same grammar as - [server names in the appendices](/appendices/#server-name). + "200": + description: The delegated server information. The `Content-Type` for this + response SHOULD be `application/json`, however servers parsing the + response should assume that the body is JSON regardless of type. + Failures parsing the JSON or invalid data provided in the resulting + parsed JSON should not result in discovery failure - consult the + server discovery process for information on how to continue. + content: + application/json: + schema: + type: object + properties: + m.server: + type: string + description: |- + The server name to delegate server-server communications to, with optional + port. The delegated server name uses the same grammar as + [server names in the appendices](/appendices/#server-name). + examples: + response: + value: { + "m.server": "delegated.example.com:1234" + } +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost + basePath: + default: /.well-known diff --git a/layouts/partials/json-schema/resolve-additional-types.html b/layouts/partials/json-schema/resolve-additional-types.html index a8f25be4..58710076 100644 --- a/layouts/partials/json-schema/resolve-additional-types.html +++ b/layouts/partials/json-schema/resolve-additional-types.html @@ -70,8 +70,8 @@ {{/* Add any nested objects referenced in this object's `items` */}} - {{ if reflect.IsSlice $this_object.items}} - {{ range $idx, $item := $this_object.items }} + {{ if $this_object.items.anyOf }} + {{ range $idx, $item := $this_object.items.anyOf }} {{ $additional_objects = partial "get-additional-objects" (dict "this_object" $item "additional_objects" $additional_objects diff --git a/layouts/partials/openapi/render-object-table.html b/layouts/partials/openapi/render-object-table.html index 67e3dc01..5c38be87 100644 --- a/layouts/partials/openapi/render-object-table.html +++ b/layouts/partials/openapi/render-object-table.html @@ -102,9 +102,16 @@ internal structure, handle this with a bit of recursion */}} {{ $type = delimit (slice "{string: " (partial "type-or-title" .additionalProperties) "}" ) "" }} - {{ else if reflect.IsSlice .type }} + {{ else if and .oneOf (reflect.IsSlice .oneOf) }} {{/* It's legal to specify an array of types. Join them together in that case */}} - {{ $type = delimit .type "|" }} + + {{ $types := slice }} + + {{ range .oneOf }} + {{ $types = $types | append .type }} + {{ end }} + + {{ $type = delimit $types "|" }} {{ else }} {{ $type = .type }} {{ end }} diff --git a/layouts/partials/openapi/render-operation.html b/layouts/partials/openapi/render-operation.html index 1e480671..6486f39c 100644 --- a/layouts/partials/openapi/render-operation.html +++ b/layouts/partials/openapi/render-operation.html @@ -64,7 +64,7 @@
-{{ partial "openapi/render-request" (dict "parameters" $operation_data.parameters "path" $path "anchor_base" $anchor ) }} +{{ partial "openapi/render-request" (dict "parameters" $operation_data.parameters "request_body" $operation_data.requestBody "path" $path "anchor_base" $anchor ) }}
{{ partial "openapi/render-responses" (dict "responses" $operation_data.responses "path" $path "anchor_base" $anchor ) }} diff --git a/layouts/partials/openapi/render-parameters.html b/layouts/partials/openapi/render-parameters.html index b7861b7f..0e643a25 100644 --- a/layouts/partials/openapi/render-parameters.html +++ b/layouts/partials/openapi/render-parameters.html @@ -21,7 +21,13 @@ {{/* build a dict mapping from name->parameter, which render-object-table expects */}} {{ $param_dict := dict }} {{ range $parameter := . }} - {{ $param_dict = merge $param_dict (dict $parameter.name $parameter )}} + {{/* + merge the schema at the same level as the rest of the other fields because that is + what `render-object-table` expects. Put the schema first so examples in it are + overwritten. + */}} + {{ $param := merge $parameter.schema $parameter }} + {{ $param_dict = merge $param_dict (dict $parameter.name $param )}} {{ end }} {{/* and render the parameters */}} diff --git a/layouts/partials/openapi/render-request.html b/layouts/partials/openapi/render-request.html index be39fa38..36b846da 100644 --- a/layouts/partials/openapi/render-request.html +++ b/layouts/partials/openapi/render-request.html @@ -3,6 +3,7 @@ Render the request part of a single HTTP API operation, given: * `parameters`: OpenAPI/Swagger data specifying the parameters + * `request_body`: OpenAPI/Swagger data specifying the request body * `path`: the path where this definition was found, to enable us to resolve "$ref" * `anchor_base`: a prefix to add to the HTML anchors generated for each object @@ -14,48 +15,57 @@ */}} {{ $parameters := .parameters }} +{{ $request_body := .request_body }} {{ $path := .path }} {{ $anchor_base := .anchor_base }}

Request

-{{ if $parameters }} +{{ if or $parameters $request_body }} - {{ $simple_parameters := where $parameters "in" "!=" "body"}} - {{ if $simple_parameters }} + {{ if $parameters }}

Request parameters

- {{ partial "openapi/render-parameters" (dict "parameters" $simple_parameters "type" "header" "caption" "header parameters") }} - {{ partial "openapi/render-parameters" (dict "parameters" $simple_parameters "type" "path" "caption" "path parameters") }} - {{ partial "openapi/render-parameters" (dict "parameters" $simple_parameters "type" "query" "caption" "query parameters") }} + {{ partial "openapi/render-parameters" (dict "parameters" $parameters "type" "header" "caption" "header parameters") }} + {{ partial "openapi/render-parameters" (dict "parameters" $parameters "type" "path" "caption" "path parameters") }} + {{ partial "openapi/render-parameters" (dict "parameters" $parameters "type" "query" "caption" "query parameters") }} {{ end }} - {{ $body_parameters := where $parameters "in" "body"}} - {{ if $body_parameters }} + {{ if $request_body }}

Request body

+ {{/* + A request can have several content types. Only show the schema for JSON. + */}} + {{ $json_body := index $request_body.content "application/json" }} + {{ if $json_body }} + {{ $schema := partial "json-schema/resolve-refs" (dict "schema" $json_body.schema "path" $path) }} + {{ $schema := partial "json-schema/resolve-allof" $schema }} - {{/* at most one body param is allowed by the spec */}} - {{ $body_parameter := index $body_parameters 0 }} - {{ $schema := partial "json-schema/resolve-refs" (dict "schema" $body_parameter.schema "path" $path) }} - {{ $schema := partial "json-schema/resolve-allof" $schema }} - - {{ $additional_types := partial "json-schema/resolve-additional-types" (dict "schema" $schema "anchor_base" $anchor_base) }} - {{ $additional_types = uniq $additional_types }} - {{ range $additional_types }} - {{ partial "openapi/render-object-table" . }} + {{ $additional_types := partial "json-schema/resolve-additional-types" (dict "schema" $schema "anchor_base" $anchor_base) }} + {{ $additional_types = uniq $additional_types }} + {{ range $additional_types }} + {{ partial "openapi/render-object-table" . }} + {{ end }} {{ end }}

Request body example

+ {{/* + Show all the examples. + */}} + {{ range $mime, $body := $request_body.content }} + {{ $schema := partial "json-schema/resolve-refs" (dict "schema" $body.schema "path" $path) }} + {{ $schema := partial "json-schema/resolve-allof" $schema }} - {{ $example := partial "json-schema/resolve-example" $schema }} - {{ $example_json := jsonify (dict "indent" " ") $example }} - {{ $example_json = replace $example_json "\\u003c" "<" }} - {{ $example_json = replace $example_json "\\u003e" ">" | safeHTML }} + {{ $example := partial "json-schema/resolve-example" $schema }} + {{ $example_json := jsonify (dict "indent" " ") $example }} + {{ $example_json = replace $example_json "\\u003c" "<" }} + {{ $example_json = replace $example_json "\\u003e" ">" | safeHTML }} ```json {{ $example_json }} ``` + {{ end }} {{ end }} {{ else }} diff --git a/layouts/partials/openapi/render-responses.html b/layouts/partials/openapi/render-responses.html index 9c59b0f2..9ef643e5 100644 --- a/layouts/partials/openapi/render-responses.html +++ b/layouts/partials/openapi/render-responses.html @@ -38,11 +38,19 @@ {{ range $code, $response := $responses }} - {{ if $response.schema }} + {{/* + A response can have several content types so only insert the title once. + */}} + {{ $is_title_set := false }} + {{ range $content_type, $content := $response.content }} + {{ if $content.schema }} + {{ if not $is_title_set }} + {{ $is_title_set = true }}

{{$code}} response

+ {{ end }} - {{ $schema := partial "json-schema/resolve-refs" (dict "schema" $response.schema "path" $path) }} + {{ $schema := partial "json-schema/resolve-refs" (dict "schema" $content.schema "path" $path) }} {{ $schema := partial "json-schema/resolve-allof" $schema }} {{/* @@ -51,9 +59,9 @@ */}} {{ if eq $schema.type "array" }} {{ $type_of := "" }} - {{ if reflect.IsSlice $schema.items }} + {{ if $schema.items.anyOf }} {{ $types := slice }} - {{ range $schema.items }} + {{ range $schema.items.anyOf }} {{ if .title }} {{ $types = $types | append .title}} {{ else }} @@ -84,9 +92,9 @@ */}} {{ if or (eq $schema.type "object") (eq $schema.type "array") }} {{ $example := partial "json-schema/resolve-example" $schema }} - {{ if $response.examples }} - {{ $example = partial "json-schema/resolve-refs" (dict "schema" $response.examples "path" $path) }} - {{ $example = index $example "application/json" }} + {{ if $content.examples }} + {{ $example = partial "json-schema/resolve-refs" (dict "schema" $content.examples "path" $path) }} + {{ $example = $example.response.value }} {{ end }} {{ $example_json := jsonify (dict "indent" " ") $example }} @@ -96,6 +104,7 @@ ```json {{ $example_json }} ``` + {{ end }} {{ end }} {{ end }} {{ end }} diff --git a/layouts/shortcodes/http-api.html b/layouts/shortcodes/http-api.html index 32e0ad41..2668b1ab 100644 --- a/layouts/shortcodes/http-api.html +++ b/layouts/shortcodes/http-api.html @@ -20,7 +20,7 @@ {{ $api := .Params.api}} {{ $api_data := index .Site.Data.api .Params.spec .Params.api }} -{{ $base_url := $api_data.basePath }} +{{ $base_url := (index $api_data.servers 0).variables.basePath.default }} {{ $path := delimit (slice "api" $spec) "/" }} {{ partial "openapi/render-api" (dict "api_data" $api_data "base_url" $base_url "path" $path) }} diff --git a/scripts/dump-swagger.py b/scripts/dump-swagger.py index 82de8763..ce97c4c3 100755 --- a/scripts/dump-swagger.py +++ b/scripts/dump-swagger.py @@ -133,16 +133,15 @@ base_url = args.base_url.rstrip("/") logging.basicConfig() output = { - "basePath": "/", - "consumes": ["application/json"], - "produces": ["application/json"], - "host": "matrix.org", # The servers value will be picked up by RapiDoc to provide a way # to switch API servers. Useful when one wants to test compliance # of their server with the API. "servers": [ { - "url": "https://{homeserver_address}/", + "url": "https://matrix.org", + }, + { + "url": "https://{homeserver_address}", "variables": { "homeserver_address": { "default": "matrix-client.matrix.org", @@ -151,20 +150,21 @@ output = { }, } ], - "schemes": ["https"], "info": { "title": available_apis[selected_api], "version": release_label, }, - "securityDefinitions": {}, + "components": { + "securitySchemes": {} + }, "paths": {}, - "swagger": "2.0", + "openapi": "3.1.0", } selected_api_dir = os.path.join(api_dir, selected_api) try: with open(os.path.join(selected_api_dir, 'definitions', 'security.yaml')) as f: - output['securityDefinitions'] = yaml.safe_load(f) + output['components']['securitySchemes'] = yaml.safe_load(f) except FileNotFoundError: print("No security definitions available for this API") @@ -174,12 +174,12 @@ for filename in os.listdir(selected_api_dir): continue filepath = os.path.join(selected_api_dir, filename) - print("Reading swagger API: %s" % filepath) + print("Reading OpenAPI: %s" % filepath) with open(filepath, "r") as f: api = yaml.safe_load(f.read()) api = resolve_references(filepath, api) - basePath = api['basePath'] + basePath = api['servers'][0]['variables']['basePath']['default'] for path, methods in api["paths"].items(): path = basePath + path for method, spec in methods.items(): diff --git a/scripts/package-lock.json b/scripts/package-lock.json index 5e3937c2..6b6e5328 100644 --- a/scripts/package-lock.json +++ b/scripts/package-lock.json @@ -9,19 +9,18 @@ "version": "0.0.1", "license": "ISC", "dependencies": { - "nopt": "^3.0.2", - "swagger-parser": "^10.0.3" + "@apidevtools/swagger-parser": "^10.1.0", + "nopt": "^3.0.2" } }, "node_modules/@apidevtools/json-schema-ref-parser": { - "version": "9.0.9", - "resolved": "https://registry.npmjs.org/@apidevtools/json-schema-ref-parser/-/json-schema-ref-parser-9.0.9.tgz", - "integrity": "sha512-GBD2Le9w2+lVFoc4vswGI/TjkNIZSVp7+9xPf+X3uidBfWnAeUWmquteSyt0+VCrhNMWj/FTABISQrD3Z/YA+w==", + "version": "9.0.6", + "resolved": "https://registry.npmjs.org/@apidevtools/json-schema-ref-parser/-/json-schema-ref-parser-9.0.6.tgz", + "integrity": "sha512-M3YgsLjI0lZxvrpeGVk9Ap032W6TPQkH6pRAZz81Ac3WUNF79VQooAFnp8umjvVzUmD93NkogxEwbSce7qMsUg==", "dependencies": { "@jsdevtools/ono": "^7.1.3", - "@types/json-schema": "^7.0.6", "call-me-maybe": "^1.0.1", - "js-yaml": "^4.1.0" + "js-yaml": "^3.13.1" } }, "node_modules/@apidevtools/openapi-schemas": { @@ -38,16 +37,17 @@ "integrity": "sha512-QAkD5kK2b1WfjDS/UQn/qQkbwF31uqRjPTrsCs5ZG9BQGAkjwvqGFjjPqAuzac/IYzpPtRzjCP1WrTuAIjMrXg==" }, "node_modules/@apidevtools/swagger-parser": { - "version": "10.0.3", - "resolved": "https://registry.npmjs.org/@apidevtools/swagger-parser/-/swagger-parser-10.0.3.tgz", - "integrity": "sha512-sNiLY51vZOmSPFZA5TF35KZ2HbgYklQnTSDnkghamzLb3EkNtcQnrBQEj5AOCxHpTtXpqMCRM1CrmV2rG6nw4g==", + "version": "10.1.0", + "resolved": "https://registry.npmjs.org/@apidevtools/swagger-parser/-/swagger-parser-10.1.0.tgz", + "integrity": "sha512-9Kt7EuS/7WbMAUv2gSziqjvxwDbFSg3Xeyfuj5laUODX8o/k/CpsAKiQ8W7/R88eXFTMbJYg6+7uAmOWNKmwnw==", "dependencies": { - "@apidevtools/json-schema-ref-parser": "^9.0.6", - "@apidevtools/openapi-schemas": "^2.0.4", + "@apidevtools/json-schema-ref-parser": "9.0.6", + "@apidevtools/openapi-schemas": "^2.1.0", "@apidevtools/swagger-methods": "^3.0.2", "@jsdevtools/ono": "^7.1.3", - "call-me-maybe": "^1.0.1", - "z-schema": "^5.0.1" + "ajv": "^8.6.3", + "ajv-draft-04": "^1.0.0", + "call-me-maybe": "^1.0.1" }, "peerDependencies": { "openapi-types": ">=7" @@ -58,52 +58,85 @@ "resolved": "https://registry.npmjs.org/@jsdevtools/ono/-/ono-7.1.3.tgz", "integrity": "sha512-4JQNk+3mVzK3xh2rqd6RB4J46qUR19azEHBneZyTZM+c456qOrbbM/5xcR8huNCCcbVt7+UmizG6GuUvPvKUYg==" }, - "node_modules/@types/json-schema": { - "version": "7.0.9", - "resolved": "https://registry.npmjs.org/@types/json-schema/-/json-schema-7.0.9.tgz", - "integrity": "sha512-qcUXuemtEu+E5wZSJHNxUXeCZhAfXKQ41D+duX+VYPde7xyEVZci+/oXKJL13tnRs9lR2pr4fod59GT6/X1/yQ==" - }, "node_modules/abbrev": { "version": "1.1.1", "resolved": "https://registry.npmjs.org/abbrev/-/abbrev-1.1.1.tgz", "integrity": "sha512-nne9/IiQ/hzIhY6pdDnbBtz7DjPTKrY00P/zvPSm5pOFkl6xuGrGnXn/VtTNNfNtAfZ9/1RtehkszU9qcTii0Q==" }, + "node_modules/ajv": { + "version": "8.11.0", + "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.11.0.tgz", + "integrity": "sha512-wGgprdCvMalC0BztXvitD2hC04YffAvtsUn93JbGXYLAtCUO4xd17mCCZQxUOItiBwZvJScWo8NIvQMQ71rdpg==", + "dependencies": { + "fast-deep-equal": "^3.1.1", + "json-schema-traverse": "^1.0.0", + "require-from-string": "^2.0.2", + "uri-js": "^4.2.2" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/epoberezkin" + } + }, + "node_modules/ajv-draft-04": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/ajv-draft-04/-/ajv-draft-04-1.0.0.tgz", + "integrity": "sha512-mv00Te6nmYbRp5DCwclxtt7yV/joXJPGS7nM+97GdxvuttCOfgI3K4U25zboyeX0O+myI8ERluxQe5wljMmVIw==", + "peerDependencies": { + "ajv": "^8.5.0" + }, + "peerDependenciesMeta": { + "ajv": { + "optional": true + } + } + }, "node_modules/argparse": { - "version": "2.0.1", - "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz", - "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==" + "version": "1.0.10", + "resolved": "https://registry.npmjs.org/argparse/-/argparse-1.0.10.tgz", + "integrity": "sha512-o5Roy6tNG4SL/FOkCAN6RzjiakZS25RLYFrcMttJqbdd8BWrnA+fGz57iN5Pb06pvBGvl5gQ0B48dJlslXvoTg==", + "dependencies": { + "sprintf-js": "~1.0.2" + } }, "node_modules/call-me-maybe": { "version": "1.0.1", "resolved": "https://registry.npmjs.org/call-me-maybe/-/call-me-maybe-1.0.1.tgz", - "integrity": "sha1-JtII6onje1y95gJQoV8DHBak1ms=" + "integrity": "sha512-wCyFsDQkKPwwF8BDwOiWNx/9K45L/hvggQiDbve+viMNMQnWhrlYIuBk09offfwCRtCO9P6XwUttufzU11WCVw==" }, - "node_modules/commander": { - "version": "2.20.3", - "resolved": "https://registry.npmjs.org/commander/-/commander-2.20.3.tgz", - "integrity": "sha512-GpVkmM8vF2vQUkj2LvZmD35JxeJOLCwJ9cUkugyk2nuhbv3+mJvpLYYt+0+USMxE+oj+ey/lJEnhZw75x/OMcQ==", - "optional": true + "node_modules/esprima": { + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/esprima/-/esprima-4.0.1.tgz", + "integrity": "sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A==", + "bin": { + "esparse": "bin/esparse.js", + "esvalidate": "bin/esvalidate.js" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/fast-deep-equal": { + "version": "3.1.3", + "resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz", + "integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==" }, "node_modules/js-yaml": { - "version": "4.1.0", - "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.0.tgz", - "integrity": "sha512-wpxZs9NoxZaJESJGIZTyDEaYpl0FKSA+FB9aJiyemKhMwkxQg63h4T1KJgUGHpTqPDNRcmmYLugrRjJlBtWvRA==", + "version": "3.14.1", + "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-3.14.1.tgz", + "integrity": "sha512-okMH7OXXJ7YrN9Ok3/SXrnu4iX9yOk+25nqX4imS2npuvTYDmo/QEZoqwZkYaIDk3jVvBOTOIEgEhaLOynBS9g==", "dependencies": { - "argparse": "^2.0.1" + "argparse": "^1.0.7", + "esprima": "^4.0.0" }, "bin": { "js-yaml": "bin/js-yaml.js" } }, - "node_modules/lodash.get": { - "version": "4.4.2", - "resolved": "https://registry.npmjs.org/lodash.get/-/lodash.get-4.4.2.tgz", - "integrity": "sha1-LRd/ZS+jHpObRDjVNBSZ36OCXpk=" - }, - "node_modules/lodash.isequal": { - "version": "4.5.0", - "resolved": "https://registry.npmjs.org/lodash.isequal/-/lodash.isequal-4.5.0.tgz", - "integrity": "sha1-QVxEePK8wwEgwizhDtMib30+GOA=" + "node_modules/json-schema-traverse": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz", + "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==" }, "node_modules/nopt": { "version": "3.0.6", @@ -122,55 +155,45 @@ "integrity": "sha512-sR23YjmuwDSMsQVZDHbV9mPgi0RyniQlqR0AQxTC2/F3cpSjRFMH3CFPjoWvNqhC4OxPkDYNb2l8Mc1Me6D/KQ==", "peer": true }, - "node_modules/swagger-parser": { - "version": "10.0.3", - "resolved": "https://registry.npmjs.org/swagger-parser/-/swagger-parser-10.0.3.tgz", - "integrity": "sha512-nF7oMeL4KypldrQhac8RyHerJeGPD1p2xDh900GPvc+Nk7nWP6jX2FcC7WmkinMoAmoO774+AFXcWsW8gMWEIg==", - "dependencies": { - "@apidevtools/swagger-parser": "10.0.3" - }, + "node_modules/punycode": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/punycode/-/punycode-2.1.1.tgz", + "integrity": "sha512-XRsRjdf+j5ml+y/6GKHPZbrF/8p2Yga0JPtdqTIY2Xe5ohJPD9saDJJLPvp9+NSBprVvevdXZybnj2cv8OEd0A==", "engines": { - "node": ">=10" + "node": ">=6" } }, - "node_modules/validator": { - "version": "13.7.0", - "resolved": "https://registry.npmjs.org/validator/-/validator-13.7.0.tgz", - "integrity": "sha512-nYXQLCBkpJ8X6ltALua9dRrZDHVYxjJ1wgskNt1lH9fzGjs3tgojGSCBjmEPwkWS1y29+DrizMTW19Pr9uB2nw==", + "node_modules/require-from-string": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/require-from-string/-/require-from-string-2.0.2.tgz", + "integrity": "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==", "engines": { - "node": ">= 0.10" + "node": ">=0.10.0" } }, - "node_modules/z-schema": { - "version": "5.0.1", - "resolved": "https://registry.npmjs.org/z-schema/-/z-schema-5.0.1.tgz", - "integrity": "sha512-Gp8xU2lULhREqTWj9t4BEAeA7M835n4fWJ9KjGWksV3wmLUdOJo2hAr+QYvkVZIGOOTyeN274g1f95dKRsgYgQ==", + "node_modules/sprintf-js": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/sprintf-js/-/sprintf-js-1.0.3.tgz", + "integrity": "sha512-D9cPgkvLlV3t3IzL0D0YLvGA9Ahk4PcvVwUbN0dSGr1aP0Nrt4AEnTUbuGvquEC0mA64Gqt1fzirlRs5ibXx8g==" + }, + "node_modules/uri-js": { + "version": "4.4.1", + "resolved": "https://registry.npmjs.org/uri-js/-/uri-js-4.4.1.tgz", + "integrity": "sha512-7rKUyy33Q1yc98pQ1DAmLtwX109F7TIfWlW1Ydo8Wl1ii1SeHieeh0HHfPeL2fMXK6z0s8ecKs9frCuLJvndBg==", "dependencies": { - "lodash.get": "^4.4.2", - "lodash.isequal": "^4.5.0", - "validator": "^13.6.0" - }, - "bin": { - "z-schema": "bin/z-schema" - }, - "engines": { - "node": ">=8.0.0" - }, - "optionalDependencies": { - "commander": "^2.7.1" + "punycode": "^2.1.0" } } }, "dependencies": { "@apidevtools/json-schema-ref-parser": { - "version": "9.0.9", - "resolved": "https://registry.npmjs.org/@apidevtools/json-schema-ref-parser/-/json-schema-ref-parser-9.0.9.tgz", - "integrity": "sha512-GBD2Le9w2+lVFoc4vswGI/TjkNIZSVp7+9xPf+X3uidBfWnAeUWmquteSyt0+VCrhNMWj/FTABISQrD3Z/YA+w==", + "version": "9.0.6", + "resolved": "https://registry.npmjs.org/@apidevtools/json-schema-ref-parser/-/json-schema-ref-parser-9.0.6.tgz", + "integrity": "sha512-M3YgsLjI0lZxvrpeGVk9Ap032W6TPQkH6pRAZz81Ac3WUNF79VQooAFnp8umjvVzUmD93NkogxEwbSce7qMsUg==", "requires": { "@jsdevtools/ono": "^7.1.3", - "@types/json-schema": "^7.0.6", "call-me-maybe": "^1.0.1", - "js-yaml": "^4.1.0" + "js-yaml": "^3.13.1" } }, "@apidevtools/openapi-schemas": { @@ -184,16 +207,17 @@ "integrity": "sha512-QAkD5kK2b1WfjDS/UQn/qQkbwF31uqRjPTrsCs5ZG9BQGAkjwvqGFjjPqAuzac/IYzpPtRzjCP1WrTuAIjMrXg==" }, "@apidevtools/swagger-parser": { - "version": "10.0.3", - "resolved": "https://registry.npmjs.org/@apidevtools/swagger-parser/-/swagger-parser-10.0.3.tgz", - "integrity": "sha512-sNiLY51vZOmSPFZA5TF35KZ2HbgYklQnTSDnkghamzLb3EkNtcQnrBQEj5AOCxHpTtXpqMCRM1CrmV2rG6nw4g==", + "version": "10.1.0", + "resolved": "https://registry.npmjs.org/@apidevtools/swagger-parser/-/swagger-parser-10.1.0.tgz", + "integrity": "sha512-9Kt7EuS/7WbMAUv2gSziqjvxwDbFSg3Xeyfuj5laUODX8o/k/CpsAKiQ8W7/R88eXFTMbJYg6+7uAmOWNKmwnw==", "requires": { - "@apidevtools/json-schema-ref-parser": "^9.0.6", - "@apidevtools/openapi-schemas": "^2.0.4", + "@apidevtools/json-schema-ref-parser": "9.0.6", + "@apidevtools/openapi-schemas": "^2.1.0", "@apidevtools/swagger-methods": "^3.0.2", "@jsdevtools/ono": "^7.1.3", - "call-me-maybe": "^1.0.1", - "z-schema": "^5.0.1" + "ajv": "^8.6.3", + "ajv-draft-04": "^1.0.0", + "call-me-maybe": "^1.0.1" } }, "@jsdevtools/ono": { @@ -201,49 +225,64 @@ "resolved": "https://registry.npmjs.org/@jsdevtools/ono/-/ono-7.1.3.tgz", "integrity": "sha512-4JQNk+3mVzK3xh2rqd6RB4J46qUR19azEHBneZyTZM+c456qOrbbM/5xcR8huNCCcbVt7+UmizG6GuUvPvKUYg==" }, - "@types/json-schema": { - "version": "7.0.9", - "resolved": "https://registry.npmjs.org/@types/json-schema/-/json-schema-7.0.9.tgz", - "integrity": "sha512-qcUXuemtEu+E5wZSJHNxUXeCZhAfXKQ41D+duX+VYPde7xyEVZci+/oXKJL13tnRs9lR2pr4fod59GT6/X1/yQ==" - }, "abbrev": { "version": "1.1.1", "resolved": "https://registry.npmjs.org/abbrev/-/abbrev-1.1.1.tgz", "integrity": "sha512-nne9/IiQ/hzIhY6pdDnbBtz7DjPTKrY00P/zvPSm5pOFkl6xuGrGnXn/VtTNNfNtAfZ9/1RtehkszU9qcTii0Q==" }, + "ajv": { + "version": "8.11.0", + "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.11.0.tgz", + "integrity": "sha512-wGgprdCvMalC0BztXvitD2hC04YffAvtsUn93JbGXYLAtCUO4xd17mCCZQxUOItiBwZvJScWo8NIvQMQ71rdpg==", + "requires": { + "fast-deep-equal": "^3.1.1", + "json-schema-traverse": "^1.0.0", + "require-from-string": "^2.0.2", + "uri-js": "^4.2.2" + } + }, + "ajv-draft-04": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/ajv-draft-04/-/ajv-draft-04-1.0.0.tgz", + "integrity": "sha512-mv00Te6nmYbRp5DCwclxtt7yV/joXJPGS7nM+97GdxvuttCOfgI3K4U25zboyeX0O+myI8ERluxQe5wljMmVIw==", + "requires": {} + }, "argparse": { - "version": "2.0.1", - "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz", - "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==" + "version": "1.0.10", + "resolved": "https://registry.npmjs.org/argparse/-/argparse-1.0.10.tgz", + "integrity": "sha512-o5Roy6tNG4SL/FOkCAN6RzjiakZS25RLYFrcMttJqbdd8BWrnA+fGz57iN5Pb06pvBGvl5gQ0B48dJlslXvoTg==", + "requires": { + "sprintf-js": "~1.0.2" + } }, "call-me-maybe": { "version": "1.0.1", "resolved": "https://registry.npmjs.org/call-me-maybe/-/call-me-maybe-1.0.1.tgz", - "integrity": "sha1-JtII6onje1y95gJQoV8DHBak1ms=" + "integrity": "sha512-wCyFsDQkKPwwF8BDwOiWNx/9K45L/hvggQiDbve+viMNMQnWhrlYIuBk09offfwCRtCO9P6XwUttufzU11WCVw==" }, - "commander": { - "version": "2.20.3", - "resolved": "https://registry.npmjs.org/commander/-/commander-2.20.3.tgz", - "integrity": "sha512-GpVkmM8vF2vQUkj2LvZmD35JxeJOLCwJ9cUkugyk2nuhbv3+mJvpLYYt+0+USMxE+oj+ey/lJEnhZw75x/OMcQ==", - "optional": true + "esprima": { + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/esprima/-/esprima-4.0.1.tgz", + "integrity": "sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A==" + }, + "fast-deep-equal": { + "version": "3.1.3", + "resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz", + "integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==" }, "js-yaml": { - "version": "4.1.0", - "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.0.tgz", - "integrity": "sha512-wpxZs9NoxZaJESJGIZTyDEaYpl0FKSA+FB9aJiyemKhMwkxQg63h4T1KJgUGHpTqPDNRcmmYLugrRjJlBtWvRA==", + "version": "3.14.1", + "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-3.14.1.tgz", + "integrity": "sha512-okMH7OXXJ7YrN9Ok3/SXrnu4iX9yOk+25nqX4imS2npuvTYDmo/QEZoqwZkYaIDk3jVvBOTOIEgEhaLOynBS9g==", "requires": { - "argparse": "^2.0.1" + "argparse": "^1.0.7", + "esprima": "^4.0.0" } }, - "lodash.get": { - "version": "4.4.2", - "resolved": "https://registry.npmjs.org/lodash.get/-/lodash.get-4.4.2.tgz", - "integrity": "sha1-LRd/ZS+jHpObRDjVNBSZ36OCXpk=" - }, - "lodash.isequal": { - "version": "4.5.0", - "resolved": "https://registry.npmjs.org/lodash.isequal/-/lodash.isequal-4.5.0.tgz", - "integrity": "sha1-QVxEePK8wwEgwizhDtMib30+GOA=" + "json-schema-traverse": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz", + "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==" }, "nopt": { "version": "3.0.6", @@ -259,28 +298,27 @@ "integrity": "sha512-sR23YjmuwDSMsQVZDHbV9mPgi0RyniQlqR0AQxTC2/F3cpSjRFMH3CFPjoWvNqhC4OxPkDYNb2l8Mc1Me6D/KQ==", "peer": true }, - "swagger-parser": { - "version": "10.0.3", - "resolved": "https://registry.npmjs.org/swagger-parser/-/swagger-parser-10.0.3.tgz", - "integrity": "sha512-nF7oMeL4KypldrQhac8RyHerJeGPD1p2xDh900GPvc+Nk7nWP6jX2FcC7WmkinMoAmoO774+AFXcWsW8gMWEIg==", - "requires": { - "@apidevtools/swagger-parser": "10.0.3" - } + "punycode": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/punycode/-/punycode-2.1.1.tgz", + "integrity": "sha512-XRsRjdf+j5ml+y/6GKHPZbrF/8p2Yga0JPtdqTIY2Xe5ohJPD9saDJJLPvp9+NSBprVvevdXZybnj2cv8OEd0A==" }, - "validator": { - "version": "13.7.0", - "resolved": "https://registry.npmjs.org/validator/-/validator-13.7.0.tgz", - "integrity": "sha512-nYXQLCBkpJ8X6ltALua9dRrZDHVYxjJ1wgskNt1lH9fzGjs3tgojGSCBjmEPwkWS1y29+DrizMTW19Pr9uB2nw==" + "require-from-string": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/require-from-string/-/require-from-string-2.0.2.tgz", + "integrity": "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==" }, - "z-schema": { - "version": "5.0.1", - "resolved": "https://registry.npmjs.org/z-schema/-/z-schema-5.0.1.tgz", - "integrity": "sha512-Gp8xU2lULhREqTWj9t4BEAeA7M835n4fWJ9KjGWksV3wmLUdOJo2hAr+QYvkVZIGOOTyeN274g1f95dKRsgYgQ==", + "sprintf-js": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/sprintf-js/-/sprintf-js-1.0.3.tgz", + "integrity": "sha512-D9cPgkvLlV3t3IzL0D0YLvGA9Ahk4PcvVwUbN0dSGr1aP0Nrt4AEnTUbuGvquEC0mA64Gqt1fzirlRs5ibXx8g==" + }, + "uri-js": { + "version": "4.4.1", + "resolved": "https://registry.npmjs.org/uri-js/-/uri-js-4.4.1.tgz", + "integrity": "sha512-7rKUyy33Q1yc98pQ1DAmLtwX109F7TIfWlW1Ydo8Wl1ii1SeHieeh0HHfPeL2fMXK6z0s8ecKs9frCuLJvndBg==", "requires": { - "commander": "^2.7.1", - "lodash.get": "^4.4.2", - "lodash.isequal": "^4.5.0", - "validator": "^13.6.0" + "punycode": "^2.1.0" } } } diff --git a/scripts/package.json b/scripts/package.json index d4342c56..011a6e10 100644 --- a/scripts/package.json +++ b/scripts/package.json @@ -9,7 +9,7 @@ "author": "", "license": "ISC", "dependencies": { - "nopt": "^3.0.2", - "swagger-parser": "^10.0.3" + "@apidevtools/swagger-parser": "^10.1.0", + "nopt": "^3.0.2" } } diff --git a/scripts/validator.js b/scripts/validator.js index c20dd993..f3b86158 100644 --- a/scripts/validator.js +++ b/scripts/validator.js @@ -1,7 +1,7 @@ "use strict"; var fs = require("fs"); var nopt = require("nopt"); -var parser = require("swagger-parser"); +var parser = require("@apidevtools/swagger-parser"); var path = require("path"); var opts = nopt({ @@ -14,8 +14,8 @@ var opts = nopt({ if (opts.help) { console.log( - "Use swagger-parser to validate against Swagger 2.0\n"+ - "Usage:\n"+ + "Use swagger-parser to validate against OpenAPI 3.1.0\n" + + "Usage:\n" + " node validator.js -s " ); process.exit(0); @@ -26,7 +26,7 @@ if (!opts.schema) { } -var errFn = function(err, api) { +var errFn = function (err, api) { if (!err) { return; } @@ -45,7 +45,7 @@ var errFn = function(err, api) { function makeHandler(scope) { if (!scope) scope = "Schema"; - return function(err, api, metadata) { + return function (err, api, metadata) { if (err) { console.error("%s is not valid.", scope || "Schema"); errFn(err, api, metadata); // Won't return @@ -68,11 +68,11 @@ function makeHandler(scope) { var isDir = fs.lstatSync(opts.schema).isDirectory(); if (isDir) { console.log("Checking directory %s for .yaml files...", opts.schema); - fs.readdir(opts.schema, function(err, files) { + fs.readdir(opts.schema, function (err, files) { if (err) { errFn(err); // Won't return } - files.forEach(function(f) { + files.forEach(function (f) { var suffix = ".yaml"; if (f.indexOf(suffix, f.length - suffix.length) > 0) { parser.validate(path.join(opts.schema, f), makeHandler(f)); @@ -80,7 +80,7 @@ if (isDir) { }); }); } -else{ +else { parser.validate(opts.schema, makeHandler(opts.schema)); } From f4aa7c0327ea61aa11bef9e14a163404143dcc57 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Wed, 7 Jun 2023 20:36:47 +0200 Subject: [PATCH 34/59] Bump the version of jsonschema (#1556) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Bump the version of jsonschema OpenAPI 3.1 uses JSON Schema Draft 2020-12 so we need a version that supports it. Signed-off-by: Kévin Commaille * Add changelog Signed-off-by: Kévin Commaille * Fix PR number Signed-off-by: Kévin Commaille --------- Signed-off-by: Kévin Commaille --- changelogs/internal/newsfragments/1556.clarification | 1 + scripts/check-event-schema-examples.py | 2 +- scripts/requirements.txt | 5 ++--- 3 files changed, 4 insertions(+), 4 deletions(-) create mode 100644 changelogs/internal/newsfragments/1556.clarification diff --git a/changelogs/internal/newsfragments/1556.clarification b/changelogs/internal/newsfragments/1556.clarification new file mode 100644 index 00000000..05c5897e --- /dev/null +++ b/changelogs/internal/newsfragments/1556.clarification @@ -0,0 +1 @@ +Bump jsonschema to validate JSON Schemas against Draft 2020-12. diff --git a/scripts/check-event-schema-examples.py b/scripts/check-event-schema-examples.py index e5261c87..c6191321 100755 --- a/scripts/check-event-schema-examples.py +++ b/scripts/check-event-schema-examples.py @@ -88,7 +88,7 @@ def check_example_file(examplepath, schemapath): fileurl = "file://" + os.path.abspath(schemapath) schema["id"] = fileurl - resolver = jsonschema.RefResolver(schemapath, schema, handlers={"file": load_file}) + resolver = jsonschema.RefResolver(fileurl, schema, handlers={"file": load_file}) print ("Checking schema for: %r %r" % (examplepath, schemapath)) try: diff --git a/scripts/requirements.txt b/scripts/requirements.txt index 9d9f1167..a3ff4f0b 100644 --- a/scripts/requirements.txt +++ b/scripts/requirements.txt @@ -1,9 +1,8 @@ # no doubt older versions would be fine for many of these but these were # current at the time of writing -# jsonschema 3.0.0 objects to the $refs in our schema file. TODO: figure out -# why. -jsonschema >= 2.6.0, < 3.0.0 +# we need at least version 4.0.0 for support of JSON Schema Draft 2020-12. +jsonschema >= 4.0.0 PyYAML >= 3.12 requests >= 2.18.4 From 3c5355a278baec46a47f8240708421d1faff0fe7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Fri, 9 Jun 2023 20:55:12 +0200 Subject: [PATCH 35/59] Use Redocly CLI to validate OpenAPI definitions (#1558) --- .github/workflows/main.yml | 9 +- .../internal/newsfragments/1558.clarification | 1 + redocly.yaml | 10 + scripts/package-lock.json | 325 ------------------ scripts/package.json | 15 - scripts/validator.js | 86 ----- 6 files changed, 12 insertions(+), 434 deletions(-) create mode 100644 changelogs/internal/newsfragments/1558.clarification create mode 100644 redocly.yaml delete mode 100644 scripts/package-lock.json delete mode 100644 scripts/package.json delete mode 100644 scripts/validator.js diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 2227a119..aa5d701f 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -23,16 +23,9 @@ jobs: uses: actions/setup-node@v2 with: node-version: '14' - - name: "⚙️ npm" - working-directory: "./scripts" - run: | - npm install - name: "🔎 Run validator" - working-directory: "./scripts" run: | - node validator.js -s "../data/api/application-service" - node validator.js -s "../data/api/client-server" - node validator.js -s "../data/api/push-gateway" + npx @redocly/cli@latest lint data/api/*/*.yaml check-examples: name: "🔎 Check Event schema examples" diff --git a/changelogs/internal/newsfragments/1558.clarification b/changelogs/internal/newsfragments/1558.clarification new file mode 100644 index 00000000..29e1c1d0 --- /dev/null +++ b/changelogs/internal/newsfragments/1558.clarification @@ -0,0 +1 @@ +Use Redocly CLI to validate OpenAPI definitions. diff --git a/redocly.yaml b/redocly.yaml new file mode 100644 index 00000000..263f0bca --- /dev/null +++ b/redocly.yaml @@ -0,0 +1,10 @@ +# See https://redocly.com/docs/cli/configuration/ for more information. +extends: + - minimal +rules: + info-license: off + security-defined: off + operation-4xx-response: off + no-invalid-media-type-examples: off + no-path-trailing-slash: off + operation-2xx-response: off \ No newline at end of file diff --git a/scripts/package-lock.json b/scripts/package-lock.json deleted file mode 100644 index 6b6e5328..00000000 --- a/scripts/package-lock.json +++ /dev/null @@ -1,325 +0,0 @@ -{ - "name": "swagger-cli-validator", - "version": "0.0.1", - "lockfileVersion": 2, - "requires": true, - "packages": { - "": { - "name": "swagger-cli-validator", - "version": "0.0.1", - "license": "ISC", - "dependencies": { - "@apidevtools/swagger-parser": "^10.1.0", - "nopt": "^3.0.2" - } - }, - "node_modules/@apidevtools/json-schema-ref-parser": { - "version": "9.0.6", - "resolved": "https://registry.npmjs.org/@apidevtools/json-schema-ref-parser/-/json-schema-ref-parser-9.0.6.tgz", - "integrity": "sha512-M3YgsLjI0lZxvrpeGVk9Ap032W6TPQkH6pRAZz81Ac3WUNF79VQooAFnp8umjvVzUmD93NkogxEwbSce7qMsUg==", - "dependencies": { - "@jsdevtools/ono": "^7.1.3", - "call-me-maybe": "^1.0.1", - "js-yaml": "^3.13.1" - } - }, - "node_modules/@apidevtools/openapi-schemas": { - "version": "2.1.0", - "resolved": "https://registry.npmjs.org/@apidevtools/openapi-schemas/-/openapi-schemas-2.1.0.tgz", - "integrity": "sha512-Zc1AlqrJlX3SlpupFGpiLi2EbteyP7fXmUOGup6/DnkRgjP9bgMM/ag+n91rsv0U1Gpz0H3VILA/o3bW7Ua6BQ==", - "engines": { - "node": ">=10" - } - }, - "node_modules/@apidevtools/swagger-methods": { - "version": "3.0.2", - "resolved": "https://registry.npmjs.org/@apidevtools/swagger-methods/-/swagger-methods-3.0.2.tgz", - "integrity": "sha512-QAkD5kK2b1WfjDS/UQn/qQkbwF31uqRjPTrsCs5ZG9BQGAkjwvqGFjjPqAuzac/IYzpPtRzjCP1WrTuAIjMrXg==" - }, - "node_modules/@apidevtools/swagger-parser": { - "version": "10.1.0", - "resolved": "https://registry.npmjs.org/@apidevtools/swagger-parser/-/swagger-parser-10.1.0.tgz", - "integrity": "sha512-9Kt7EuS/7WbMAUv2gSziqjvxwDbFSg3Xeyfuj5laUODX8o/k/CpsAKiQ8W7/R88eXFTMbJYg6+7uAmOWNKmwnw==", - "dependencies": { - "@apidevtools/json-schema-ref-parser": "9.0.6", - "@apidevtools/openapi-schemas": "^2.1.0", - "@apidevtools/swagger-methods": "^3.0.2", - "@jsdevtools/ono": "^7.1.3", - "ajv": "^8.6.3", - "ajv-draft-04": "^1.0.0", - "call-me-maybe": "^1.0.1" - }, - "peerDependencies": { - "openapi-types": ">=7" - } - }, - "node_modules/@jsdevtools/ono": { - "version": "7.1.3", - "resolved": "https://registry.npmjs.org/@jsdevtools/ono/-/ono-7.1.3.tgz", - "integrity": "sha512-4JQNk+3mVzK3xh2rqd6RB4J46qUR19azEHBneZyTZM+c456qOrbbM/5xcR8huNCCcbVt7+UmizG6GuUvPvKUYg==" - }, - "node_modules/abbrev": { - "version": "1.1.1", - "resolved": "https://registry.npmjs.org/abbrev/-/abbrev-1.1.1.tgz", - "integrity": "sha512-nne9/IiQ/hzIhY6pdDnbBtz7DjPTKrY00P/zvPSm5pOFkl6xuGrGnXn/VtTNNfNtAfZ9/1RtehkszU9qcTii0Q==" - }, - "node_modules/ajv": { - "version": "8.11.0", - "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.11.0.tgz", - "integrity": "sha512-wGgprdCvMalC0BztXvitD2hC04YffAvtsUn93JbGXYLAtCUO4xd17mCCZQxUOItiBwZvJScWo8NIvQMQ71rdpg==", - "dependencies": { - "fast-deep-equal": "^3.1.1", - "json-schema-traverse": "^1.0.0", - "require-from-string": "^2.0.2", - "uri-js": "^4.2.2" - }, - "funding": { - "type": "github", - "url": "https://github.com/sponsors/epoberezkin" - } - }, - "node_modules/ajv-draft-04": { - "version": "1.0.0", - "resolved": "https://registry.npmjs.org/ajv-draft-04/-/ajv-draft-04-1.0.0.tgz", - "integrity": "sha512-mv00Te6nmYbRp5DCwclxtt7yV/joXJPGS7nM+97GdxvuttCOfgI3K4U25zboyeX0O+myI8ERluxQe5wljMmVIw==", - "peerDependencies": { - "ajv": "^8.5.0" - }, - "peerDependenciesMeta": { - "ajv": { - "optional": true - } - } - }, - "node_modules/argparse": { - "version": "1.0.10", - "resolved": "https://registry.npmjs.org/argparse/-/argparse-1.0.10.tgz", - "integrity": "sha512-o5Roy6tNG4SL/FOkCAN6RzjiakZS25RLYFrcMttJqbdd8BWrnA+fGz57iN5Pb06pvBGvl5gQ0B48dJlslXvoTg==", - "dependencies": { - "sprintf-js": "~1.0.2" - } - }, - "node_modules/call-me-maybe": { - "version": "1.0.1", - "resolved": "https://registry.npmjs.org/call-me-maybe/-/call-me-maybe-1.0.1.tgz", - "integrity": "sha512-wCyFsDQkKPwwF8BDwOiWNx/9K45L/hvggQiDbve+viMNMQnWhrlYIuBk09offfwCRtCO9P6XwUttufzU11WCVw==" - }, - "node_modules/esprima": { - "version": "4.0.1", - "resolved": "https://registry.npmjs.org/esprima/-/esprima-4.0.1.tgz", - "integrity": "sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A==", - "bin": { - "esparse": "bin/esparse.js", - "esvalidate": "bin/esvalidate.js" - }, - "engines": { - "node": ">=4" - } - }, - "node_modules/fast-deep-equal": { - "version": "3.1.3", - "resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz", - "integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==" - }, - "node_modules/js-yaml": { - "version": "3.14.1", - "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-3.14.1.tgz", - "integrity": "sha512-okMH7OXXJ7YrN9Ok3/SXrnu4iX9yOk+25nqX4imS2npuvTYDmo/QEZoqwZkYaIDk3jVvBOTOIEgEhaLOynBS9g==", - "dependencies": { - "argparse": "^1.0.7", - "esprima": "^4.0.0" - }, - "bin": { - "js-yaml": "bin/js-yaml.js" - } - }, - "node_modules/json-schema-traverse": { - "version": "1.0.0", - "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz", - "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==" - }, - "node_modules/nopt": { - "version": "3.0.6", - "resolved": "https://registry.npmjs.org/nopt/-/nopt-3.0.6.tgz", - "integrity": "sha1-xkZdvwirzU2zWTF/eaxopkayj/k=", - "dependencies": { - "abbrev": "1" - }, - "bin": { - "nopt": "bin/nopt.js" - } - }, - "node_modules/openapi-types": { - "version": "9.3.0", - "resolved": "https://registry.npmjs.org/openapi-types/-/openapi-types-9.3.0.tgz", - "integrity": "sha512-sR23YjmuwDSMsQVZDHbV9mPgi0RyniQlqR0AQxTC2/F3cpSjRFMH3CFPjoWvNqhC4OxPkDYNb2l8Mc1Me6D/KQ==", - "peer": true - }, - "node_modules/punycode": { - "version": "2.1.1", - "resolved": "https://registry.npmjs.org/punycode/-/punycode-2.1.1.tgz", - "integrity": "sha512-XRsRjdf+j5ml+y/6GKHPZbrF/8p2Yga0JPtdqTIY2Xe5ohJPD9saDJJLPvp9+NSBprVvevdXZybnj2cv8OEd0A==", - "engines": { - "node": ">=6" - } - }, - "node_modules/require-from-string": { - "version": "2.0.2", - "resolved": "https://registry.npmjs.org/require-from-string/-/require-from-string-2.0.2.tgz", - "integrity": "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==", - "engines": { - "node": ">=0.10.0" - } - }, - "node_modules/sprintf-js": { - "version": "1.0.3", - "resolved": "https://registry.npmjs.org/sprintf-js/-/sprintf-js-1.0.3.tgz", - "integrity": "sha512-D9cPgkvLlV3t3IzL0D0YLvGA9Ahk4PcvVwUbN0dSGr1aP0Nrt4AEnTUbuGvquEC0mA64Gqt1fzirlRs5ibXx8g==" - }, - "node_modules/uri-js": { - "version": "4.4.1", - "resolved": "https://registry.npmjs.org/uri-js/-/uri-js-4.4.1.tgz", - "integrity": "sha512-7rKUyy33Q1yc98pQ1DAmLtwX109F7TIfWlW1Ydo8Wl1ii1SeHieeh0HHfPeL2fMXK6z0s8ecKs9frCuLJvndBg==", - "dependencies": { - "punycode": "^2.1.0" - } - } - }, - "dependencies": { - "@apidevtools/json-schema-ref-parser": { - "version": "9.0.6", - "resolved": "https://registry.npmjs.org/@apidevtools/json-schema-ref-parser/-/json-schema-ref-parser-9.0.6.tgz", - "integrity": "sha512-M3YgsLjI0lZxvrpeGVk9Ap032W6TPQkH6pRAZz81Ac3WUNF79VQooAFnp8umjvVzUmD93NkogxEwbSce7qMsUg==", - "requires": { - "@jsdevtools/ono": "^7.1.3", - "call-me-maybe": "^1.0.1", - "js-yaml": "^3.13.1" - } - }, - "@apidevtools/openapi-schemas": { - "version": "2.1.0", - "resolved": "https://registry.npmjs.org/@apidevtools/openapi-schemas/-/openapi-schemas-2.1.0.tgz", - "integrity": "sha512-Zc1AlqrJlX3SlpupFGpiLi2EbteyP7fXmUOGup6/DnkRgjP9bgMM/ag+n91rsv0U1Gpz0H3VILA/o3bW7Ua6BQ==" - }, - "@apidevtools/swagger-methods": { - "version": "3.0.2", - "resolved": "https://registry.npmjs.org/@apidevtools/swagger-methods/-/swagger-methods-3.0.2.tgz", - "integrity": "sha512-QAkD5kK2b1WfjDS/UQn/qQkbwF31uqRjPTrsCs5ZG9BQGAkjwvqGFjjPqAuzac/IYzpPtRzjCP1WrTuAIjMrXg==" - }, - "@apidevtools/swagger-parser": { - "version": "10.1.0", - "resolved": "https://registry.npmjs.org/@apidevtools/swagger-parser/-/swagger-parser-10.1.0.tgz", - "integrity": "sha512-9Kt7EuS/7WbMAUv2gSziqjvxwDbFSg3Xeyfuj5laUODX8o/k/CpsAKiQ8W7/R88eXFTMbJYg6+7uAmOWNKmwnw==", - "requires": { - "@apidevtools/json-schema-ref-parser": "9.0.6", - "@apidevtools/openapi-schemas": "^2.1.0", - "@apidevtools/swagger-methods": "^3.0.2", - "@jsdevtools/ono": "^7.1.3", - "ajv": "^8.6.3", - "ajv-draft-04": "^1.0.0", - "call-me-maybe": "^1.0.1" - } - }, - "@jsdevtools/ono": { - "version": "7.1.3", - "resolved": "https://registry.npmjs.org/@jsdevtools/ono/-/ono-7.1.3.tgz", - "integrity": "sha512-4JQNk+3mVzK3xh2rqd6RB4J46qUR19azEHBneZyTZM+c456qOrbbM/5xcR8huNCCcbVt7+UmizG6GuUvPvKUYg==" - }, - "abbrev": { - "version": "1.1.1", - "resolved": "https://registry.npmjs.org/abbrev/-/abbrev-1.1.1.tgz", - "integrity": "sha512-nne9/IiQ/hzIhY6pdDnbBtz7DjPTKrY00P/zvPSm5pOFkl6xuGrGnXn/VtTNNfNtAfZ9/1RtehkszU9qcTii0Q==" - }, - "ajv": { - "version": "8.11.0", - "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.11.0.tgz", - "integrity": "sha512-wGgprdCvMalC0BztXvitD2hC04YffAvtsUn93JbGXYLAtCUO4xd17mCCZQxUOItiBwZvJScWo8NIvQMQ71rdpg==", - "requires": { - "fast-deep-equal": "^3.1.1", - "json-schema-traverse": "^1.0.0", - "require-from-string": "^2.0.2", - "uri-js": "^4.2.2" - } - }, - "ajv-draft-04": { - "version": "1.0.0", - "resolved": "https://registry.npmjs.org/ajv-draft-04/-/ajv-draft-04-1.0.0.tgz", - "integrity": "sha512-mv00Te6nmYbRp5DCwclxtt7yV/joXJPGS7nM+97GdxvuttCOfgI3K4U25zboyeX0O+myI8ERluxQe5wljMmVIw==", - "requires": {} - }, - "argparse": { - "version": "1.0.10", - "resolved": "https://registry.npmjs.org/argparse/-/argparse-1.0.10.tgz", - "integrity": "sha512-o5Roy6tNG4SL/FOkCAN6RzjiakZS25RLYFrcMttJqbdd8BWrnA+fGz57iN5Pb06pvBGvl5gQ0B48dJlslXvoTg==", - "requires": { - "sprintf-js": "~1.0.2" - } - }, - "call-me-maybe": { - "version": "1.0.1", - "resolved": "https://registry.npmjs.org/call-me-maybe/-/call-me-maybe-1.0.1.tgz", - "integrity": "sha512-wCyFsDQkKPwwF8BDwOiWNx/9K45L/hvggQiDbve+viMNMQnWhrlYIuBk09offfwCRtCO9P6XwUttufzU11WCVw==" - }, - "esprima": { - "version": "4.0.1", - "resolved": "https://registry.npmjs.org/esprima/-/esprima-4.0.1.tgz", - "integrity": "sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A==" - }, - "fast-deep-equal": { - "version": "3.1.3", - "resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz", - "integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==" - }, - "js-yaml": { - "version": "3.14.1", - "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-3.14.1.tgz", - "integrity": "sha512-okMH7OXXJ7YrN9Ok3/SXrnu4iX9yOk+25nqX4imS2npuvTYDmo/QEZoqwZkYaIDk3jVvBOTOIEgEhaLOynBS9g==", - "requires": { - "argparse": "^1.0.7", - "esprima": "^4.0.0" - } - }, - "json-schema-traverse": { - "version": "1.0.0", - "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz", - "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==" - }, - "nopt": { - "version": "3.0.6", - "resolved": "https://registry.npmjs.org/nopt/-/nopt-3.0.6.tgz", - "integrity": "sha1-xkZdvwirzU2zWTF/eaxopkayj/k=", - "requires": { - "abbrev": "1" - } - }, - "openapi-types": { - "version": "9.3.0", - "resolved": "https://registry.npmjs.org/openapi-types/-/openapi-types-9.3.0.tgz", - "integrity": "sha512-sR23YjmuwDSMsQVZDHbV9mPgi0RyniQlqR0AQxTC2/F3cpSjRFMH3CFPjoWvNqhC4OxPkDYNb2l8Mc1Me6D/KQ==", - "peer": true - }, - "punycode": { - "version": "2.1.1", - "resolved": "https://registry.npmjs.org/punycode/-/punycode-2.1.1.tgz", - "integrity": "sha512-XRsRjdf+j5ml+y/6GKHPZbrF/8p2Yga0JPtdqTIY2Xe5ohJPD9saDJJLPvp9+NSBprVvevdXZybnj2cv8OEd0A==" - }, - "require-from-string": { - "version": "2.0.2", - "resolved": "https://registry.npmjs.org/require-from-string/-/require-from-string-2.0.2.tgz", - "integrity": "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==" - }, - "sprintf-js": { - "version": "1.0.3", - "resolved": "https://registry.npmjs.org/sprintf-js/-/sprintf-js-1.0.3.tgz", - "integrity": "sha512-D9cPgkvLlV3t3IzL0D0YLvGA9Ahk4PcvVwUbN0dSGr1aP0Nrt4AEnTUbuGvquEC0mA64Gqt1fzirlRs5ibXx8g==" - }, - "uri-js": { - "version": "4.4.1", - "resolved": "https://registry.npmjs.org/uri-js/-/uri-js-4.4.1.tgz", - "integrity": "sha512-7rKUyy33Q1yc98pQ1DAmLtwX109F7TIfWlW1Ydo8Wl1ii1SeHieeh0HHfPeL2fMXK6z0s8ecKs9frCuLJvndBg==", - "requires": { - "punycode": "^2.1.0" - } - } - } -} diff --git a/scripts/package.json b/scripts/package.json deleted file mode 100644 index 011a6e10..00000000 --- a/scripts/package.json +++ /dev/null @@ -1,15 +0,0 @@ -{ - "name": "swagger-cli-validator", - "version": "0.0.1", - "description": "", - "main": "validator.js", - "scripts": { - "test": "echo \"Error: no test specified\" && exit 1" - }, - "author": "", - "license": "ISC", - "dependencies": { - "@apidevtools/swagger-parser": "^10.1.0", - "nopt": "^3.0.2" - } -} diff --git a/scripts/validator.js b/scripts/validator.js deleted file mode 100644 index f3b86158..00000000 --- a/scripts/validator.js +++ /dev/null @@ -1,86 +0,0 @@ -"use strict"; -var fs = require("fs"); -var nopt = require("nopt"); -var parser = require("@apidevtools/swagger-parser"); -var path = require("path"); - -var opts = nopt({ - "help": Boolean, - "schema": path -}, { - "h": "--help", - "s": "--schema" -}); - -if (opts.help) { - console.log( - "Use swagger-parser to validate against OpenAPI 3.1.0\n" + - "Usage:\n" + - " node validator.js -s " - ); - process.exit(0); -} -if (!opts.schema) { - console.error("No [s]chema specified."); - process.exit(1); -} - - -var errFn = function (err, api) { - if (!err) { - return; - } - console.error(err); - process.exit(1); -}; - -/** - * @brief Produce a handler for parser.validate(). - * Recommended usage: `parser.validate(filename, makeHandler(filename));` - * or `parser.validate(schema, makeHandler());`. - * @param scope - usually a filename, this will be used to denote - * an (in)valid schema in console output; "Schema" if undefined - * @returns {function} the handler that can be passed to parser.validate - */ -function makeHandler(scope) { - if (!scope) - scope = "Schema"; - return function (err, api, metadata) { - if (err) { - console.error("%s is not valid.", scope || "Schema"); - errFn(err, api, metadata); // Won't return - } - - Object.keys(api.paths).forEach(function (endpoint) { - var operationsMap = api.paths[endpoint]; - Object.keys(operationsMap).forEach(function (verb) { - if (!operationsMap[verb]["operationId"]) { - console.error("%s is not valid", scope); - errFn("operationId is missing in " + endpoint + ", verb " + verb, api); - } - }) - }); - - console.log("%s is valid.", scope); - } -} - -var isDir = fs.lstatSync(opts.schema).isDirectory(); -if (isDir) { - console.log("Checking directory %s for .yaml files...", opts.schema); - fs.readdir(opts.schema, function (err, files) { - if (err) { - errFn(err); // Won't return - } - files.forEach(function (f) { - var suffix = ".yaml"; - if (f.indexOf(suffix, f.length - suffix.length) > 0) { - parser.validate(path.join(opts.schema, f), makeHandler(f)); - } - }); - }); -} -else { - parser.validate(opts.schema, makeHandler(opts.schema)); -} - From 7a142936f55791ef67ede727d450d77737f485a7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Fri, 9 Jun 2023 21:57:28 +0200 Subject: [PATCH 36/59] Fix level of examples in server keys definition (#1560) --- .../newsfragments/1560.clarification | 1 + data/api/server-server/definitions/keys.yaml | 22 +++++++++---------- 2 files changed, 12 insertions(+), 11 deletions(-) create mode 100644 changelogs/server_server/newsfragments/1560.clarification diff --git a/changelogs/server_server/newsfragments/1560.clarification b/changelogs/server_server/newsfragments/1560.clarification new file mode 100644 index 00000000..e717dda4 --- /dev/null +++ b/changelogs/server_server/newsfragments/1560.clarification @@ -0,0 +1 @@ +Fix level of examples in server keys definition. diff --git a/data/api/server-server/definitions/keys.yaml b/data/api/server-server/definitions/keys.yaml index 97ac1667..efb76f26 100644 --- a/data/api/server-server/definitions/keys.yaml +++ b/data/api/server-server/definitions/keys.yaml @@ -33,17 +33,17 @@ properties: additionalProperties: type: object title: Verify Key - example: { - "ed25519:abc123": { - "key": "VGhpcyBzaG91bGQgYmUgYSByZWFsIGVkMjU1MTkgcGF5bG9hZA" - } - } properties: key: type: string description: The [Unpadded base64](/appendices/#unpadded-base64) encoded key. example: "VGhpcyBzaG91bGQgYmUgYSByZWFsIGVkMjU1MTkgcGF5bG9hZA" required: ["key"] + example: { + "ed25519:abc123": { + "key": "VGhpcyBzaG91bGQgYmUgYSByZWFsIGVkMjU1MTkgcGF5bG9hZA" + } + } old_verify_keys: type: object description: |- @@ -56,12 +56,6 @@ properties: additionalProperties: type: object title: Old Verify Key - example: { - "ed25519:0ldK3y": { - "expired_ts": 1532645052628, - "key": "VGhpcyBzaG91bGQgYmUgeW91ciBvbGQga2V5J3MgZWQyNTUxOSBwYXlsb2FkLg" - } - } properties: expired_ts: type: integer @@ -73,6 +67,12 @@ properties: description: The [Unpadded base64](/appendices/#unpadded-base64) encoded key. example: "VGhpcyBzaG91bGQgYmUgeW91ciBvbGQga2V5J3MgZWQyNTUxOSBwYXlsb2FkLg" required: ["expired_ts", "key"] + example: { + "ed25519:0ldK3y": { + "expired_ts": 1532645052628, + "key": "VGhpcyBzaG91bGQgYmUgeW91ciBvbGQga2V5J3MgZWQyNTUxOSBwYXlsb2FkLg" + } + } signatures: type: object description: |- From adff3faa353b86bf45122d87176b5891d9761d52 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Sat, 10 Jun 2023 13:44:06 +0200 Subject: [PATCH 37/59] Make sure version in x-changedInMatrixVersion is a string (#1562) --- changelogs/internal/newsfragments/1562.clarification | 1 + .../definitions/client_event_without_room_id.yaml | 2 +- data/event-schemas/schema/m.call.hangup.yaml | 2 +- data/event-schemas/schema/m.receipt.yaml | 2 +- data/event-schemas/schema/m.room.encrypted.yaml | 4 ++-- data/event-schemas/schema/m.room_key_request.yaml | 2 +- 6 files changed, 7 insertions(+), 6 deletions(-) create mode 100644 changelogs/internal/newsfragments/1562.clarification diff --git a/changelogs/internal/newsfragments/1562.clarification b/changelogs/internal/newsfragments/1562.clarification new file mode 100644 index 00000000..6882cad1 --- /dev/null +++ b/changelogs/internal/newsfragments/1562.clarification @@ -0,0 +1 @@ +Make sure version in x-changedInMatrixVersion is a string. diff --git a/data/api/client-server/definitions/client_event_without_room_id.yaml b/data/api/client-server/definitions/client_event_without_room_id.yaml index 0decb6f3..d78dcc68 100644 --- a/data/api/client-server/definitions/client_event_without_room_id.yaml +++ b/data/api/client-server/definitions/client_event_without_room_id.yaml @@ -104,7 +104,7 @@ properties: by the local homeserver, and is only returned if the event is a state event, and the client has permission to see the previous content. x-changedInMatrixVersion: - 1.2: | + "1.2": | Previously, this field was specified at the top level of returned events rather than in `unsigned` (with the exception of the [`GET .../notifications`](/client-server-api/#get_matrixclientv3notifications) diff --git a/data/event-schemas/schema/m.call.hangup.yaml b/data/event-schemas/schema/m.call.hangup.yaml index 65d697ab..0ca7fb65 100644 --- a/data/event-schemas/schema/m.call.hangup.yaml +++ b/data/event-schemas/schema/m.call.hangup.yaml @@ -35,7 +35,7 @@ properties: previous previous versions of the spec, so a missing value should be treated as `user_hangup`. x-changedInMatrixVersion: - 1.7: |- + "1.7": |- Additional values were added. enum: - ice_timeout diff --git a/data/event-schemas/schema/m.receipt.yaml b/data/event-schemas/schema/m.receipt.yaml index c501d022..6062d31f 100644 --- a/data/event-schemas/schema/m.receipt.yaml +++ b/data/event-schemas/schema/m.receipt.yaml @@ -2,7 +2,7 @@ type: object title: Receipt Event description: Informs the client of new receipts. x-changedInMatrixVersion: - 1.4: | + "1.4": | Added `m.read.private` receipts to the event's `content`. allOf: - $ref: "core-event-schema/event.yaml" diff --git a/data/event-schemas/schema/m.room.encrypted.yaml b/data/event-schemas/schema/m.room.encrypted.yaml index 84461013..95e05ff7 100644 --- a/data/event-schemas/schema/m.room.encrypted.yaml +++ b/data/event-schemas/schema/m.room.encrypted.yaml @@ -42,7 +42,7 @@ properties: sender_key: type: string x-changedInMatrixVersion: - 1.3: |- + "1.3": |- Previously this field was required, however given it offers no additional security or privacy benefit it has been deprecated for Megolm messages. See [`m.megolm.v1.aes-sha2`](#mmegolmv1aes-sha2) for more information. @@ -57,7 +57,7 @@ properties: device_id: type: string x-changedInMatrixVersion: - 1.3: |- + "1.3": |- Previously this field was required for Megolm messages, however given it offers no additional security or privacy benefit it has been deprecated for Megolm messages. See [`m.megolm.v1.aes-sha2`](#mmegolmv1aes-sha2) for diff --git a/data/event-schemas/schema/m.room_key_request.yaml b/data/event-schemas/schema/m.room_key_request.yaml index acabe2d9..9894456e 100644 --- a/data/event-schemas/schema/m.room_key_request.yaml +++ b/data/event-schemas/schema/m.room_key_request.yaml @@ -24,7 +24,7 @@ properties: sender_key: type: string x-changedInMatrixVersion: - 1.3: |- + "1.3": |- Previously this field was required, however given it offers no additional security or privacy benefit it has been deprecated. See [`m.megolm.v1.aes-sha2`](#mmegolmv1aes-sha2) for more information. From 49957be1e3656364ac31268364abe0e9be1aac43 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Tue, 13 Jun 2023 16:12:25 +0200 Subject: [PATCH 38/59] Allow `null` in `room_types` for `POST /publicRooms` endpoints (#1564) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- .../newsfragments/1564.clarification | 1 + .../newsfragments/1564.clarification | 1 + data/api/client-server/list_public_rooms.yaml | 2 +- data/api/server-server/public_rooms.yaml | 2 +- layouts/partials/openapi/render-object-table.html | 15 ++++++++++++++- 5 files changed, 18 insertions(+), 3 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1564.clarification create mode 100644 changelogs/server_server/newsfragments/1564.clarification diff --git a/changelogs/client_server/newsfragments/1564.clarification b/changelogs/client_server/newsfragments/1564.clarification new file mode 100644 index 00000000..59fcf699 --- /dev/null +++ b/changelogs/client_server/newsfragments/1564.clarification @@ -0,0 +1 @@ +Allow `null` in `room_types` in `POST /publicRooms` endpoints schemas. diff --git a/changelogs/server_server/newsfragments/1564.clarification b/changelogs/server_server/newsfragments/1564.clarification new file mode 100644 index 00000000..59fcf699 --- /dev/null +++ b/changelogs/server_server/newsfragments/1564.clarification @@ -0,0 +1 @@ +Allow `null` in `room_types` in `POST /publicRooms` endpoints schemas. diff --git a/data/api/client-server/list_public_rooms.yaml b/data/api/client-server/list_public_rooms.yaml index e4f0551b..ba816b06 100644 --- a/data/api/client-server/list_public_rooms.yaml +++ b/data/api/client-server/list_public_rooms.yaml @@ -214,7 +214,7 @@ paths: type: array x-addedInMatrixVersion: "1.4" items: - type: string + type: ["string", "null"] description: |- An optional list of [room types](/client-server-api/#types) to search for. To include rooms without a room type, specify `null` within this diff --git a/data/api/server-server/public_rooms.yaml b/data/api/server-server/public_rooms.yaml index dd909f8f..c81789ae 100644 --- a/data/api/server-server/public_rooms.yaml +++ b/data/api/server-server/public_rooms.yaml @@ -107,7 +107,7 @@ paths: type: array x-addedInMatrixVersion: "1.4" items: - type: string + type: ["string", "null"] description: |- An optional list of [room types](/client-server-api/#types) to search for. To include rooms without a room type, specify `null` within this diff --git a/layouts/partials/openapi/render-object-table.html b/layouts/partials/openapi/render-object-table.html index 5c38be87..4fc5ac76 100644 --- a/layouts/partials/openapi/render-object-table.html +++ b/layouts/partials/openapi/render-object-table.html @@ -102,11 +102,24 @@ internal structure, handle this with a bit of recursion */}} {{ $type = delimit (slice "{string: " (partial "type-or-title" .additionalProperties) "}" ) "" }} - {{ else if and .oneOf (reflect.IsSlice .oneOf) }} + {{ else if reflect.IsSlice .type }} {{/* It's legal to specify an array of types. Join them together in that case */}} {{ $types := slice }} + {{ range .type }} + {{ $types = $types | append . }} + {{ end }} + + {{ $type = delimit $types "|" }} + {{ else if and .oneOf (reflect.IsSlice .oneOf) }} + {{/* + This is like an array of types except some of the types probably have a schema. + Join them together too. + */}} + + {{ $types := slice }} + {{ range .oneOf }} {{ $types = $types | append .type }} {{ end }} From 4a9bda9bed667a29313d3b9c2c4b9e3916ed40ca Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Tue, 20 Jun 2023 19:20:22 +0200 Subject: [PATCH 39/59] Use tag name as the OpenAPI definition version (#1561) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- .github/workflows/main.yml | 8 ++++++++ changelogs/internal/newsfragments/1561.clarification | 1 + 2 files changed, 9 insertions(+) create mode 100644 changelogs/internal/newsfragments/1561.clarification diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index aa5d701f..060ed0dd 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -86,18 +86,26 @@ jobs: pip install -r scripts/requirements.txt - name: "📦 Asset creation" run: | + if [[ "${GITHUB_REF}" == refs/tags/* ]]; then + export RELEASE="${GITHUB_REF/refs\/tags\//}" + else + export RELEASE="unstable" + fi # The output path matches the final deployment path at spec.matrix.org scripts/dump-swagger.py \ --base-url "https://spec.matrix.org${{ needs.calculate-baseurl.outputs.baseURL }}" \ --api application-service \ + -r "$RELEASE" \ -o spec/application-service-api/api.json scripts/dump-swagger.py \ --base-url "https://spec.matrix.org${{ needs.calculate-baseurl.outputs.baseURL }}" \ --api client-server \ + -r "$RELEASE" \ -o spec/client-server-api/api.json scripts/dump-swagger.py \ --base-url "https://spec.matrix.org${{ needs.calculate-baseurl.outputs.baseURL }}" \ --api push-gateway \ + -r "$RELEASE" \ -o spec/push-gateway-api/api.json tar -czf openapi.tar.gz spec - name: "📤 Artifact upload" diff --git a/changelogs/internal/newsfragments/1561.clarification b/changelogs/internal/newsfragments/1561.clarification new file mode 100644 index 00000000..6381ddf3 --- /dev/null +++ b/changelogs/internal/newsfragments/1561.clarification @@ -0,0 +1 @@ +Use tag name as the OpenAPI definition version. From 564444d43edb70d77fdf1233e5f381001dbcb115 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Tue, 20 Jun 2023 19:33:06 +0200 Subject: [PATCH 40/59] Render binary request and response bodies (#1579) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- assets/scss/custom.scss | 2 +- .../newsfragments/1579.clarification | 1 + data/api/client-server/account-data.yaml | 2 + data/api/client-server/content-repo.yaml | 18 +-- .../partials/openapi/render-content-type.html | 27 ++++ layouts/partials/openapi/render-request.html | 51 ++++++-- .../partials/openapi/render-responses.html | 119 ++++++++++-------- 7 files changed, 142 insertions(+), 78 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1579.clarification create mode 100644 layouts/partials/openapi/render-content-type.html diff --git a/assets/scss/custom.scss b/assets/scss/custom.scss index 9d748bd2..7cdc35ce 100644 --- a/assets/scss/custom.scss +++ b/assets/scss/custom.scss @@ -374,7 +374,7 @@ footer { padding: 1rem; } - &.object-table, &.response-table { + &.object-table, &.response-table, &.content-type-table { border: 1px $table-border-color solid; caption { diff --git a/changelogs/client_server/newsfragments/1579.clarification b/changelogs/client_server/newsfragments/1579.clarification new file mode 100644 index 00000000..d53f2352 --- /dev/null +++ b/changelogs/client_server/newsfragments/1579.clarification @@ -0,0 +1 @@ +Render binary request and response bodies. diff --git a/data/api/client-server/account-data.yaml b/data/api/client-server/account-data.yaml index b4526198..bf89b21b 100644 --- a/data/api/client-server/account-data.yaml +++ b/data/api/client-server/account-data.yaml @@ -327,6 +327,8 @@ paths: `M_INVALID_PARAM`." content: application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml examples: response: value: { diff --git a/data/api/client-server/content-repo.yaml b/data/api/client-server/content-repo.yaml index 7792b2a9..c8800279 100644 --- a/data/api/client-server/content-repo.yaml +++ b/data/api/client-server/content-repo.yaml @@ -39,10 +39,7 @@ paths: requestBody: content: application/octet-stream: - schema: - type: string - example: - format: byte + example: description: The content to be uploaded. required: true responses: @@ -142,10 +139,7 @@ paths: requestBody: content: application/octet-stream: - schema: - type: string - example: - format: byte + example: description: The content to be uploaded. required: true responses: @@ -361,10 +355,8 @@ paths: content: application/octet-stream: schema: - type: string # This is a workaround for us not being able to say the response is required. description: "**Required.** The bytes for the uploaded file." - format: binary "307": description: A redirect to the thumbnail of the requested content. headers: @@ -500,10 +492,8 @@ paths: content: application/octet-stream: schema: - type: string # This is a workaround for us not being able to say the response is required. description: "**Required.** The bytes for the uploaded file." - format: binary "307": description: A redirect to the thumbnail of the requested content. headers: @@ -657,15 +647,11 @@ paths: content: image/jpeg: schema: - type: string # This is a workaround for us not being able to say the response is required. description: "**Required.** The bytes for the thumbnail." - format: binary image/png: schema: - type: string description: "**Required.** The bytes for the thumbnail." - format: binary "307": description: A redirect to the thumbnail of the requested content. headers: diff --git a/layouts/partials/openapi/render-content-type.html b/layouts/partials/openapi/render-content-type.html new file mode 100644 index 00000000..da1a69bd --- /dev/null +++ b/layouts/partials/openapi/render-content-type.html @@ -0,0 +1,27 @@ +{{/* + + Render a table showing content type and description, given: + + * `content_type`: the content type as a string + + * `description`: the description as a string + +*/}} + +{{ $content_type := .content_type }} +{{ $description := .description}} + +{{ if $content_type }} + + + + + + + + + + +
Content-TypeDescription
{{ $content_type }}{{ $description | markdownify -}}
+ +{{ end }} diff --git a/layouts/partials/openapi/render-request.html b/layouts/partials/openapi/render-request.html index 36b846da..ce31943c 100644 --- a/layouts/partials/openapi/render-request.html +++ b/layouts/partials/openapi/render-request.html @@ -35,10 +35,13 @@ {{ if $request_body }}

Request body

{{/* - A request can have several content types. Only show the schema for JSON. + A request can have several content types. */}} {{ $json_body := index $request_body.content "application/json" }} {{ if $json_body }} + {{/* + Display the JSON schemas + */}} {{ $schema := partial "json-schema/resolve-refs" (dict "schema" $json_body.schema "path" $path) }} {{ $schema := partial "json-schema/resolve-allof" $schema }} @@ -47,6 +50,16 @@ {{ range $additional_types }} {{ partial "openapi/render-object-table" . }} {{ end }} + {{ else }} + {{/* + Show the content types and description. + */}} + {{ $mimes := slice }} + {{ range $mime, $body := $request_body.content }} + {{ $mimes = $mimes | append $mime }} + {{ end }} + {{ $content_type := delimit $mimes "|"}} + {{ partial "openapi/render-content-type" (dict "content_type" $content_type "description" $request_body.description) }} {{ end }}

Request body example

@@ -54,17 +67,41 @@ Show all the examples. */}} {{ range $mime, $body := $request_body.content }} - {{ $schema := partial "json-schema/resolve-refs" (dict "schema" $body.schema "path" $path) }} - {{ $schema := partial "json-schema/resolve-allof" $schema }} + {{ $example := dict }} - {{ $example := partial "json-schema/resolve-example" $schema }} - {{ $example_json := jsonify (dict "indent" " ") $example }} - {{ $example_json = replace $example_json "\\u003c" "<" }} - {{ $example_json = replace $example_json "\\u003e" ">" | safeHTML }} + {{ if $body.schema }} + {{ $schema := partial "json-schema/resolve-refs" (dict "schema" $body.schema "path" $path) }} + {{ $schema := partial "json-schema/resolve-allof" $schema }} + {{ $example = partial "json-schema/resolve-example" $schema }} + {{ end }} + + {{ if and (eq ($example | len) 0) $body.example }} + {{/* + If no example was generated from the schema, fallback to the + main example. + */}} + {{ $example = $body.example }} + {{ end }} + + {{ if eq $mime "application/json" }} + {{ $example_json := jsonify (dict "indent" " ") $example }} + {{ $example_json = replace $example_json "\\u003c" "<" }} + {{ $example_json = replace $example_json "\\u003e" ">" | safeHTML }} ```json {{ $example_json }} ``` + {{ else }} + {{ $example = $example | safeHTML }} + {{/* + We need to set a language for the code otherwise the styling + is different than other examples. + */}} +```json +{{ $example }} +``` + {{ end }} + {{ end }} {{ end }} diff --git a/layouts/partials/openapi/render-responses.html b/layouts/partials/openapi/render-responses.html index 9ef643e5..37538b6e 100644 --- a/layouts/partials/openapi/render-responses.html +++ b/layouts/partials/openapi/render-responses.html @@ -38,73 +38,84 @@ {{ range $code, $response := $responses }} - {{/* - A response can have several content types so only insert the title once. - */}} - {{ $is_title_set := false }} - {{ range $content_type, $content := $response.content }} - {{ if $content.schema }} - - {{ if not $is_title_set }} - {{ $is_title_set = true }} + {{ if $response.content }}

{{$code}} response

- {{ end }} - - {{ $schema := partial "json-schema/resolve-refs" (dict "schema" $content.schema "path" $path) }} - {{ $schema := partial "json-schema/resolve-allof" $schema }} - {{/* - All this is to work out how to express the content of the response - in the case where it is an array. + A response can have several content types. */}} - {{ if eq $schema.type "array" }} - {{ $type_of := "" }} - {{ if $schema.items.anyOf }} - {{ $types := slice }} - {{ range $schema.items.anyOf }} - {{ if .title }} - {{ $types = $types | append .title}} - {{ else }} - {{ $types = $types | append .type }} + {{ $json_body := index $response.content "application/json" }} + {{ if $json_body }} + {{/* + Display the JSON schemas + */}} + + {{ $schema := partial "json-schema/resolve-refs" (dict "schema" $json_body.schema "path" $path) }} + {{ $schema := partial "json-schema/resolve-allof" $schema }} + + {{/* + All this is to work out how to express the content of the response + in the case where it is an array. + */}} + {{ if eq $schema.type "array" }} + {{ $type_of := "" }} + {{ if $schema.items.anyOf }} + {{ $types := slice }} + {{ range $schema.items.anyOf }} + {{ if .title }} + {{ $types = $types | append .title}} + {{ else }} + {{ $types = $types | append .type }} + {{ end }} {{ end }} + {{ $type_of = delimit $types ", "}} + {{ else }} + {{ $type_of = $schema.items.title }} {{ end }} - {{ $type_of = delimit $types ", "}} - {{ else }} - {{ $type_of = $schema.items.title }} - {{ end }}

Array of {{ $type_of }}.

- {{ end }} - - - {{/* - render object tables for any objects referenced in the - response. (This will be a no-op for response types which aren't - objects or arrays.) - */}} - {{ $additional_types := partial "json-schema/resolve-additional-types" (dict "schema" $schema "anchor_base" $anchor_base) }} - {{ $additional_types = uniq $additional_types }} - {{ range $additional_types }} - {{ partial "openapi/render-object-table" . }} - {{ end }} - - {{/* - render an example. currently this is only supported for arrays and objects. - */}} - {{ if or (eq $schema.type "object") (eq $schema.type "array") }} - {{ $example := partial "json-schema/resolve-example" $schema }} - {{ if $content.examples }} - {{ $example = partial "json-schema/resolve-refs" (dict "schema" $content.examples "path" $path) }} - {{ $example = $example.response.value }} {{ end }} - {{ $example_json := jsonify (dict "indent" " ") $example }} - {{ $example_json = replace $example_json "\\u003c" "<" }} - {{ $example_json = replace $example_json "\\u003e" ">" | safeHTML }} + + {{/* + render object tables for any objects referenced in the + response. (This will be a no-op for response types which aren't + objects or arrays.) + */}} + {{ $additional_types := partial "json-schema/resolve-additional-types" (dict "schema" $schema "anchor_base" $anchor_base) }} + {{ $additional_types = uniq $additional_types }} + {{ range $additional_types }} + {{ partial "openapi/render-object-table" . }} + {{ end }} + + {{/* + render an example. currently this is only supported for arrays and objects. + */}} + {{ if or (eq $schema.type "object") (eq $schema.type "array") }} + {{ $example := partial "json-schema/resolve-example" $schema }} + {{ if $json_body.examples }} + {{ $example = partial "json-schema/resolve-refs" (dict "schema" $json_body.examples "path" $path) }} + {{ $example = $example.response.value }} + {{ end }} + + {{ $example_json := jsonify (dict "indent" " ") $example }} + {{ $example_json = replace $example_json "\\u003c" "<" }} + {{ $example_json = replace $example_json "\\u003e" ">" | safeHTML }} ```json {{ $example_json }} ``` {{ end }} + {{ else }} + {{/* + Show the content types and description. + */}} + {{ $mimes := slice }} + {{ $desc := "" }} + {{ range $mime, $body := $response.content }} + {{ $mimes = $mimes | append $mime }} + {{ $desc = $body.schema.description }} + {{ end }} + {{ $content_type := delimit $mimes "|"}} + {{ partial "openapi/render-content-type" (dict "content_type" $content_type "description" $desc) }} {{ end }} {{ end }} {{ end }} From b79fa06cfb24813b410330ff7cc4da9035b69eb0 Mon Sep 17 00:00:00 2001 From: Midnight Veil Date: Wed, 21 Jun 2023 23:51:50 +1000 Subject: [PATCH 41/59] Fix headers with custom IDs via the correct syntax (#1578) Was previously using elements which just add another anchor rather than changing the existing one. They also use a deprecated HTML attribute and in some cases broke the header display. Fixes #1572. Signed-off-by: Midnight Veil --- changelogs/client_server/newsfragments/1578.clarification | 1 + changelogs/server_server/newsfragments/1578.clarification | 1 + content/client-server-api/modules/end_to_end_encryption.md | 5 ++--- content/server-server-api.md | 3 +-- 4 files changed, 5 insertions(+), 5 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1578.clarification create mode 100644 changelogs/server_server/newsfragments/1578.clarification diff --git a/changelogs/client_server/newsfragments/1578.clarification b/changelogs/client_server/newsfragments/1578.clarification new file mode 100644 index 00000000..09e9dc70 --- /dev/null +++ b/changelogs/client_server/newsfragments/1578.clarification @@ -0,0 +1 @@ +Fix broken header formatting. Contributed by @midnightveil. diff --git a/changelogs/server_server/newsfragments/1578.clarification b/changelogs/server_server/newsfragments/1578.clarification new file mode 100644 index 00000000..09e9dc70 --- /dev/null +++ b/changelogs/server_server/newsfragments/1578.clarification @@ -0,0 +1 @@ +Fix broken header formatting. Contributed by @midnightveil. diff --git a/content/client-server-api/modules/end_to_end_encryption.md b/content/client-server-api/modules/end_to_end_encryption.md index 067fadab..27bf673a 100644 --- a/content/client-server-api/modules/end_to_end_encryption.md +++ b/content/client-server-api/modules/end_to_end_encryption.md @@ -134,8 +134,7 @@ are offline/unable to upload additional keys, though sessions started using fallback keys could be vulnerable to replay attacks. {{% /boxes/warning %}} -Devices will be informed, [via -`/sync`](#a-namee2e-extensions-to-sync-extensions-to-sync), about the number of +Devices will be informed, [via `/sync`](#e2e-extensions-to-sync), about the number of one-time keys remaining that can be claimed, as well as whether the fallback keys have been used. The device can thus ensure that, while it is online, there is a sufficient supply of one-time keys available, and that the fallback keys @@ -1699,7 +1698,7 @@ When a client is updating a Megolm session in its store, the client MUST ensure: {{% http-api spec="client-server" api="keys" %}} -##### Extensions to /sync +##### Extensions to /sync {#e2e-extensions-to-sync} This module adds an optional `device_lists` property to the [`/sync`](/client-server-api/#get_matrixclientv3sync) response, as specified below. The server need only populate this property for an diff --git a/content/server-server-api.md b/content/server-server-api.md index b8c78345..2dc80da5 100644 --- a/content/server-server-api.md +++ b/content/server-server-api.md @@ -877,8 +877,7 @@ on the resulting `m.room.member` event. If the joining server fails all conditions then a 403 `M_FORBIDDEN` error is used by the resident server. - -## Knocking upon a room +## Knocking upon a room {#knocking-rooms} Rooms can permit knocking through the join rules, and if permitted this gives users a way to request to join (be invited) to the room. Users who From 30845e189fef3e53e807bf78598e01f4cbe90880 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Fri, 23 Jun 2023 15:31:17 +0200 Subject: [PATCH 42/59] Remove unnecessary `oneOf`s in JSON schemas (#1585) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Remove unnecessary `oneOf`s in JSON schemas Signed-off-by: Kévin Commaille * Add changelog Signed-off-by: Kévin Commaille --------- Signed-off-by: Kévin Commaille --- .../client_server/newsfragments/1585.clarification | 1 + data/api/client-server/definitions/push_rule.yaml | 4 +--- data/api/client-server/notifications.yaml | 4 +--- data/api/client-server/pushrules.yaml | 12 +++--------- 4 files changed, 6 insertions(+), 15 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1585.clarification diff --git a/changelogs/client_server/newsfragments/1585.clarification b/changelogs/client_server/newsfragments/1585.clarification new file mode 100644 index 00000000..5b26ae97 --- /dev/null +++ b/changelogs/client_server/newsfragments/1585.clarification @@ -0,0 +1 @@ +Remove unnecessary `oneOf`s in JSON schemas. diff --git a/data/api/client-server/definitions/push_rule.yaml b/data/api/client-server/definitions/push_rule.yaml index 4f1b41ad..a6534895 100644 --- a/data/api/client-server/definitions/push_rule.yaml +++ b/data/api/client-server/definitions/push_rule.yaml @@ -17,9 +17,7 @@ type: object properties: actions: items: - oneOf: - - type: object - - type: string + type: ["string", "object"] type: array description: |- The actions to perform when this rule is matched. diff --git a/data/api/client-server/notifications.yaml b/data/api/client-server/notifications.yaml index 1cde576b..21d6640a 100644 --- a/data/api/client-server/notifications.yaml +++ b/data/api/client-server/notifications.yaml @@ -86,9 +86,7 @@ paths: The action(s) to perform when the conditions for this rule are met. See [Push Rules: API](/client-server-api/#push-rules-api). items: - oneOf: - - type: object - - type: string + type: ["object", "string"] event: title: Event description: The Event object for the event that triggered the notification. diff --git a/data/api/client-server/pushrules.yaml b/data/api/client-server/pushrules.yaml index 77a07afd..88013307 100644 --- a/data/api/client-server/pushrules.yaml +++ b/data/api/client-server/pushrules.yaml @@ -458,9 +458,7 @@ paths: type: array description: The action(s) to perform when the conditions for this rule are met. items: - oneOf: - - type: string - - type: object + type: ["string", "object"] conditions: type: array description: |- @@ -723,9 +721,7 @@ paths: type: array description: The action(s) to perform for this rule. items: - oneOf: - - type: string - - type: object + type: ["string", "object"] required: - actions examples: @@ -801,9 +797,7 @@ paths: type: array description: The action(s) to perform for this rule. items: - oneOf: - - type: string - - type: object + type: ["string", "object"] required: - actions example: { From a6eb381ebb380d237ddfe899c83367392d38baf5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Tue, 27 Jun 2023 23:24:22 +0200 Subject: [PATCH 43/59] Fix the sidebar in recent versions of Hugo (#1551) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- assets/scss/custom.scss | 20 +++--- .../internal/newsfragments/1551.clarification | 1 + config.toml | 4 ++ layouts/partials/sidebar-tree.html | 61 ------------------- static/js/toc.js | 11 +++- 5 files changed, 27 insertions(+), 70 deletions(-) create mode 100644 changelogs/internal/newsfragments/1551.clarification delete mode 100644 layouts/partials/sidebar-tree.html diff --git a/assets/scss/custom.scss b/assets/scss/custom.scss index 7cdc35ce..047e57d7 100644 --- a/assets/scss/custom.scss +++ b/assets/scss/custom.scss @@ -68,9 +68,8 @@ Custom SCSS for the Matrix spec margin-top: 1rem; } - &>.td-sidebar-nav__section > li > a.td-sidebar-link { - font-weight: $font-weight-bold; - font-size: 1.3rem; + .td-sidebar-nav__section .ul-1 ul { + padding-left: 0; } /* This is to make the width of the items that have sub-items (like room versions) @@ -79,12 +78,20 @@ Custom SCSS for the Matrix spec padding-right: 0 !important; } - a.indent-1 { + .ul-1 > li > a { padding-left: 1rem !important; } - a.indent-2 { - padding-left: 2rem; + .ul-2 > li > a { + padding-left: 2rem !important; + } + + a.td-sidebar-link.tree-root { + color: $gray-800; + font-weight: $font-weight-bold; + font-size: 1.3rem; + margin-bottom: 0; + border-bottom: none; } a, a.td-sidebar-link { @@ -103,7 +110,6 @@ Custom SCSS for the Matrix spec &.active, &active:hover { background-color: $secondary-background; - font-weight: $font-weight-normal; } } } diff --git a/changelogs/internal/newsfragments/1551.clarification b/changelogs/internal/newsfragments/1551.clarification new file mode 100644 index 00000000..b9f32571 --- /dev/null +++ b/changelogs/internal/newsfragments/1551.clarification @@ -0,0 +1 @@ +Fix the sidebar in recent versions of Hugo diff --git a/config.toml b/config.toml index 00757bd5..c6f1bd45 100644 --- a/config.toml +++ b/config.toml @@ -62,6 +62,10 @@ current_version_url = "https://spec.matrix.org/latest" footer_about_disable = false # Collapse HTTP API and event
elements rendered_data_collapsed = false +# Hide the search entry in the sidebar +sidebar_search_disable = true +# Only show the current page's ancestors, siblings and direct descendants in the sidebar menu +sidebar_menu_compact = true [params.links] # End user relevant links. These will show up on left side of footer and in the community page if you have one. diff --git a/layouts/partials/sidebar-tree.html b/layouts/partials/sidebar-tree.html deleted file mode 100644 index 3589868e..00000000 --- a/layouts/partials/sidebar-tree.html +++ /dev/null @@ -1,61 +0,0 @@ -{{/* - - A version of the sidebar-tree.html partial in Docsy, with a few small - modifications: - - * include `div#toc` for the ToC - * start the sidebar at the root (homepage) since for us that is the Matrix - overview page - -*/}} - -{{/* We cache this partial for bigger sites and set the active class client side. */}} -{{ $shouldDelayActive := ge (len .Site.Pages) 2000 }} -
-
-
- {{ partial "search-input.html" . }} - -
-
-
- -
- -{{ define "section-tree-nav-section" }} - {{ $s := .section }} - {{ $p := .page }} - {{ $shouldDelayActive := .delayActive }} - {{ $indent := .indent }} - {{ $active := eq $p.RelPermalink $s.RelPermalink }} - {{ $show := or ($p.IsAncestor $s) ($p.IsDescendant $s) }} - {{ $sid := $s.RelPermalink | anchorize }} -
    -
  • - {{ $s.LinkTitle }} - {{ $pages := where (union $s.Pages $s.Sections).ByWeight ".Params.toc_hide" "!=" true }} - {{ $pages := $pages | first 50 }} - {{ if gt (len $pages) 0 }} -
      - {{ range $pages }} - {{ if .IsPage }} - {{ $mid := printf "m-%s" (.RelPermalink | anchorize) }} - {{ $active := eq . $p }} -
    • - {{ .LinkTitle }} -
      • - {{ else }} - {{ $indent := add $indent 1 }} - {{ template "section-tree-nav-section" (dict "page" $p "section" . "indent" $indent) }} - {{ end }} - {{ end }} -
    - {{ end }} -
    • -
-{{ end }} diff --git a/static/js/toc.js b/static/js/toc.js index fa36ba4a..6386e40d 100644 --- a/static/js/toc.js +++ b/static/js/toc.js @@ -111,11 +111,18 @@ function makeToc() { const section = makeTocSection(tocTargets, 0); nav.appendChild(section.content); - // append title and content to the #toc placeholder - const toc = document.body.querySelector("#toc"); + // build the TOC and append to it title and content + const toc = document.createElement("div"); + toc.id = "toc"; toc.appendChild(title); toc.appendChild(nav); + // append TOC to the section navigation + const section_nav = document.body.querySelector("#td-section-nav"); + let hr = document.createElement("hr"); + section_nav.appendChild(hr); + section_nav.appendChild(toc); + // tell ToC items about any rendered-data headings they contain setTocItemChildren(section.content, headings); } From b2ab339ba6e600ce18bea767f94c4e144cd75395 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Wed, 28 Jun 2023 07:26:14 +0100 Subject: [PATCH 44/59] Bump hugo version used for the build (#1591) Since https://github.com/matrix-org/matrix-spec/issues/1544 is fixed, we can use a modern hugo. --- .github/workflows/main.yml | 2 +- changelogs/internal/newsfragments/1591.clarification | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 changelogs/internal/newsfragments/1591.clarification diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 060ed0dd..d836b100 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -148,7 +148,7 @@ jobs: - name: "➕ Setup Hugo" uses: peaceiris/actions-hugo@c03b5dbed22245418539b65eb9a3b1d5fdd9a0a6 with: - hugo-version: '0.93.3' + hugo-version: '0.113.0' extended: true - name: "📥 Source checkout" uses: actions/checkout@v2 diff --git a/changelogs/internal/newsfragments/1591.clarification b/changelogs/internal/newsfragments/1591.clarification new file mode 100644 index 00000000..3ee889ff --- /dev/null +++ b/changelogs/internal/newsfragments/1591.clarification @@ -0,0 +1 @@ +Update the version of Hugo used to render the spec to v0.113.0. From 903b206e3b37222d7de5ba19bce3f16c3f614f02 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 28 Jun 2023 08:11:28 -0600 Subject: [PATCH 45/59] Specify our usage of ABNF for grammar (#1582) * Specify our usage of ABNF for grammar * Create 1582.clarification * Update meta/documentation_style.rst Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --------- Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- changelogs/internal/newsfragments/1582.clarification | 1 + meta/documentation_style.rst | 7 +++++++ 2 files changed, 8 insertions(+) create mode 100644 changelogs/internal/newsfragments/1582.clarification diff --git a/changelogs/internal/newsfragments/1582.clarification b/changelogs/internal/newsfragments/1582.clarification new file mode 100644 index 00000000..2f048a06 --- /dev/null +++ b/changelogs/internal/newsfragments/1582.clarification @@ -0,0 +1 @@ +Clarify usage of ABNF for grammar in the documentation style guide. diff --git a/meta/documentation_style.rst b/meta/documentation_style.rst index 468b2675..e7b71408 100644 --- a/meta/documentation_style.rst +++ b/meta/documentation_style.rst @@ -185,3 +185,10 @@ The subheadings which are always deemed as client-affecting are: * Redactions When a new subheading is added, it must be referenced and ordered in this document. + +Describing grammar +~~~~~~~~~~~~~~~~~~ + +Use `RFC5234-style ABNF `_ when describing +the grammar for something in the spec, such as user IDs or server names. Use lowercase +and underscore-deliminated element names (`user_id`, not `UserID` or `user-id`). From 42114406afdd129cbd6d260bd413f344b1c648d0 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Thu, 29 Jun 2023 18:54:47 +0100 Subject: [PATCH 46/59] Update link to SAS emoji data (#1593) --- changelogs/client_server/newsfragments/1593.clarification | 1 + content/client-server-api/modules/end_to_end_encryption.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 changelogs/client_server/newsfragments/1593.clarification diff --git a/changelogs/client_server/newsfragments/1593.clarification b/changelogs/client_server/newsfragments/1593.clarification new file mode 100644 index 00000000..2f6cbee6 --- /dev/null +++ b/changelogs/client_server/newsfragments/1593.clarification @@ -0,0 +1 @@ +Update link to SAS emoji definition data. diff --git a/content/client-server-api/modules/end_to_end_encryption.md b/content/client-server-api/modules/end_to_end_encryption.md index 27bf673a..d1efae40 100644 --- a/content/client-server-api/modules/end_to_end_encryption.md +++ b/content/client-server-api/modules/end_to_end_encryption.md @@ -891,7 +891,7 @@ following table to get the corresponding emoji: {{% boxes/note %}} This table is available as JSON at - +. {{% /boxes/note %}} {{% boxes/rationale %}} From 414cc1ea52bd81b9e188d360b83572345b3f55a5 Mon Sep 17 00:00:00 2001 From: cheb Date: Tue, 4 Jul 2023 14:52:48 +0200 Subject: [PATCH 47/59] Add missing type enum for m.reaction (#1552) --- changelogs/client_server/newsfragments/1552.clarification | 1 + data/event-schemas/schema/m.reaction.yaml | 4 ++++ 2 files changed, 5 insertions(+) create mode 100644 changelogs/client_server/newsfragments/1552.clarification diff --git a/changelogs/client_server/newsfragments/1552.clarification b/changelogs/client_server/newsfragments/1552.clarification new file mode 100644 index 00000000..3f8cdbfb --- /dev/null +++ b/changelogs/client_server/newsfragments/1552.clarification @@ -0,0 +1 @@ +Fix missing `type` property in the JSON schema definition of the `m.reaction` event. Contributed by @chebureki. diff --git a/data/event-schemas/schema/m.reaction.yaml b/data/event-schemas/schema/m.reaction.yaml index 6d369c5f..e7ad0ba1 100644 --- a/data/event-schemas/schema/m.reaction.yaml +++ b/data/event-schemas/schema/m.reaction.yaml @@ -37,3 +37,7 @@ properties: (see the [emoji variation sequences list](https://www.unicode.org/Public/UCD/latest/ucd/emoji/emoji-variation-sequences.txt)). example: "👍" + type: + enum: + - m.reaction + type: string From e9acece3ecc6995f04e55f7e38d6411be1a7876d Mon Sep 17 00:00:00 2001 From: Tony Garnock-Jones Date: Tue, 4 Jul 2023 14:59:37 +0200 Subject: [PATCH 48/59] Cope with negative-zero, and give an example of negative-zero and a large power of ten (#1573) --- .../newsfragments/1573.clarification | 1 + content/appendices.md | 18 +++++++++++++++++- 2 files changed, 18 insertions(+), 1 deletion(-) create mode 100644 changelogs/appendices/newsfragments/1573.clarification diff --git a/changelogs/appendices/newsfragments/1573.clarification b/changelogs/appendices/newsfragments/1573.clarification new file mode 100644 index 00000000..7210ae76 --- /dev/null +++ b/changelogs/appendices/newsfragments/1573.clarification @@ -0,0 +1 @@ +Clarify spec re canonical JSON to handle negative-zero; also, give an example of negative-zero and a large power of ten diff --git a/content/appendices.md b/content/appendices.md index 52940aa6..4592c428 100644 --- a/content/appendices.md +++ b/content/appendices.md @@ -90,7 +90,8 @@ To ensure that all implementations use the same JSON encoding we define We define this encoding for a value to be the shortest UTF-8 JSON encoding with dictionary keys lexicographically sorted by Unicode codepoint. Numbers in the JSON must be integers in the range -`[-(2**53)+1, (2**53)-1]`. +`[-(2**53)+1, (2**53)-1]`, represented without exponents or decimal +places, and negative zero `-0` MUST NOT appear. We pick UTF-8 as the encoding as it should be available to all platforms and JSON received from the network is likely to be already encoded using @@ -304,6 +305,21 @@ The following canonical JSON should be produced: {"a":null} ``` +Given the following JSON object: + +```json +{ + "a": -0, + "b": 1e10 +} +``` + +The following canonical JSON should be produced: + +```json +{"a":0,"b":10000000000} +``` + ### Signing Details JSON is signed by encoding the JSON object without `signatures` or keys From 65214115471ec362ae5791a40d5eae6abbb6b419 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 4 Jul 2023 09:40:43 -0400 Subject: [PATCH 49/59] Allow + in Matrix IDs. (#1583) --- changelogs/appendices/newsfragments/1583.feature | 1 + content/appendices.md | 6 ++++-- 2 files changed, 5 insertions(+), 2 deletions(-) create mode 100644 changelogs/appendices/newsfragments/1583.feature diff --git a/changelogs/appendices/newsfragments/1583.feature b/changelogs/appendices/newsfragments/1583.feature new file mode 100644 index 00000000..b24077c6 --- /dev/null +++ b/changelogs/appendices/newsfragments/1583.feature @@ -0,0 +1 @@ +Allow `+` in Matrix IDs, per [MSC4009](https://github.com/matrix-org/matrix-spec-proposals/pull/4009). diff --git a/content/appendices.md b/content/appendices.md index 4592c428..59c1b1c3 100644 --- a/content/appendices.md +++ b/content/appendices.md @@ -540,6 +540,8 @@ be represented with a `domain` component under some conditions - see the #### User Identifiers +{{% changed-in v="1.8" %}} + Users within Matrix are uniquely identified by their Matrix user ID. The user ID is namespaced to the homeserver which allocated the account and has the form: @@ -548,7 +550,7 @@ has the form: The `localpart` of a user ID is an opaque identifier for that user. It MUST NOT be empty, and MUST contain only the characters `a-z`, `0-9`, -`.`, `_`, `=`, `-`, and `/`. +`.`, `_`, `=`, `-`, `/`, and `+`. The `domain` of a user ID is the [server name](#server-name) of the homeserver which allocated the account. @@ -562,7 +564,7 @@ The complete grammar for a legal user ID is: user_id_localpart = 1*user_id_char user_id_char = DIGIT / %x61-7A ; a-z - / "-" / "." / "=" / "_" / "/" + / "-" / "." / "=" / "_" / "/" / "+" {{% boxes/rationale %}} A number of factors were considered when defining the allowable From bed9223610d069021a612fecce2cadbcce6616a6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Tue, 4 Jul 2023 20:32:47 +0200 Subject: [PATCH 50/59] Make sure examples types match schema in definitions (#1563) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Make sure examples types match schema in definitions Signed-off-by: Kévin Commaille * Add changelogs Signed-off-by: Kévin Commaille * Add double quotes around URL Signed-off-by: Kévin Commaille --------- Signed-off-by: Kévin Commaille --- changelogs/client_server/newsfragments/1563.clarification | 1 + .../identity_service/newsfragments/1563.clarification | 1 + changelogs/server_server/newsfragments/1563.clarification | 1 + data/api/client-server/message_pagination.yaml | 2 +- data/api/client-server/old_sync.yaml | 6 +++--- data/api/client-server/peeking_events.yaml | 5 ++--- data/api/client-server/pushrules.yaml | 2 +- data/api/client-server/sync.yaml | 2 +- data/api/identity/v2_associations.yaml | 2 +- data/api/identity/v2_email_associations.yaml | 2 +- data/api/identity/v2_phone_associations.yaml | 2 +- data/api/identity/v2_terms.yaml | 2 +- data/api/server-server/leaving-v2.yaml | 4 ++-- 13 files changed, 17 insertions(+), 15 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1563.clarification create mode 100644 changelogs/identity_service/newsfragments/1563.clarification create mode 100644 changelogs/server_server/newsfragments/1563.clarification diff --git a/changelogs/client_server/newsfragments/1563.clarification b/changelogs/client_server/newsfragments/1563.clarification new file mode 100644 index 00000000..1d6ef324 --- /dev/null +++ b/changelogs/client_server/newsfragments/1563.clarification @@ -0,0 +1 @@ +Make sure examples types match schema in definitions. diff --git a/changelogs/identity_service/newsfragments/1563.clarification b/changelogs/identity_service/newsfragments/1563.clarification new file mode 100644 index 00000000..1d6ef324 --- /dev/null +++ b/changelogs/identity_service/newsfragments/1563.clarification @@ -0,0 +1 @@ +Make sure examples types match schema in definitions. diff --git a/changelogs/server_server/newsfragments/1563.clarification b/changelogs/server_server/newsfragments/1563.clarification new file mode 100644 index 00000000..1d6ef324 --- /dev/null +++ b/changelogs/server_server/newsfragments/1563.clarification @@ -0,0 +1 @@ +Make sure examples types match schema in definitions. diff --git a/data/api/client-server/message_pagination.yaml b/data/api/client-server/message_pagination.yaml index 940b9802..07c16497 100644 --- a/data/api/client-server/message_pagination.yaml +++ b/data/api/client-server/message_pagination.yaml @@ -84,7 +84,7 @@ paths: - in: query name: limit description: "The maximum number of events to return. Default: 10." - example: "3" + example: 3 schema: type: integer - in: query diff --git a/data/api/client-server/old_sync.yaml b/data/api/client-server/old_sync.yaml index 3e0ad0b6..540c97c7 100644 --- a/data/api/client-server/old_sync.yaml +++ b/data/api/client-server/old_sync.yaml @@ -44,7 +44,7 @@ paths: name: timeout description: The maximum time in milliseconds to wait for an event. required: false - example: "35000" + example: 35000 schema: type: integer responses: @@ -105,7 +105,7 @@ paths: name: limit description: The maximum number of messages to return for each room. required: false - example: "2" + example: 2 schema: type: integer - in: query @@ -116,7 +116,7 @@ paths: included. If set to `true` then rooms that the user has left are included as well. By default this is `false`. required: false - example: "true" + example: true schema: type: boolean responses: diff --git a/data/api/client-server/peeking_events.yaml b/data/api/client-server/peeking_events.yaml index 19eb67a0..b323d940 100644 --- a/data/api/client-server/peeking_events.yaml +++ b/data/api/client-server/peeking_events.yaml @@ -49,14 +49,13 @@ paths: name: timeout description: The maximum time in milliseconds to wait for an event. required: false - example: "35000" + example: 35000 schema: type: integer - in: query name: room_id description: The room ID for which events should be returned. - example: - - "!somewhere:over.the.rainbow" + example: "!somewhere:over.the.rainbow" schema: type: string responses: diff --git a/data/api/client-server/pushrules.yaml b/data/api/client-server/pushrules.yaml index 88013307..57638583 100644 --- a/data/api/client-server/pushrules.yaml +++ b/data/api/client-server/pushrules.yaml @@ -543,7 +543,7 @@ paths: required: true description: | The kind of rule - example: cake + example: content schema: type: string enum: diff --git a/data/api/client-server/sync.yaml b/data/api/client-server/sync.yaml index 0b22a96e..5e554722 100644 --- a/data/api/client-server/sync.yaml +++ b/data/api/client-server/sync.yaml @@ -84,7 +84,7 @@ paths: changed since the point indicated by `since` will be returned. By default, this is `false`. - example: "false" + example: false schema: type: boolean - in: query diff --git a/data/api/identity/v2_associations.yaml b/data/api/identity/v2_associations.yaml index 8ed4041a..c9b8ba6e 100644 --- a/data/api/identity/v2_associations.yaml +++ b/data/api/identity/v2_associations.yaml @@ -29,7 +29,7 @@ paths: name: sid description: The Session ID generated by the `requestToken` call. required: true - example: 1234 + example: "1234" schema: type: string - in: query diff --git a/data/api/identity/v2_email_associations.yaml b/data/api/identity/v2_email_associations.yaml index 0bd31b52..ad5c2517 100644 --- a/data/api/identity/v2_email_associations.yaml +++ b/data/api/identity/v2_email_associations.yaml @@ -186,7 +186,7 @@ paths: name: sid required: true description: The session ID, generated by the `requestToken` call. - example: 1234 + example: "1234" schema: type: string - in: query diff --git a/data/api/identity/v2_phone_associations.yaml b/data/api/identity/v2_phone_associations.yaml index f887be26..7f44fb3d 100644 --- a/data/api/identity/v2_phone_associations.yaml +++ b/data/api/identity/v2_phone_associations.yaml @@ -188,7 +188,7 @@ paths: name: sid required: true description: The session ID, generated by the `requestToken` call. - example: 1234 + example: "1234" schema: type: string - in: query diff --git a/data/api/identity/v2_terms.yaml b/data/api/identity/v2_terms.yaml index f4a45932..550d0bdb 100644 --- a/data/api/identity/v2_terms.yaml +++ b/data/api/identity/v2_terms.yaml @@ -131,7 +131,7 @@ paths: items: type: string description: The URLs the user is accepting in this request. - example: https://example.org/somewhere/terms-2.0-en.html + example: ["https://example.org/somewhere/terms-2.0-en.html"] required: - user_accepts responses: diff --git a/data/api/server-server/leaving-v2.yaml b/data/api/server-server/leaving-v2.yaml index 75248b53..b79ce008 100644 --- a/data/api/server-server/leaving-v2.yaml +++ b/data/api/server-server/leaving-v2.yaml @@ -109,7 +109,6 @@ paths: - depth - content example: { - "room_id": "!somewhere:example.org", "type": "m.room.member", "state_key": "@someone:example.org", "origin": "example.org", @@ -117,7 +116,8 @@ paths: "sender": "@someone:example.org", "content": { "membership": "leave" - } + }, + "depth": 0 } required: true responses: From 67c9f814e036d089fec9c9d4ecbe50edc1c0301e Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 4 Jul 2023 18:54:55 -0400 Subject: [PATCH 51/59] fix description of MAC calculation (#1590) --- .../newsfragments/1590.clarification | 1 + .../modules/end_to_end_encryption.md | 50 ++++++++++--------- 2 files changed, 28 insertions(+), 23 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1590.clarification diff --git a/changelogs/client_server/newsfragments/1590.clarification b/changelogs/client_server/newsfragments/1590.clarification new file mode 100644 index 00000000..1642357d --- /dev/null +++ b/changelogs/client_server/newsfragments/1590.clarification @@ -0,0 +1 @@ +Fix description of MAC calculation in SAS verification. \ No newline at end of file diff --git a/content/client-server-api/modules/end_to_end_encryption.md b/content/client-server-api/modules/end_to_end_encryption.md index d1efae40..d84bfb69 100644 --- a/content/client-server-api/modules/end_to_end_encryption.md +++ b/content/client-server-api/modules/end_to_end_encryption.md @@ -776,33 +776,37 @@ The method used to calculate these MACs depends upon the value of the message. All current implementations should use the `hkdf-hmac-sha256.v2` method which is defined as follows: -The MAC used is HMAC as defined in [RFC -5869](https://tools.ietf.org/html/rfc5869), using SHA-256 as the hash -function. The shared secret is supplied as the input keying material. No salt -is used, and in the info parameter is the concatenation of: +1. An HMAC key is generated using HKDF, as defined in [RFC + 5869](https://tools.ietf.org/html/rfc5869), using SHA-256 as the hash + function. The shared secret is supplied as the input keying material. No salt + is used, and in the info parameter is the concatenation of: -- The string `MATRIX_KEY_VERIFICATION_MAC`. -- The Matrix ID of the user whose key is being MAC-ed. -- The Device ID of the device sending the MAC. -- The Matrix ID of the other user. -- The Device ID of the device receiving the MAC. -- The `transaction_id` being used. -- The Key ID of the key being MAC-ed, or the string `KEY_IDS` if the - item being MAC-ed is the list of key IDs. + - The string `MATRIX_KEY_VERIFICATION_MAC`. + - The Matrix ID of the user whose key is being MAC-ed. + - The Device ID of the device sending the MAC. + - The Matrix ID of the other user. + - The Device ID of the device receiving the MAC. + - The `transaction_id` being used. + - The Key ID of the key being MAC-ed, or the string `KEY_IDS` if the + item being MAC-ed is the list of key IDs. -If a key is being MACed, the MAC is performed on the public key as encoded -according to the [key algorithm](#key-algorithms). For example, for `ed25519` -keys, it is the unpadded base64-encoded key. +2. A MAC is then generated using HMAC as defined in [RFC + 2104](https://tools.ietf.org/html/rfc2104) with the key generated above and + using SHA-256 as the hash function. -If the key list is being MACed, the list is sorted lexicographically and -comma-separated with no extra whitespace added, with each key written in the -form `{algorithm}:{keyId}`. For example, the key list could look like: -`ed25519:Cross+Signing+Key,ed25519:DEVICEID`. In this way, the recipient can -reconstruct the list from the names in the `mac` property of the -`m.key.verification.mac` message and ensure that no keys were added or removed. + If a key is being MACed, the MAC is performed on the public key as encoded + according to the [key algorithm](#key-algorithms). For example, for `ed25519` + keys, it is the unpadded base64-encoded key. -The MAC values are base64-encoded and sent in a -[`m.key.verification.mac`](#mkeyverificationmac) message. + If the key list is being MACed, the list is sorted lexicographically and + comma-separated with no extra whitespace added, with each key written in the + form `{algorithm}:{keyId}`. For example, the key list could look like: + `ed25519:Cross+Signing+Key,ed25519:DEVICEID`. In this way, the recipient can + reconstruct the list from the names in the `mac` property of the + `m.key.verification.mac` message and ensure that no keys were added or removed. + +3. The MAC values are base64-encoded and sent in a + [`m.key.verification.mac`](#mkeyverificationmac) message. {{% boxes/note %}} The MAC method `hkdf-hmac-sha256` used an incorrect base64 encoding, due to a From 14051847653383e432ebacae2cc430cc9ebce1e0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Wed, 5 Jul 2023 18:18:58 +0200 Subject: [PATCH 52/59] Fix schema of custom fields in query for appservice API (#1584) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Fix schema of custom fields in query for appservice API Signed-off-by: Kévin Commaille * Add changelog Signed-off-by: Kévin Commaille * Remove ellipses Signed-off-by: Kévin Commaille --------- Signed-off-by: Kévin Commaille --- .../newsfragments/1584.clarification | 1 + data/api/application-service/protocols.yaml | 12 ++++++++---- data/api/client-server/third_party_lookup.yaml | 6 ++++-- 3 files changed, 13 insertions(+), 6 deletions(-) create mode 100644 changelogs/application_service/newsfragments/1584.clarification diff --git a/changelogs/application_service/newsfragments/1584.clarification b/changelogs/application_service/newsfragments/1584.clarification new file mode 100644 index 00000000..098c1260 --- /dev/null +++ b/changelogs/application_service/newsfragments/1584.clarification @@ -0,0 +1 @@ +Fix JSON schema of custom fields in query. diff --git a/data/api/application-service/protocols.yaml b/data/api/application-service/protocols.yaml index 59dff5b0..dddd26d4 100644 --- a/data/api/application-service/protocols.yaml +++ b/data/api/application-service/protocols.yaml @@ -96,12 +96,14 @@ paths: schema: type: string - in: query - name: fields... + name: fields description: |- One or more custom fields that are passed to the application service to help identify the user. schema: - type: string + type: object + additionalProperties: + type: string responses: "200": description: The Matrix User IDs found with the given parameters. @@ -161,12 +163,14 @@ paths: schema: type: string - in: query - name: fields... + name: fields description: |- One or more custom fields that are passed to the application service to help identify the third-party location. schema: - type: string + type: object + additionalProperties: + type: string responses: "200": description: At least one portal room was found. diff --git a/data/api/client-server/third_party_lookup.yaml b/data/api/client-server/third_party_lookup.yaml index de1b0b63..797f065f 100644 --- a/data/api/client-server/third_party_lookup.yaml +++ b/data/api/client-server/third_party_lookup.yaml @@ -139,11 +139,13 @@ paths: schema: type: string - in: query - name: fields... + name: fields description: One or more custom fields that are passed to the AS to help identify the user. schema: - type: string + type: object + additionalProperties: + type: string responses: "200": description: The Matrix User IDs found with the given parameters. From 3ae6bb47d88d20fa7090df3e03314bddf0e266a4 Mon Sep 17 00:00:00 2001 From: Michael Telatynski <7t3chguy@gmail.com> Date: Wed, 12 Jul 2023 08:52:30 +0100 Subject: [PATCH 53/59] Update end_to_end_encryption.md (#1596) --- content/client-server-api/modules/end_to_end_encryption.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/client-server-api/modules/end_to_end_encryption.md b/content/client-server-api/modules/end_to_end_encryption.md index d84bfb69..f2f75705 100644 --- a/content/client-server-api/modules/end_to_end_encryption.md +++ b/content/client-server-api/modules/end_to_end_encryption.md @@ -305,7 +305,7 @@ properties. | key | JWK | **Required.** A [JSON Web Key](https://tools.ietf.org/html/rfc7517#appendix-A.3) object. | | iv | string | **Required.** The 128-bit unique counter block used by AES-CTR, encoded as unpadded base64. | | hashes | {string: string} | **Required.** A map from an algorithm name to a hash of the ciphertext, encoded as unpadded base64. Clients should support the SHA-256 hash, which uses the key `sha256`. | -| v | string | **Required.** Version of the encrypted attachments protocol. Must be `v2`. | +| v | string | **Required.** Version of the encrypted attachment's protocol. Must be `v2`. | `JWK` From 746524928cbcfa7e9051b6f7f9ea17bb6d16c04a Mon Sep 17 00:00:00 2001 From: Vladimir Panteleev Date: Wed, 12 Jul 2023 17:04:32 +0000 Subject: [PATCH 54/59] Fix grammar in client-server-api intro (#1597) --- changelogs/client_server/newsfragments/1597.clarification | 1 + content/client-server-api/_index.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 changelogs/client_server/newsfragments/1597.clarification diff --git a/changelogs/client_server/newsfragments/1597.clarification b/changelogs/client_server/newsfragments/1597.clarification new file mode 100644 index 00000000..3ccb2333 --- /dev/null +++ b/changelogs/client_server/newsfragments/1597.clarification @@ -0,0 +1 @@ +Fix various typos throughout the specification. diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 8ebe8f71..0e7e8473 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -62,7 +62,7 @@ error message e.g. `M_FORBIDDEN`. Error codes should have their namespace first in ALL CAPS, followed by a single `_`. For example, if there was a custom namespace `com.mydomain.here`, and a `FORBIDDEN` code, the error code should look like `COM.MYDOMAIN.HERE_FORBIDDEN`. Error codes defined by this -specification should start `M_`. +specification should start with `M_`. Some `errcode`s define additional keys which should be present in the error response object, but the keys `error` and `errcode` MUST always be present. From 50fe89d74b0c54896d1f3981698bf3407c3bc2dd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Tue, 18 Jul 2023 11:55:03 +0200 Subject: [PATCH 55/59] Fix definition of response of `POST /_matrix/federation/v1/user/keys/claim` (#1559) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- .../newsfragments/1559.clarification | 1 + data/api/server-server/user_keys.yaml | 38 ++++++++++--------- .../json-schema/resolve-additional-types.html | 15 ++++++++ .../partials/openapi/render-object-table.html | 4 +- 4 files changed, 38 insertions(+), 20 deletions(-) create mode 100644 changelogs/server_server/newsfragments/1559.clarification diff --git a/changelogs/server_server/newsfragments/1559.clarification b/changelogs/server_server/newsfragments/1559.clarification new file mode 100644 index 00000000..401a94e0 --- /dev/null +++ b/changelogs/server_server/newsfragments/1559.clarification @@ -0,0 +1 @@ +Fix definition of response of `POST /_matrix/federation/v1/user/keys/claim`. diff --git a/data/api/server-server/user_keys.yaml b/data/api/server-server/user_keys.yaml index 60995a74..fb598e94 100644 --- a/data/api/server-server/user_keys.yaml +++ b/data/api/server-server/user_keys.yaml @@ -71,26 +71,28 @@ paths: type: object # Key additionalProperties: - type: object - title: KeyObject - properties: - key: - type: string - description: The key, encoded using unpadded base64. - signatures: - type: object - title: Signatures - additionalProperties: - type: object - additionalProperties: + oneOf: + - type: string + - type: object + title: KeyObject + properties: + key: type: string - description: |- - Signature of the key object. + description: The key, encoded using unpadded base64. + signatures: + type: object + title: Signatures + additionalProperties: + 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: diff --git a/layouts/partials/json-schema/resolve-additional-types.html b/layouts/partials/json-schema/resolve-additional-types.html index 58710076..449b4222 100644 --- a/layouts/partials/json-schema/resolve-additional-types.html +++ b/layouts/partials/json-schema/resolve-additional-types.html @@ -91,6 +91,21 @@ {{ end }} {{ end }} +{{/* + Handle object schemas using the `oneOf` keyword + (https://json-schema.org/understanding-json-schema/reference/combining.html#oneof) +*/}} +{{ if $this_object.oneOf }} + {{ range $idx, $item := $this_object.oneOf }} + {{ $additional_objects = partial "get-additional-objects" (dict + "this_object" $item + "additional_objects" $additional_objects + "anchor_base" $anchor_base + "name" (printf "%s.oneOf[%d]" $name $idx) + ) }} + {{ end }} +{{ end }} + {{ return $additional_objects }} diff --git a/layouts/partials/openapi/render-object-table.html b/layouts/partials/openapi/render-object-table.html index 4fc5ac76..0f5841a4 100644 --- a/layouts/partials/openapi/render-object-table.html +++ b/layouts/partials/openapi/render-object-table.html @@ -36,7 +36,7 @@ {{ $property := partial "json-schema/resolve-allof" $property }} {{ $type := $property.type }} - {{ if eq $property.type "object" }} + {{ if or (eq $property.type "object") (and $property.oneOf (reflect.IsSlice .oneOf)) }} {{ $type = partial "type-or-title" $property }} {{ end }} @@ -121,7 +121,7 @@ {{ $types := slice }} {{ range .oneOf }} - {{ $types = $types | append .type }} + {{ $types = $types | append (partial "type-or-title" .) }} {{ end }} {{ $type = delimit $types "|" }} From 639caf057db22628b92f30152e9282f0cc795c18 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Tue, 18 Jul 2023 18:52:38 +0200 Subject: [PATCH 56/59] Fix rendered changelog with new version of towncrier (#1598) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- .../internal/newsfragments/1598.clarification | 1 + changelogs/pyproject.toml | 53 ++++++++++++++----- changelogs/template.md.jinja | 24 +++++++++ scripts/generate-changelog.sh | 11 +--- scripts/requirements.txt | 4 +- 5 files changed, 69 insertions(+), 24 deletions(-) create mode 100644 changelogs/internal/newsfragments/1598.clarification create mode 100644 changelogs/template.md.jinja diff --git a/changelogs/internal/newsfragments/1598.clarification b/changelogs/internal/newsfragments/1598.clarification new file mode 100644 index 00000000..1077e83c --- /dev/null +++ b/changelogs/internal/newsfragments/1598.clarification @@ -0,0 +1 @@ +Fix rendered changelog with new version of towncrier. diff --git a/changelogs/pyproject.toml b/changelogs/pyproject.toml index d32f6415..d42c96d6 100644 --- a/changelogs/pyproject.toml +++ b/changelogs/pyproject.toml @@ -1,39 +1,66 @@ [tool.towncrier] version = "unused" - filename = "../rendered.md" - issue_format = "[#{issue}](https://github.com/matrix-org/matrix-spec/issues/{issue})" - title_format = "### {name}" # Matches rendered spec, even if awkward - underlines = " " # 3 spaces intentionally to hide RST headings - - # Note: The names below have the tag built-in so the rendered spec *and* the generated - # changelog can benefit from sane headings. + filename = "rendered.md" + template = "template.md.jinja" [[tool.towncrier.type]] directory = "breaking" - name = "Breaking Changes" + name = "Breaking Changes" showcontent = true [[tool.towncrier.type]] directory = "deprecation" - name = "Deprecations" + name = "Deprecations" showcontent = true [[tool.towncrier.type]] directory = "new" - name = "New Endpoints" + name = "New Endpoints" showcontent = true [[tool.towncrier.type]] directory = "removal" - name = "Removed Endpoints" + name = "Removed Endpoints" showcontent = true [[tool.towncrier.type]] directory = "feature" - name = "Backwards Compatible Changes" + name = "Backwards Compatible Changes" showcontent = true [[tool.towncrier.type]] directory = "clarification" - name = "Spec Clarifications" + name = "Spec Clarifications" showcontent = true + + [[tool.towncrier.section]] + name = "Client-Server API" + path = "client_server" + + [[tool.towncrier.section]] + name = "Server-Server API" + path = "server_server" + + [[tool.towncrier.section]] + name = "Application Service API" + path = "application_service" + + [[tool.towncrier.section]] + name = "Identity Service API" + path = "identity_service" + + [[tool.towncrier.section]] + name = "Push Gateway API" + path = "push_gateway" + + [[tool.towncrier.section]] + name = "Room Versions" + path = "room_versions" + + [[tool.towncrier.section]] + name = "Appendices" + path = "appendices" + + [[tool.towncrier.section]] + name = "Internal Changes/Tooling" + path = "internal" diff --git a/changelogs/template.md.jinja b/changelogs/template.md.jinja new file mode 100644 index 00000000..38de4b92 --- /dev/null +++ b/changelogs/template.md.jinja @@ -0,0 +1,24 @@ +{% for section_name, section in sections.items() %} +{% if section_name %} + +### {{section_name}} +{% endif %} + +{% if section %} +{% for category, val in definitions.items() if category in section %} +**{{ definitions[category]['name'] }}** + +{% for content, issues in section[category].items() %} +- {{ content }} ( +{%- for issue in issues %} +[{{issue}}](https://github.com/matrix-org/matrix-spec/issues/{{issue|trim('#')}}){% if not loop.last %}, {% endif %} +{%- endfor %} +) +{% endfor %} + +{% endfor %} +{% else %} +No significant changes. + +{% endif %} +{% endfor %} diff --git a/scripts/generate-changelog.sh b/scripts/generate-changelog.sh index 73e59940..45132619 100755 --- a/scripts/generate-changelog.sh +++ b/scripts/generate-changelog.sh @@ -13,15 +13,8 @@ cd `dirname $0`/../changelogs # Pre-cleanup just in case it wasn't done on the last run rm -f rendered.md -# Reversed order so that room versions ends up on the bottom -towncrier --name "Internal Changes/Tooling" --dir "./internal" --config "./pyproject.toml" --yes -towncrier --name "Appendices" --dir "./appendices" --config "./pyproject.toml" --yes -towncrier --name "Room Versions" --dir "./room_versions" --config "./pyproject.toml" --yes -towncrier --name "Push Gateway API" --dir "./push_gateway" --config "./pyproject.toml" --yes -towncrier --name "Identity Service API" --dir "./identity_service" --config "./pyproject.toml" --yes -towncrier --name "Application Service API" --dir "./application_service" --config "./pyproject.toml" --yes -towncrier --name "Server-Server API" --dir "./server_server" --config "./pyproject.toml" --yes -towncrier --name "Client-Server API" --dir "./client_server" --config "./pyproject.toml" --yes +# Generate changelog +towncrier --yes { # Prepare the header diff --git a/scripts/requirements.txt b/scripts/requirements.txt index a3ff4f0b..0349d87f 100644 --- a/scripts/requirements.txt +++ b/scripts/requirements.txt @@ -2,8 +2,8 @@ # current at the time of writing # we need at least version 4.0.0 for support of JSON Schema Draft 2020-12. -jsonschema >= 4.0.0 +jsonschema == 4.17.3 PyYAML >= 3.12 requests >= 2.18.4 -towncrier == 21.9.0rc1 +towncrier == 23.6.0 From 4f39ad2a2420efa36f9654ce059ba1b153b5dd94 Mon Sep 17 00:00:00 2001 From: Martin Fischer Date: Wed, 19 Jul 2023 10:43:08 +0200 Subject: [PATCH 57/59] Add comment about Docsy fork to .gitmodules (#1600) --- .gitmodules | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.gitmodules b/.gitmodules index 5e606ab2..3760b077 100644 --- a/.gitmodules +++ b/.gitmodules @@ -1,4 +1,7 @@ [submodule "themes/docsy"] path = themes/docsy + # We use our own forked version of the Docsy theme, + # to avoid loading fonts from CDNs, which Docsy currently + # doesn't support (see https://github.com/google/docsy/issues/605). url = https://github.com/matrix-org/docsy.git branch = master From 1a11a7b9988347f7e3e9ff6a7330182c8b7ba73a Mon Sep 17 00:00:00 2001 From: Martin Fischer Date: Thu, 20 Jul 2023 09:23:16 +0200 Subject: [PATCH 58/59] Use auto table-layout on desktop (#1601) Signed-off-by: Martin Fischer --- assets/scss/custom.scss | 57 ++++++++++--------- .../internal/newsfragments/1601.clarification | 1 + 2 files changed, 32 insertions(+), 26 deletions(-) create mode 100644 changelogs/internal/newsfragments/1601.clarification diff --git a/assets/scss/custom.scss b/assets/scss/custom.scss index 047e57d7..c147b645 100644 --- a/assets/scss/custom.scss +++ b/assets/scss/custom.scss @@ -350,19 +350,37 @@ footer { } table { - /* Docsy makes all tables "responsive tables", which causes Bootstrap 4 to create - * tables with a "display" property of "block". - * - * However, for "table-layout: fixed" to be effective, an element must have a - * "display" property of "table". - * - * Thus, we override the "display" property here. This may no longer be necessary once - * Docsy updates to Bootstrap v5+: https://github.com/google/docsy/issues/470. - * For more details, see - * https://github.com/matrix-org/matrix-spec/pull/1295/files#r1010759688 */ - display: table; - table-layout: fixed; - width: 100%; + @media (max-width: 800px) { + /* Docsy by default applies `overflow-x: auto;` to tables, which + * results in annoying horizontal scrolling on mobile, so we instead + * switch to a fixed table layout on a narrow browser width. + * (On a wider width the default auto table-layout provides better readability.) + * + * Docsy makes all tables "responsive tables", which causes Bootstrap 4 to create + * tables with a "display" property of "block". + * However, for "table-layout: fixed" to be effective, an element must have a + * "display" property of "table". + * + * Thus, we override the "display" property here. This may no longer be necessary once + * Docsy updates to Bootstrap v5+: https://github.com/google/docsy/issues/470. + * For more details, see + * https://github.com/matrix-org/matrix-spec/pull/1295/files#r1010759688 */ + display: table; + table-layout: fixed; + width: 100%; + + .col-name, .col-type, .col-status { + width: 25%; + } + + .col-description { + width: 50%; + } + + .col-status-description { + width: 75%; + } + } // add some space between two tables when they are right next to each other & + table { @@ -409,19 +427,6 @@ footer { &.basic-info th { width: 15rem; } - - .col-name, .col-type, .col-status { - width: 25%; - } - - .col-description { - width: 50%; - } - - .col-status-description { - width: 75%; - } - } pre { diff --git a/changelogs/internal/newsfragments/1601.clarification b/changelogs/internal/newsfragments/1601.clarification new file mode 100644 index 00000000..1b9a529e --- /dev/null +++ b/changelogs/internal/newsfragments/1601.clarification @@ -0,0 +1 @@ +Improve the layout of tables on desktop displays. Contributed by @not-my-profile. From f5035b8e0271649816ab35dc12e9a5cc5e7783c3 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Thu, 20 Jul 2023 08:44:56 +0100 Subject: [PATCH 59/59] Fix up attribution Per request at https://github.com/matrix-org/matrix-spec/pull/1601#discussion_r1269035798 --- changelogs/internal/newsfragments/1601.clarification | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changelogs/internal/newsfragments/1601.clarification b/changelogs/internal/newsfragments/1601.clarification index 1b9a529e..7d3b9b12 100644 --- a/changelogs/internal/newsfragments/1601.clarification +++ b/changelogs/internal/newsfragments/1601.clarification @@ -1 +1 @@ -Improve the layout of tables on desktop displays. Contributed by @not-my-profile. +Improve the layout of tables on desktop displays. Contributed by Martin Fischer.