diff --git a/data/api/application-service/definitions/protocol.yaml b/data/api/application-service/definitions/protocol.yaml index 851091d6..b16eedfc 100644 --- a/data/api/application-service/definitions/protocol.yaml +++ b/data/api/application-service/definitions/protocol.yaml @@ -43,9 +43,9 @@ properties: field_types: title: Field Types description: |- - The type definitions for the fields defined in the ``user_fields`` and - ``location_fields``. Each entry in those arrays MUST have an entry here. The - ``string`` key for this object is field name itself. + The type definitions for the fields defined in the `user_fields` and + `location_fields`. Each entry in those arrays MUST have an entry here. The + `string` key for this object is field name itself. May be an empty object if no fields are defined. type: object @@ -101,7 +101,7 @@ properties: example: "mxc://example.org/JkLmNoPq" fields: type: object - description: Preset values for ``fields`` the client may use to search by. + description: Preset values for `fields` the client may use to search by. example: { "network": "freenode" } diff --git a/data/api/application-service/definitions/security.yaml b/data/api/application-service/definitions/security.yaml index bcfc69c0..6d7edd3a 100644 --- a/data/api/application-service/definitions/security.yaml +++ b/data/api/application-service/definitions/security.yaml @@ -13,6 +13,6 @@ # limitations under the License. homeserverAccessToken: type: apiKey - description: The ``hs_token`` provided by the application service's registration. + description: The `hs_token` provided by the application service's registration. name: access_token in: query diff --git a/data/api/application-service/query_room.yaml b/data/api/application-service/query_room.yaml index 2fbc87d1..6ddc6234 100644 --- a/data/api/application-service/query_room.yaml +++ b/data/api/application-service/query_room.yaml @@ -34,7 +34,7 @@ paths: description: |- This endpoint is invoked by the homeserver on an application service to query the existence of a given room alias. The homeserver will only query room - aliases inside the application service's ``aliases`` namespace. The + aliases inside the application service's `aliases` namespace. The homeserver will send this request when it receives a request to join a room alias within the application service's namespace. operationId: queryRoomByAlias diff --git a/data/api/application-service/query_user.yaml b/data/api/application-service/query_user.yaml index da363382..f8fc4ef1 100644 --- a/data/api/application-service/query_user.yaml +++ b/data/api/application-service/query_user.yaml @@ -34,7 +34,7 @@ paths: description: |- This endpoint is invoked by the homeserver on an application service to query the existence of a given user ID. The homeserver will only query user IDs - inside the application service's ``users`` namespace. The homeserver will + inside the application service's `users` namespace. The homeserver will send this request when it receives an event for an unknown user ID in the application service's namespace, such as a room invite. operationId: queryUserById diff --git a/data/api/application-service/transactions.yaml b/data/api/application-service/transactions.yaml index 20eace85..e4b62e01 100644 --- a/data/api/application-service/transactions.yaml +++ b/data/api/application-service/transactions.yaml @@ -34,7 +34,7 @@ paths: (or batch of events) to the application service. Note that the application service should distinguish state events - from message events via the presence of a ``state_key``, rather than + from message events via the presence of a `state_key`, rather than via the event type. operationId: sendTransaction security: diff --git a/data/api/client-server/account-data.yaml b/data/api/client-server/account-data.yaml index ae845b25..ec0d017f 100644 --- a/data/api/client-server/account-data.yaml +++ b/data/api/client-server/account-data.yaml @@ -33,7 +33,7 @@ paths: description: |- Set some account_data for the client. This config is only visible to the user that set the account_data. The config will be synced to clients in the - top-level ``account_data``. + top-level `account_data`. operationId: setAccountData security: - accessToken: [] @@ -110,7 +110,7 @@ paths: description: |- Set some account_data for the client on a given room. This config is only visible to the user that set the account_data. The config will be synced to - clients in the per-room ``account_data``. + clients in the per-room `account_data`. operationId: setAccountDataPerRoom security: - accessToken: [] diff --git a/data/api/client-server/administrative_contact.yaml b/data/api/client-server/administrative_contact.yaml index 61f9e8eb..8a709f54 100644 --- a/data/api/client-server/administrative_contact.yaml +++ b/data/api/client-server/administrative_contact.yaml @@ -93,13 +93,13 @@ paths: description: |- Adds contact information to the user's account. - This endpoint is deprecated in favour of the more specific ``/3pid/add`` - and ``/3pid/bind`` endpoints. + This endpoint is deprecated in favour of the more specific `/3pid/add` + and `/3pid/bind` endpoints. **Note:** - Previously this endpoint supported a ``bind`` parameter. This parameter - has been removed, making this endpoint behave as though it was ``false``. - This results in this endpoint being an equivalent to ``/3pid/bind`` rather + Previously this endpoint supported a `bind` parameter. This parameter + has been removed, making this endpoint behave as though it was `false`. + This results in this endpoint being an equivalent to `/3pid/bind` rather than dual-purpose. operationId: post3PIDs deprecated: true @@ -157,8 +157,8 @@ paths: 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 + 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. @@ -166,7 +166,7 @@ paths: 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). + in the `/versions` response (ie: r0.5.0). example: "https://example.org/path/to/submitToken" 403: description: The credentials could not be verified with the identity server. @@ -294,7 +294,7 @@ paths: Removes a third party identifier from the user's account. This might not cause an unbind of the identifier from the identity server. - Unlike other endpoints, this endpoint does not take an ``id_access_token`` + Unlike other endpoints, this endpoint does not take an `id_access_token` parameter because the homeserver is expected to sign the request to the identity server instead. operationId: delete3pidFromAccount @@ -311,9 +311,9 @@ paths: 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``. + 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 @@ -342,8 +342,8 @@ paths: - "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 - indentity server has unbound the identifier whereas ``no-support`` + the 3PID from the identity server. `success` indicates that the + indentity 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. @@ -359,7 +359,7 @@ paths: Removes a user's third party identifier from the provided identity server without removing it from the homeserver. - Unlike other endpoints, this endpoint does not take an ``id_access_token`` + Unlike other endpoints, this endpoint does not take an `id_access_token` parameter because the homeserver is expected to sign the request to the identity server instead. operationId: unbind3pidFromAccount @@ -376,9 +376,9 @@ paths: 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``. + 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 @@ -407,8 +407,8 @@ paths: - "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 + 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" @@ -456,7 +456,7 @@ paths: 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`` + 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: @@ -503,7 +503,7 @@ paths: 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`` + 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: diff --git a/data/api/client-server/appservice_room_directory.yaml b/data/api/client-server/appservice_room_directory.yaml index 63783cfd..ec0470c3 100644 --- a/data/api/client-server/appservice_room_directory.yaml +++ b/data/api/client-server/appservice_room_directory.yaml @@ -40,7 +40,7 @@ paths: This API is similar to the room directory visibility API used by clients to update the homeserver's more general room directory. - This API requires the use of an application service access token (``as_token``) + 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. operationId: updateAppserviceRoomDirectoryVsibility diff --git a/data/api/client-server/banning.yaml b/data/api/client-server/banning.yaml index 4e9a62ef..8b3cb80d 100644 --- a/data/api/client-server/banning.yaml +++ b/data/api/client-server/banning.yaml @@ -62,7 +62,7 @@ paths: reason: 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`_ event. + `reason` on the target's updated `m.room.member`_ event. required: ["user_id"] responses: 200: @@ -74,7 +74,7 @@ paths: type: object 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: + 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. @@ -121,7 +121,7 @@ paths: reason: type: string description: |- - Optional reason to be included as the ``reason`` on the subsequent + Optional reason to be included as the `reason` on the subsequent membership event. required: ["user_id"] responses: @@ -134,7 +134,7 @@ paths: type: object 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: + 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: diff --git a/data/api/client-server/content-repo.yaml b/data/api/client-server/content-repo.yaml index b827e8d2..220115b0 100644 --- a/data/api/client-server/content-repo.yaml +++ b/data/api/client-server/content-repo.yaml @@ -112,14 +112,14 @@ paths: x-example: matrix.org required: true description: | - The server name from the ``mxc://`` URI (the authoritory component) + The server name from the `mxc://` URI (the authoritory component) - in: path type: string name: mediaId x-example: ascERGshawAWawugaAcauga required: true description: | - The media ID from the ``mxc://`` URI (the path component) + The media ID from the `mxc://` URI (the path component) - in: query type: boolean name: allow_remote @@ -177,20 +177,20 @@ paths: x-example: matrix.org required: true description: | - The server name from the ``mxc://`` URI (the authoritory component) + The server name from the `mxc://` URI (the authoritory component) - in: path type: string name: mediaId x-example: ascERGshawAWawugaAcauga required: true description: | - The media ID from the ``mxc://`` URI (the path component) + The media ID from the `mxc://` URI (the path component) - in: path type: string name: fileName x-example: filename.jpg required: true - description: A filename to give in the ``Content-Disposition`` header. + description: A filename to give in the `Content-Disposition` header. - in: query type: boolean name: allow_remote @@ -210,7 +210,7 @@ paths: type: "string" Content-Disposition: description: |- - The ``fileName`` requested or the name of the file that was previously + The `fileName` requested or the name of the file that was previously uploaded, if set. type: "string" schema: @@ -248,14 +248,14 @@ paths: required: true x-example: example.org description: | - The server name from the ``mxc://`` URI (the authoritory component) + The server name from the `mxc://` URI (the authoritory component) - in: path type: string name: mediaId x-example: ascERGshawAWawugaAcauga required: true description: | - The media ID from the ``mxc://`` URI (the path component) + The media ID from the `mxc://` URI (the path component) - in: query type: integer x-example: 64 diff --git a/data/api/client-server/create_room.yaml b/data/api/client-server/create_room.yaml index 8b4cf9e9..0330d955 100644 --- a/data/api/client-server/create_room.yaml +++ b/data/api/client-server/create_room.yaml @@ -38,41 +38,41 @@ paths: the new room, including checking power levels for each event. It MUST apply the events implied by the request in the following order: - 1. The ``m.room.create`` event itself. Must be the first event in the + 1. The `m.room.create` event itself. Must be the first event in the room. - 2. An ``m.room.member`` event for the creator to join the room. This is + 2. An `m.room.member` event for the creator to join the room. This is needed so the remaining events can be sent. - 3. A default ``m.room.power_levels`` event, giving the room creator + 3. A default `m.room.power_levels` event, giving the room creator (and not other members) permission to send state events. Overridden - by the ``power_level_content_override`` parameter. + by the `power_level_content_override` parameter. - 4. Events set by the ``preset``. Currently these are the ``m.room.join_rules``, - ``m.room.history_visibility``, and ``m.room.guest_access`` state events. + 4. Events set by the `preset`. Currently these are the `m.room.join_rules`, + `m.room.history_visibility`, and `m.room.guest_access` state events. - 5. Events listed in ``initial_state``, in the order that they are + 5. Events listed in `initial_state`, in the order that they are listed. - 6. Events implied by ``name`` and ``topic`` (``m.room.name`` and ``m.room.topic`` + 6. Events implied by `name` and `topic` (`m.room.name` and `m.room.topic` state events). - 7. Invite events implied by ``invite`` and ``invite_3pid`` (``m.room.member`` with - ``membership: invite`` and ``m.room.third_party_invite``). + 7. Invite events implied by `invite` and `invite_3pid` (`m.room.member` with + `membership: invite` and `m.room.third_party_invite`). The available presets do the following with respect to room state: ======================== ============== ====================== ================ ========= - Preset ``join_rules`` ``history_visibility`` ``guest_access`` Other + Preset `join_rules` `history_visibility` `guest_access` Other ======================== ============== ====================== ================ ========= - ``private_chat`` ``invite`` ``shared`` ``can_join`` - ``trusted_private_chat`` ``invite`` ``shared`` ``can_join`` All invitees are given the same power level as the room creator. - ``public_chat`` ``public`` ``shared`` ``forbidden`` + `private_chat` `invite` `shared` `can_join` + `trusted_private_chat` `invite` `shared` `can_join` All invitees are given the same power level as the room creator. + `public_chat` `public` `shared` `forbidden` ======================== ============== ====================== ================ ========= - The server will create a ``m.room.create`` event in the room with the + The server will create a `m.room.create` event in the room with the requesting user as the creator, alongside other keys provided in the - ``creation_content``. + `creation_content`. operationId: createRoom security: - accessToken: [] @@ -97,12 +97,12 @@ paths: 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 + 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``. + `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: |- @@ -111,22 +111,22 @@ paths: 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``. + would be `#foo:example.com`. The complete room alias will become the canonical alias for the room. name: type: string description: |- - If this is included, an ``m.room.name`` event will be sent + 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``. + Events for more information on `m.room.name`. topic: type: string description: |- - If this is included, an ``m.room.topic`` event will be sent + 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``. + Events for more information on `m.room.topic`. invite: type: array description: |- @@ -155,7 +155,7 @@ paths: medium: type: string # TODO: Link to Identity Service spec when it eixsts - description: The kind of address being passed in the address field, for example ``email``. + description: The kind of address being passed in the address field, for example `email`. address: type: string description: The invitee's third party identifier. @@ -165,16 +165,16 @@ paths: 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 + 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 + Extra keys, such as `m.federate`, to be added to the content of the `m.room.create`_ event. The server will clobber the following - keys: ``creator``, ``room_version``. Future versions of the specification + keys: `creator`, `room_version`. Future versions of the specification may allow the server to clobber other keys. initial_state: type: array @@ -184,8 +184,8 @@ paths: room. The expected format of the state events are an object with type, state_key and content keys set. - Takes precedence over events set by ``preset``, but gets - overriden by ``name`` and ``topic`` keys. + Takes precedence over events set by `preset`, but gets + overriden by `name` and `topic` keys. items: type: object title: StateEvent @@ -207,16 +207,16 @@ paths: 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``. + 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`_ for more information. + 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`_ for more information. power_level_content_override: title: Power Level Event Content type: object @@ -244,24 +244,24 @@ paths: 400: description: |- - The request is invalid. A meaningful ``errcode`` and description + The request is invalid. A meaningful `errcode` and description error text will be returned. Example reasons for rejection include: - - The request body is malformed (``errcode`` set to ``M_BAD_JSON`` - or ``M_NOT_JSON``). + - The request body is malformed (`errcode` set to `M_BAD_JSON` + or `M_NOT_JSON`). - - The room alias specified is already taken (``errcode`` set to - ``M_ROOM_IN_USE``). + - The room alias specified is already taken (`errcode` set to + `M_ROOM_IN_USE`). - The initial state implied by the parameters to the request is - invalid: for example, the user's ``power_level`` is set below - that necessary to set the room name (``errcode`` set to - ``M_INVALID_ROOM_STATE``). + invalid: for example, the user's `power_level` is set below + that necessary to set the room name (`errcode` set to + `M_INVALID_ROOM_STATE`). - The homeserver doesn't support the requested room version, or one or more users being invited to the new room are residents of a homeserver which does not support the requested room version. - The ``errcode`` will be ``M_UNSUPPORTED_ROOM_VERSION`` in these + The `errcode` will be `M_UNSUPPORTED_ROOM_VERSION` in these cases. schema: "$ref": "definitions/errors/error.yaml" diff --git a/data/api/client-server/cross_signing.yaml b/data/api/client-server/cross_signing.yaml index f1a0cc41..981262c6 100644 --- a/data/api/client-server/cross_signing.yaml +++ b/data/api/client-server/cross_signing.yaml @@ -110,9 +110,9 @@ paths: The input was invalid in some way. This can include one of the following error codes: - * ``M_INVALID_SIGNATURE``: For example, the self-signing or + * `M_INVALID_SIGNATURE`: For example, the self-signing or user-signing key had an incorrect signature. - * ``M_MISSING_PARAM``: No master key is available. + * `M_MISSING_PARAM`: No master key is available. schema: type: object example: { @@ -207,8 +207,8 @@ paths: 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``. + that failed. If a signature was invalid, the `errcode` will + be set to `M_INVALID_SIGNATURE`. additionalProperties: type: object additionalProperties: diff --git a/data/api/client-server/definitions/cross_signing_key.yaml b/data/api/client-server/definitions/cross_signing_key.yaml index aa8dea2e..d445d93d 100644 --- a/data/api/client-server/definitions/cross_signing_key.yaml +++ b/data/api/client-server/definitions/cross_signing_key.yaml @@ -33,7 +33,7 @@ properties: type: string description: |- The public key. The object must have exactly one property, whose name is - in the form ``:``, and whose value + in the form `:`, and whose value is the unpadded base64 public key. example: "ed25519:alice+base64+public+key": "alice+base64+public+key" diff --git a/data/api/client-server/definitions/device_keys.yaml b/data/api/client-server/definitions/device_keys.yaml index 4f7cffe7..f24dedd7 100644 --- a/data/api/client-server/definitions/device_keys.yaml +++ b/data/api/client-server/definitions/device_keys.yaml @@ -38,7 +38,7 @@ properties: type: object description: |- Public identity keys. The names of the properties should be in the - format ``:``. The keys themselves should be + format `:`. The keys themselves should be encoded as specified by the key algorithm. additionalProperties: type: string @@ -50,7 +50,7 @@ properties: title: Signatures description: |- Signatures for the device key object. A map from user ID, to a map from - ``:`` to the signature. + `:` to the signature. The signature is calculated using the process described at `Signing JSON`_. diff --git a/data/api/client-server/definitions/event.yaml b/data/api/client-server/definitions/event.yaml index 7d5808b1..54af96f5 100644 --- a/data/api/client-server/definitions/event.yaml +++ b/data/api/client-server/definitions/event.yaml @@ -44,8 +44,8 @@ properties: format: int64 type: integer prev_content: - description: Optional. The previous ``content`` for this state. This will - be present only for state events appearing in the ``timeline``. If this + description: Optional. The previous `content` for this state. This will + be present only for state events appearing in the `timeline`. If this is not a state event, or there is no previous content, this key will be missing. title: EventContent diff --git a/data/api/client-server/definitions/event_filter.yaml b/data/api/client-server/definitions/event_filter.yaml index 8c96917f..b6888693 100644 --- a/data/api/client-server/definitions/event_filter.yaml +++ b/data/api/client-server/definitions/event_filter.yaml @@ -19,14 +19,14 @@ properties: not_senders: description: A list of sender IDs to exclude. If this list is absent then no senders are excluded. A matching sender will be excluded even if it is listed in the - ``'senders'`` filter. + `'senders'` filter. items: type: string type: array not_types: description: A list of event types to exclude. If this list is absent then no event types are excluded. A matching type will be excluded even if it is listed - in the ``'types'`` filter. A '*' can be used as a wildcard to match any sequence + in the `'types'` filter. A '*' can be used as a wildcard to match any sequence of characters. items: type: string @@ -39,7 +39,7 @@ properties: type: array types: description: A list of event types to include. If this list is absent then all - event types are included. A ``'*'`` can be used as a wildcard to match any sequence + event types are included. A `'*'` can be used as a wildcard to match any sequence of characters. items: type: string diff --git a/data/api/client-server/definitions/openid_token.yaml b/data/api/client-server/definitions/openid_token.yaml index b50fcd54..32929ef6 100644 --- a/data/api/client-server/definitions/openid_token.yaml +++ b/data/api/client-server/definitions/openid_token.yaml @@ -19,10 +19,10 @@ properties: description: |- An access token the consumer may use to verify the identity of the person who generated the token. This is given to the federation - API ``GET /openid/userinfo`` to verify the user's identity. + API `GET /openid/userinfo` to verify the user's identity. token_type: type: string - description: The string ``Bearer``. + description: The string `Bearer`. matrix_server_name: type: string description: |- diff --git a/data/api/client-server/definitions/push_condition.yaml b/data/api/client-server/definitions/push_condition.yaml index 8752274e..a97786ff 100644 --- a/data/api/client-server/definitions/push_condition.yaml +++ b/data/api/client-server/definitions/push_condition.yaml @@ -23,25 +23,25 @@ properties: key: type: string description: |- - Required for ``event_match`` conditions. The dot-separated field of the + Required for `event_match` conditions. The dot-separated field of the event to match. - Required for ``sender_notification_permission`` conditions. The field in + Required for `sender_notification_permission` conditions. The field in 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``. + must be specified under the `notifications` property in the power level + event's `content`. x-example: content.body pattern: type: string description: |- - Required for ``event_match`` conditions. The glob-style pattern to + Required for `event_match` conditions. The glob-style pattern to match against. Patterns with no special glob characters should be treated as having asterisks prepended and appended when testing the condition. is: type: string description: |- - Required for ``room_member_count`` conditions. A decimal integer + Required for `room_member_count` conditions. A decimal integer optionally prefixed by one of, ==, <, >, >= or <=. A prefix of < matches rooms where the member count is strictly less than the given number and so forth. If no prefix is present, this parameter defaults to ==. diff --git a/data/api/client-server/definitions/push_rule.yaml b/data/api/client-server/definitions/push_rule.yaml index 14a9b7d4..06efad74 100644 --- a/data/api/client-server/definitions/push_rule.yaml +++ b/data/api/client-server/definitions/push_rule.yaml @@ -43,11 +43,11 @@ properties: 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. + applicable to `underride` and `override` rules. pattern: type: string description: |- - The glob-style pattern to match against. Only applicable to ``content`` + The glob-style pattern to match against. Only applicable to `content` rules. required: - actions diff --git a/data/api/client-server/definitions/request_email_validation.yaml b/data/api/client-server/definitions/request_email_validation.yaml index d24c42b5..d52ea18e 100644 --- a/data/api/client-server/definitions/request_email_validation.yaml +++ b/data/api/client-server/definitions/request_email_validation.yaml @@ -24,7 +24,7 @@ allOf: 3PID verification. This parameter is deprecated with a plan to be removed in a future specification - version for ``/account/password`` and ``/register`` requests. + version for `/account/password` and `/register` requests. example: "id.example.com" id_access_token: type: string @@ -33,4 +33,4 @@ allOf: can treat this as optional to distinguish between r0.5-compatible clients and this specification version. - Required if an ``id_server`` is supplied. + Required if an `id_server` is supplied. diff --git a/data/api/client-server/definitions/request_msisdn_validation.yaml b/data/api/client-server/definitions/request_msisdn_validation.yaml index 54897e63..fba3a615 100644 --- a/data/api/client-server/definitions/request_msisdn_validation.yaml +++ b/data/api/client-server/definitions/request_msisdn_validation.yaml @@ -24,7 +24,7 @@ allOf: 3PID verification. This parameter is deprecated with a plan to be removed in a future specification - version for ``/account/password`` and ``/register`` requests. + version for `/account/password` and `/register` requests. example: "id.example.com" id_access_token: type: string @@ -33,4 +33,4 @@ allOf: can treat this as optional to distinguish between r0.5-compatible clients and this specification version. - Required if an ``id_server`` is supplied. + Required if an `id_server` is supplied. diff --git a/data/api/client-server/definitions/request_token_response.yaml b/data/api/client-server/definitions/request_token_response.yaml index 45201a20..b801af98 100644 --- a/data/api/client-server/definitions/request_token_response.yaml +++ b/data/api/client-server/definitions/request_token_response.yaml @@ -17,7 +17,7 @@ properties: type: string description: |- The session ID. Session IDs are opaque strings that must consist entirely - of the characters ``[0-9a-zA-Z.=_-]``. Their length must not exceed 255 + of the characters `[0-9a-zA-Z.=_-]`. Their length must not exceed 255 characters and they must not be empty. example: "123abc" submit_url: @@ -25,13 +25,13 @@ properties: 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 + 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 + advertises this specification version in the `/versions` response (ie: r0.5.0). example: "https://example.org/path/to/submitToken" required: ['sid'] diff --git a/data/api/client-server/definitions/room_event_filter.yaml b/data/api/client-server/definitions/room_event_filter.yaml index 880cb173..2c4fddc6 100644 --- a/data/api/client-server/definitions/room_event_filter.yaml +++ b/data/api/client-server/definitions/room_event_filter.yaml @@ -19,20 +19,20 @@ allOf: lazy_load_members: type: boolean description: |- - If ``true``, enables lazy-loading of membership events. See + If `true`, enables lazy-loading of membership events. See `Lazy-loading room members <#lazy-loading-room-members>`_ - for more information. Defaults to ``false``. + for more information. Defaults to `false`. include_redundant_members: type: boolean description: |- - If ``true``, sends all membership events for all events, even if they have already + If `true`, sends all membership events for all events, even if they have already been sent to the client. Does not - apply unless ``lazy_load_members`` is ``true``. See + apply unless `lazy_load_members` is `true`. See `Lazy-loading room members <#lazy-loading-room-members>`_ - for more information. Defaults to ``false``. + for more information. Defaults to `false`. not_rooms: description: A list of room IDs to exclude. If this list is absent then no rooms - are excluded. A matching room will be excluded even if it is listed in the ``'rooms'`` + are excluded. A matching room will be excluded even if it is listed in the `'rooms'` filter. items: type: string @@ -45,5 +45,5 @@ allOf: type: array contains_url: type: boolean - description: If ``true``, includes only events with a ``url`` key in their content. If - ``false``, excludes those events. If omitted, ``url`` key is not considered for filtering. + description: If `true`, includes only events with a `url` key in their content. If + `false`, excludes those events. If omitted, `url` key is not considered for filtering. diff --git a/data/api/client-server/definitions/security.yaml b/data/api/client-server/definitions/security.yaml index bb78f0e3..963e1d43 100644 --- a/data/api/client-server/definitions/security.yaml +++ b/data/api/client-server/definitions/security.yaml @@ -13,6 +13,6 @@ # limitations under the License. accessToken: type: apiKey - description: The access_token returned by a call to ``/login`` or ``/register`` + description: The access_token returned by a call to `/login` or `/register` name: access_token in: query diff --git a/data/api/client-server/definitions/sync_filter.yaml b/data/api/client-server/definitions/sync_filter.yaml index fc37fb48..0b4a8dca 100644 --- a/data/api/client-server/definitions/sync_filter.yaml +++ b/data/api/client-server/definitions/sync_filter.yaml @@ -46,16 +46,16 @@ properties: properties: not_rooms: description: A list of room IDs to exclude. If this list is absent then no rooms - are excluded. A matching room will be excluded even if it is listed in the ``'rooms'`` - filter. This filter is applied before the filters in ``ephemeral``, - ``state``, ``timeline`` or ``account_data`` + are excluded. A matching room will be excluded even if it is listed in the `'rooms'` + filter. This filter is applied before the filters in `ephemeral`, + `state`, `timeline` or `account_data` items: type: string type: array rooms: description: A list of room IDs to include. If this list is absent then all rooms - are included. This filter is applied before the filters in ``ephemeral``, - ``state``, ``timeline`` or ``account_data`` + are included. This filter is applied before the filters in `ephemeral`, + `state`, `timeline` or `account_data` items: type: string type: array diff --git a/data/api/client-server/definitions/third_party_signed.yaml b/data/api/client-server/definitions/third_party_signed.yaml index 7ce1a1d1..4af422b4 100644 --- a/data/api/client-server/definitions/third_party_signed.yaml +++ b/data/api/client-server/definitions/third_party_signed.yaml @@ -14,7 +14,7 @@ type: object title: Third Party Signed description: |- - A signature of an ``m.third_party_invite`` token to prove that this user + A signature of an `m.third_party_invite` token to prove that this user owns a third party identity which has been invited to the room. properties: sender: diff --git a/data/api/client-server/definitions/timeline_batch.yaml b/data/api/client-server/definitions/timeline_batch.yaml index abf93830..e243b485 100644 --- a/data/api/client-server/definitions/timeline_batch.yaml +++ b/data/api/client-server/definitions/timeline_batch.yaml @@ -16,11 +16,11 @@ allOf: - $ref: room_event_batch.yaml properties: limited: - description: True if the number of events returned was limited by the ``limit`` + description: True if the number of events returned was limited by the `limit` on the filter. type: boolean prev_batch: - description: A token that can be supplied to the ``from`` parameter of the + description: A token that can be supplied to the `from` parameter of the rooms/{roomId}/messages endpoint. type: string type: object diff --git a/data/api/client-server/directory.yaml b/data/api/client-server/directory.yaml index f470c730..1b01242d 100644 --- a/data/api/client-server/directory.yaml +++ b/data/api/client-server/directory.yaml @@ -133,11 +133,11 @@ paths: room aliases can only be deleted by their creator or a server administrator. **Note:** - Servers may choose to update the ``alt_aliases`` for the ``m.room.canonical_alias`` + Servers may choose to update the `alt_aliases` for the `m.room.canonical_alias` state event in the room when an alias is removed. Servers which choose to update the 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. + have permission to update the `m.room.canonical_alias` event. operationId: deleteRoomAlias security: @@ -176,8 +176,8 @@ paths: given room. This endpoint can be called by users who are in the room (external - users receive an ``M_FORBIDDEN`` error response). If the room's - ``m.room.history_visibility`` maps to ``world_readable``, any + users receive an `M_FORBIDDEN` error response). If the room's + `m.room.history_visibility` maps to `world_readable`, any user can call this endpoint. Servers may choose to implement additional access control checks here, @@ -186,7 +186,7 @@ paths: **Note:** 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`` + as they are not curated, unlike those listed in the `m.room.canonical_alias` state event. operationId: getLocalAliases diff --git a/data/api/client-server/event_context.yaml b/data/api/client-server/event_context.yaml index da43bf9e..872356e4 100644 --- a/data/api/client-server/event_context.yaml +++ b/data/api/client-server/event_context.yaml @@ -63,10 +63,10 @@ paths: 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 - ``state``. It is not applied to the ``event`` itself. The filter may - be applied before or/and after the ``limit`` parameter - whichever the + A JSON `RoomEventFilter` to filter the returned events with. The + filter is only applied to `events_before`, `events_after`, and + `state`. It is not applied to the `event` itself. The filter may + be applied before or/and after the `limit` parameter - whichever the homeserver prefers. See `Filtering <#filtering>`_ for more information. diff --git a/data/api/client-server/filter.yaml b/data/api/client-server/filter.yaml index bf9396e2..0a12e2bb 100644 --- a/data/api/client-server/filter.yaml +++ b/data/api/client-server/filter.yaml @@ -88,7 +88,7 @@ paths: type: string description: |- The ID of the filter that was created. Cannot start - with a ``{`` as this character is used to determine + 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" diff --git a/data/api/client-server/inviting.yaml b/data/api/client-server/inviting.yaml index ae352d9d..5df5b4de 100644 --- a/data/api/client-server/inviting.yaml +++ b/data/api/client-server/inviting.yaml @@ -48,7 +48,7 @@ paths: join that room. If the user was invited to the room, the homeserver will append a - ``m.room.member`` event to the room. + `m.room.member` event to the room. .. _third party invites section: `invite-by-third-party-id-endpoint`_ operationId: inviteUser @@ -77,7 +77,7 @@ paths: reason: type: string description: |- - Optional reason to be included as the ``reason`` on the subsequent + Optional reason to be included as the `reason` on the subsequent membership event. required: ["user_id"] responses: @@ -91,20 +91,20 @@ paths: 400: description: |- - The request is invalid. A meaningful ``errcode`` and description + The request is invalid. A meaningful `errcode` and description error text will be returned. Example reasons for rejection include: - - The request body is malformed (``errcode`` set to ``M_BAD_JSON`` - or ``M_NOT_JSON``). + - The request body is malformed (`errcode` set to `M_BAD_JSON` + or `M_NOT_JSON`). - 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. + `errcode` will be `M_UNSUPPORTED_ROOM_VERSION` in these cases. 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: + 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: - The invitee has been banned from the room. - The invitee is already a member of the room. diff --git a/data/api/client-server/joining.yaml b/data/api/client-server/joining.yaml index 3cd3d6b5..0f18a571 100644 --- a/data/api/client-server/joining.yaml +++ b/data/api/client-server/joining.yaml @@ -32,7 +32,7 @@ paths: summary: Start the requesting user participating in a particular room. description: |- *Note that this API requires a room ID, not alias.* - ``/join/{roomIdOrAlias}`` *exists if you have a room alias.* + `/join/{roomIdOrAlias}` *exists if you have a room alias.* This API starts a user participating in a particular room, if that user is allowed to participate in that room. After this call, the client is @@ -62,12 +62,12 @@ paths: - $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 + `m.room.third_party_invite` event in the room, and perform key validity checking if required by the event. reason: type: string description: |- - Optional reason to be included as the ``reason`` on the subsequent + Optional reason to be included as the `reason` on the subsequent membership event. example: "Looking for support" responses: @@ -75,7 +75,7 @@ paths: description: |- The room has been joined. - The joined room ID must be returned in the ``room_id`` field. + The joined room ID must be returned in the `room_id` field. examples: application/json: { "room_id": "!d41d8cd:matrix.org"} @@ -88,7 +88,7 @@ paths: required: ["room_id"] 403: description: |- - You do not have permission to join the room. A meaningful ``errcode`` + You do not have permission to join the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejection are: - The room is invite-only and the user was not invited. @@ -108,7 +108,7 @@ paths: post: summary: Start the requesting user participating in a particular room. description: |- - *Note that this API takes either a room ID or alias, unlike* ``/room/{roomId}/join``. + *Note that this API takes either a room ID or alias, unlike* `/room/{roomId}/join`. This API starts a user participating in a particular room, if that user is allowed to participate in that room. After this call, the client is @@ -146,13 +146,13 @@ paths: 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 + 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: type: string description: |- - Optional reason to be included as the ``reason`` on the subsequent + Optional reason to be included as the `reason` on the subsequent membership event. example: "Looking for support" responses: @@ -160,7 +160,7 @@ paths: description: |- The room has been joined. - The joined room ID must be returned in the ``room_id`` field. + The joined room ID must be returned in the `room_id` field. examples: application/json: { "room_id": "!d41d8cd:matrix.org"} @@ -173,7 +173,7 @@ paths: required: ["room_id"] 403: description: |- - You do not have permission to join the room. A meaningful ``errcode`` + You do not have permission to join the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejection are: - The room is invite-only and the user was not invited. diff --git a/data/api/client-server/key_backup.yaml b/data/api/client-server/key_backup.yaml index 682372d7..ba3ec85f 100644 --- a/data/api/client-server/key_backup.yaml +++ b/data/api/client-server/key_backup.yaml @@ -124,7 +124,7 @@ paths: etag: description: |- An opaque string representing stored keys in the backup. - Clients can compare it with the ``etag`` value they received + 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 @@ -168,7 +168,7 @@ paths: type: string name: version description: |- - The backup version to get, as returned in the ``version`` parameter + The backup version to get, as returned in the `version` parameter of the response in `POST /_matrix/client/r0/room_keys/version`_ or this endpoint. required: true @@ -206,7 +206,7 @@ paths: etag: description: |- An opaque string representing stored keys in the backup. - Clients can compare it with the ``etag`` value they received + 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 @@ -240,7 +240,7 @@ paths: put: summary: Update information about an existing backup. description: |- - Update information about an existing backup. Only ``auth_data`` can be modified. + Update information about an existing backup. Only `auth_data` can be modified. operationId: putRoomKeysVersion security: - accessToken: [] @@ -249,7 +249,7 @@ paths: type: string name: version description: |- - The backup version to update, as returned in the ``version`` + The backup version to update, as returned in the `version` parameter in the response of `POST /_matrix/client/r0/room_keys/version`_ or `GET /_matrix/client/r0/room_keys/version/{version}`_. @@ -300,9 +300,9 @@ paths: properties: {} 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. + 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", @@ -338,7 +338,7 @@ paths: type: string name: version description: |- - The backup version to delete, as returned in the ``version`` + The backup version to delete, as returned in the `version` parameter in the response of `POST /_matrix/client/r0/room_keys/version`_ or `GET /_matrix/client/r0/room_keys/version/{version}`_. @@ -412,7 +412,7 @@ paths: etag: description: |- The new etag value representing stored keys in the backup. - See ``GET /room_keys/version/{version}`` for more details. + See `GET /room_keys/version/{version}` for more details. type: string example: "abcdefg" count: @@ -425,7 +425,7 @@ paths: 403: description: |- The version specified does not match the current backup version. - The current version will be included in the ``current_version`` + The current version will be included in the `current_version` field. examples: application/json: { @@ -522,7 +522,7 @@ paths: etag: description: |- The new etag value representing stored keys in the backup. - See ``GET /room_keys/version/{version}`` for more details. + See `GET /room_keys/version/{version}` for more details. type: string example: "abcdefg" count: @@ -583,7 +583,7 @@ paths: etag: description: |- The new etag value representing stored keys in the backup. - See ``GET /room_keys/version/{version}`` for more details. + See `GET /room_keys/version/{version}` for more details. type: string example: "abcdefg" count: @@ -596,7 +596,7 @@ paths: 403: description: |- The version specified does not match the current backup version. - The current version will be included in the ``current_version`` + The current version will be included in the `current_version` field. examples: application/json: { @@ -647,7 +647,7 @@ paths: 200: description: |- The key data. If no keys are found, then an object with an empty - ``sessions`` property will be returned (``{"sessions": {}}``). + `sessions` property will be returned (`{"sessions": {}}`). schema: type: object $ref: "definitions/room_key_backup.yaml" @@ -695,7 +695,7 @@ paths: etag: description: |- The new etag value representing stored keys in the backup. - See ``GET /room_keys/version/{version}`` for more details. + See `GET /room_keys/version/{version}` for more details. type: string example: "abcdefg" count: @@ -776,7 +776,7 @@ paths: etag: description: |- The new etag value representing stored keys in the backup. - See ``GET /room_keys/version/{version}`` for more details. + See `GET /room_keys/version/{version}` for more details. type: string example: "abcdefg" count: @@ -789,7 +789,7 @@ paths: 403: description: |- The version specified does not match the current backup version. - The current version will be included in the ``current_version`` + The current version will be included in the `current_version` field. examples: application/json: { @@ -834,7 +834,7 @@ paths: 200: description: |- The key data. If no keys are found, then an object with an empty - ``rooms`` property will be returned (``{"rooms": {}}``). + `rooms` property will be returned (`{"rooms": {}}`). schema: type: object properties: @@ -898,7 +898,7 @@ paths: etag: description: |- The new etag value representing stored keys in the backup. - See ``GET /room_keys/version/{version}`` for more details. + See `GET /room_keys/version/{version}` for more details. type: string example: "abcdefg" count: diff --git a/data/api/client-server/keys.yaml b/data/api/client-server/keys.yaml index 5c1e5ffb..b3a8b219 100644 --- a/data/api/client-server/keys.yaml +++ b/data/api/client-server/keys.yaml @@ -57,7 +57,7 @@ paths: 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 + `:`. The format of the key is determined by the `key algorithm <#key-algorithms>`_. May be absent if no new one-time keys are required. @@ -184,7 +184,7 @@ paths: 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. + user or device is missing from the `device_keys` result. additionalProperties: type: object example: {} @@ -194,7 +194,7 @@ paths: 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`` + `/keys/upload`, with the addition of an `unsigned` property. additionalProperties: type: object @@ -243,8 +243,8 @@ paths: 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 + `/keys/device_signing/upload`, along with the signatures + uploaded via `/keys/signatures/upload` that the requesting user is allowed to see. additionalProperties: allOf: @@ -264,7 +264,7 @@ paths: 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``. + `/keys/device_signing/upload`. additionalProperties: allOf: - $ref: definitions/cross_signing_key.yaml @@ -289,7 +289,7 @@ paths: 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``. + `/keys/device_signing/upload`. additionalProperties: allOf: - $ref: definitions/cross_signing_key.yaml @@ -364,7 +364,7 @@ paths: 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. + user or device is missing from the `one_time_keys` result. additionalProperties: type: object example: {} @@ -372,7 +372,7 @@ paths: 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. + map from devices to a map from `:` to the key object. See the `key algorithms <#key-algorithms>`_ section for information on the Key Object format. @@ -425,9 +425,9 @@ paths: The server should include in the results any users who: * currently share a room with the calling user (ie, both users have - membership state ``join``); *and* + membership state `join`); *and* * added new device identity keys or removed an existing device with - identity keys, between ``from`` and ``to``. + identity keys, between `from` and `to`. operationId: getKeysChanges security: - accessToken: [] @@ -436,7 +436,7 @@ paths: name: from type: string description: |- - The desired start point of the list. Should be the ``next_batch`` field + The desired start point of the list. Should be the `next_batch` field from a response to an earlier call to |/sync|. Users who have not uploaded new device identity keys since this point, nor deleted existing devices with identity keys since then, will be excluded @@ -447,7 +447,7 @@ paths: name: to type: string description: |- - The desired end point of the list. Should be the ``next_batch`` + The desired end point of the list. Should be the `next_batch` field from a recent call to |/sync| - typically the most recent such call. This may be used by the server as a hint to check its caches are up to date. diff --git a/data/api/client-server/kicking.yaml b/data/api/client-server/kicking.yaml index fd3f1698..728406fe 100644 --- a/data/api/client-server/kicking.yaml +++ b/data/api/client-server/kicking.yaml @@ -34,10 +34,10 @@ paths: Kick a user from the room. The caller must have the required power level in order to perform this operation. - - Kicking a user adjusts the target member's membership state to be ``leave`` with an - optional ``reason``. Like with other membership changes, a user can directly adjust - the target member's state by making a request to ``/rooms//state/m.room.member/``. + + Kicking a user adjusts the target member's membership state to be `leave` with an + optional `reason`. Like with other membership changes, a user can directly adjust + the target member's state by making a request to `/rooms//state/m.room.member/`. operationId: kick security: - accessToken: [] @@ -64,8 +64,8 @@ paths: 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`_ event. + The reason the user has been kicked. This will be supplied as the + `reason` on the target's updated `m.room.member`_ event. required: ["user_id"] responses: 200: @@ -77,7 +77,7 @@ paths: type: object 403: description: |- - You do not have permission to kick the user from the room. A meaningful ``errcode`` and + 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: - The kicker is not currently in the room. diff --git a/data/api/client-server/leaving.yaml b/data/api/client-server/leaving.yaml index 56b2b8c8..f3d3b486 100644 --- a/data/api/client-server/leaving.yaml +++ b/data/api/client-server/leaving.yaml @@ -64,7 +64,7 @@ paths: reason: type: string description: |- - Optional reason to be included as the ``reason`` on the subsequent + Optional reason to be included as the `reason` on the subsequent membership event. responses: 200: diff --git a/data/api/client-server/list_joined_rooms.yaml b/data/api/client-server/list_joined_rooms.yaml index 19ad8649..b34f3d5d 100644 --- a/data/api/client-server/list_joined_rooms.yaml +++ b/data/api/client-server/list_joined_rooms.yaml @@ -45,7 +45,7 @@ paths: joined_rooms: type: array description: |- - The ID of each room in which the user has ``joined`` membership. + The ID of each room in which the user has `joined` membership. items: type: string examples: diff --git a/data/api/client-server/list_public_rooms.yaml b/data/api/client-server/list_public_rooms.yaml index 222b412a..4175b0a9 100644 --- a/data/api/client-server/list_public_rooms.yaml +++ b/data/api/client-server/list_public_rooms.yaml @@ -48,7 +48,7 @@ paths: type: string enum: ['private', 'public'] description: The visibility of the room in the directory. - examples: + examples: application/json: { "visibility": "public" } @@ -68,7 +68,7 @@ paths: directory. Servers may choose to implement additional access control checks - here, for instance that room visibility can only be changed by + here, for instance that room visibility can only be changed by the room creator or a server administrator. operationId: setRoomVisibilityOnDirectory security: @@ -92,7 +92,7 @@ paths: type: string enum: ["private", "public"] description: |- - The new visibility setting for the room. + The new visibility setting for the room. Defaults to 'public'. example: { "visibility": "public" @@ -100,7 +100,7 @@ paths: responses: 200: description: The visibility was updated, or no change was needed. - examples: + examples: application/json: {} 404: description: The room is not known to the server @@ -204,10 +204,10 @@ paths: type: string description: |- The specific third party network/protocol to request from the - homeserver. Can only be used if ``include_all_networks`` is false. + homeserver. Can only be used if `include_all_networks` is false. example: "irc" example: { - "limit": 10, + "limit": 10, "filter": { "generic_search_term": "foo" }, diff --git a/data/api/client-server/login.yaml b/data/api/client-server/login.yaml index 557f2075..b68094c6 100644 --- a/data/api/client-server/login.yaml +++ b/data/api/client-server/login.yaml @@ -33,7 +33,7 @@ paths: summary: Get the supported login types to authenticate users description: |- Gets the homeserver's supported login types to authenticate users. Clients - should pick one of these and supply it as the ``type`` when logging in. + should pick one of these and supply it as the `type` when logging in. operationId: getLoginFlows responses: 200: @@ -56,7 +56,7 @@ paths: properties: type: description: |- - The login type. This is supplied as the ``type`` when + The login type. This is supplied as the `type` when logging in. type: string 429: @@ -71,10 +71,10 @@ paths: Authenticates the user, and issues an access token they can use to authorize themself in subsequent requests. - If the client does not supply a ``device_id``, the server must + If the client does not supply a `device_id`, the server must auto-generate one. - The returned access token must be associated with the ``device_id`` + The returned access token must be associated with the `device_id` supplied by the client or generated by the server. The server may invalidate any access token previously associated with that device. See `Relationship between access tokens and devices`_. @@ -103,22 +103,22 @@ paths: "$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``. + 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``. + 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``. + 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 + 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. + Required when `type` is `m.login.token`. Part of `Token-based`_ login. device_id: type: string description: |- @@ -131,7 +131,7 @@ paths: type: string description: |- A display name to assign to the newly-created device. Ignored - if ``device_id`` corresponds to a known device. + if `device_id` corresponds to a known device. required: ["type"] responses: @@ -169,8 +169,8 @@ paths: 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. + `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: |- @@ -197,10 +197,10 @@ paths: 403: description: |- The login attempt failed. This can include one of the following error codes: - * ``M_FORBIDDEN``: The provided authentication data was incorrect + * `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. + * `M_USER_DEACTIVATED`: The user has been deactivated. examples: application/json: { "errcode": "M_FORBIDDEN" diff --git a/data/api/client-server/message_pagination.yaml b/data/api/client-server/message_pagination.yaml index 66e1d9c2..5e5a99c2 100644 --- a/data/api/client-server/message_pagination.yaml +++ b/data/api/client-server/message_pagination.yaml @@ -51,8 +51,8 @@ paths: name: from description: |- The token to start returning events from. This token can be obtained - from a ``prev_batch`` token returned for each room by the sync API, - or from a ``start`` or ``end`` token returned by a previous request + from a `prev_batch` token returned for each room by the sync API, + or from a `start` or `end` token returned by a previous request to this endpoint. required: true x-example: "s345_678_333" @@ -61,8 +61,8 @@ paths: name: to description: |- The token to stop returning events at. This token can be obtained from - a ``prev_batch`` token returned for each room by the sync endpoint, - or from a ``start`` or ``end`` token returned by a previous request to + a `prev_batch` token returned for each room by the sync endpoint, + or from a `start` or `end` token returned by a previous request to this endpoint. required: false - in: query @@ -96,30 +96,30 @@ paths: start: type: string description: |- - The token the pagination starts from. If ``dir=b`` this will be - the token supplied in ``from``. + The token the pagination starts from. If `dir=b` this will be + the token supplied in `from`. end: type: string description: |- - The token the pagination ends at. If ``dir=b`` this token should + The token the pagination ends at. If `dir=b` this token should be used again to request even earlier events. 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, so that events start - at the ``from`` point. + 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, so that events start + at the `from` point. items: "$ref": "../../event-schemas/schema/core-event-schema/room_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``. + 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 + 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. diff --git a/data/api/client-server/notifications.yaml b/data/api/client-server/notifications.yaml index 434b3be2..86f17a13 100644 --- a/data/api/client-server/notifications.yaml +++ b/data/api/client-server/notifications.yaml @@ -54,7 +54,7 @@ paths: name: only type: string description: |- - Allows basic filtering of events returned. Supply ``highlight`` + Allows basic filtering of events returned. Supply `highlight` to return only events where the notification had the highlight tweak set. required: false @@ -87,8 +87,8 @@ paths: next_token: type: string description: |- - The token to supply in the ``from`` param of the next - ``/notifications`` request in order to request more + 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 diff --git a/data/api/client-server/old_sync.yaml b/data/api/client-server/old_sync.yaml index 7caad40e..6c65c1b0 100644 --- a/data/api/client-server/old_sync.yaml +++ b/data/api/client-server/old_sync.yaml @@ -32,10 +32,10 @@ paths: summary: Listen on the event stream. description: |- This will listen for new events and return them to the caller. This will - block until an event is received, or until the ``timeout`` is reached. + block until an event is received, or until the `timeout` is reached. This endpoint was deprecated in r0 of this specification. Clients - should instead call the |/sync|_ API with a ``since`` parameter. See + should instead call the |/sync|_ API with a `since` parameter. See the `migration guide `_. operationId: getEvents @@ -73,13 +73,13 @@ paths: start: type: string description: |- - A token which correlates to the first value in ``chunk``. This - is usually the same token supplied to ``from=``. + 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``. + 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." @@ -89,7 +89,7 @@ paths: allOf: - "$ref": "../../event-schemas/schema/core-event-schema/room_event.yaml" 400: - description: "Bad pagination ``from`` parameter." + description: "Bad pagination `from` parameter." tags: - Room participation deprecated: true @@ -101,7 +101,7 @@ paths: number of messages per room to return. This endpoint was deprecated in r0 of this specification. Clients - should instead call the |/sync|_ API with no ``since`` parameter. See + should instead call the |/sync|_ API with no `since` parameter. See the `migration guide `_. operationId: initialSync @@ -118,10 +118,10 @@ paths: type: boolean name: archived description: |- - Whether to include rooms that the user has left. If ``false`` then + Whether to include rooms that the user has left. If `false` then only rooms that the user has been invited to or has joined are - included. If set to ``true`` then rooms that the user has left are - included as well. By default this is ``false``. + 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: @@ -199,8 +199,8 @@ paths: end: type: string description: |- - A token which correlates to the last value in ``chunk``. This - token should be used with the ``/events`` API to listen for new + A token which correlates to the last value in `chunk`. This + token should be used with the `/events` API to listen for new events. presence: type: array @@ -226,7 +226,7 @@ paths: invite: type: object title: "InviteEvent" - description: "The invite event if ``membership`` is ``invite``" + description: "The invite event if `membership` is `invite`" allOf: - "$ref": "../../event-schemas/schema/m.room.member.yaml" messages: @@ -237,12 +237,12 @@ paths: start: type: string description: |- - A token which correlates to the first value in ``chunk``. + A token which correlates to the first value in `chunk`. Used for pagination. end: type: string description: |- - A token which correlates to the last value in ``chunk``. + A token which correlates to the last value in `chunk`. Used for pagination. chunk: type: array @@ -251,7 +251,7 @@ paths: list of the most recent messages for this room. If the user has left the room this will be the messages that preceeded them leaving. This array - will consist of at most ``limit`` elements. + will consist of at most `limit` elements. items: type: object title: RoomEvent @@ -274,7 +274,7 @@ paths: type: string enum: ["private", "public"] description: |- - Whether this room is visible to the ``/publicRooms`` API + Whether this room is visible to the `/publicRooms` API or not." account_data: type: array @@ -306,7 +306,7 @@ paths: get: summary: Get a single event by event ID. description: |- - Get a single event based on ``event_id``. You must have permission to + Get a single event based on `event_id`. You must have permission to retrieve this event e.g. by being a member in the room for this event. This endpoint was deprecated in r0 of this specification. Clients diff --git a/data/api/client-server/openid.yaml b/data/api/client-server/openid.yaml index 98a2449e..ec6f8818 100644 --- a/data/api/client-server/openid.yaml +++ b/data/api/client-server/openid.yaml @@ -37,7 +37,7 @@ paths: OpenID. The access token generated is only valid for the OpenID API. It cannot - be used to request another OpenID access token or call ``/sync``, for + be used to request another OpenID access token or call `/sync`, for example. operationId: requestOpenIdToken security: @@ -63,7 +63,7 @@ paths: description: |- OpenID token information. This response is nearly compatible with the response documented in the `OpenID Connect 1.0 Specification `_ - with the only difference being the lack of an ``id_token``. Instead, + with the only difference being the lack of an `id_token`. Instead, the Matrix homeserver's name is provided. examples: application/json: { diff --git a/data/api/client-server/peeking_events.yaml b/data/api/client-server/peeking_events.yaml index 462b0191..85eb8768 100644 --- a/data/api/client-server/peeking_events.yaml +++ b/data/api/client-server/peeking_events.yaml @@ -33,12 +33,12 @@ paths: description: |- This will listen for new events related to a particular room and return them to the caller. This will block until an event is received, or until - the ``timeout`` is reached. + the `timeout` is reached. - This API is the same as the normal ``/events`` endpoint, but can be + This API is the same as the normal `/events` endpoint, but can be called by users who have not joined the room. - Note that the normal ``/events`` endpoint has been deprecated. This + Note that the normal `/events` endpoint has been deprecated. This API will also be deprecated at some point, but its replacement is not yet known. operationId: peekEvents @@ -86,13 +86,13 @@ paths: start: type: string description: |- - A token which correlates to the first value in ``chunk``. This - is usually the same token supplied to ``from=``. + 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``. + 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." @@ -102,5 +102,5 @@ paths: allOf: - "$ref": "../../event-schemas/schema/core-event-schema/room_event.yaml" 400: - description: "Bad pagination ``from`` parameter." + description: "Bad pagination `from` parameter." # No tags to exclude this from the swagger UI - use the normal version instead. diff --git a/data/api/client-server/presence.yaml b/data/api/client-server/presence.yaml index b3a8bb02..003de8ca 100644 --- a/data/api/client-server/presence.yaml +++ b/data/api/client-server/presence.yaml @@ -33,7 +33,7 @@ paths: description: |- This API sets the given user's presence state. When setting the status, the activity time is updated to reflect that activity; the client does - not need to specify the ``last_active_ago`` field. You cannot set the + not need to specify the `last_active_ago` field. You cannot set the presence state of another user. operationId: setPresence security: diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml index db998e6c..6a8d6a77 100644 --- a/data/api/client-server/profile.yaml +++ b/data/api/client-server/profile.yaml @@ -32,7 +32,7 @@ paths: summary: Set the user's display name. description: |- This API sets the given user's display name. You must have permission to - set this user's display name, e.g. you need to have their ``access_token``. + set this user's display name, e.g. you need to have their `access_token`. operationId: setDisplayName security: - accessToken: [] @@ -106,7 +106,7 @@ paths: summary: Set the user's avatar URL. description: |- This API sets the given user's avatar URL. You must have permission to - set this user's avatar URL, e.g. you need to have their ``access_token``. + set this user's avatar URL, e.g. you need to have their `access_token`. operationId: setAvatarUrl security: - accessToken: [] @@ -182,7 +182,7 @@ paths: Get the combined profile information for this user. This API may be used to fetch the user's own profile information or other users; either locally or on remote homeservers. This API may return keys which are not - limited to ``displayname`` or ``avatar_url``. + limited to `displayname` or `avatar_url`. operationId: getUserProfile parameters: - in: path diff --git a/data/api/client-server/pusher.yaml b/data/api/client-server/pusher.yaml index d232baf9..e274c3b3 100644 --- a/data/api/client-server/pusher.yaml +++ b/data/api/client-server/pusher.yaml @@ -71,13 +71,13 @@ paths: pushkey: type: string description: |- - This is a unique identifier for this pusher. See ``/set`` for + 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 + The kind of pusher. `"http"` is a pusher that sends HTTP pokes. app_id: type: string @@ -114,7 +114,7 @@ paths: url: type: string description: |- - Required if ``kind`` is ``http``. The URL to use to send + Required if `kind` is `http`. The URL to use to send notifications to. format: type: string @@ -173,14 +173,14 @@ paths: client has no such concept, use any unique identifier. Max length, 512 bytes. - If the ``kind`` is ``"email"``, this is the email address to + If the `kind` is `"email"`, this is the email address to send notifications to. kind: type: string 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. + 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: |- @@ -189,7 +189,7 @@ paths: different platform versions get different app identifiers. Max length, 64 chars. - If the ``kind`` is ``"email"``, this is ``"m.email"``. + If the `kind` is `"email"`, this is `"m.email"`. app_display_name: type: string description: |- @@ -214,22 +214,22 @@ paths: type: object description: |- A dictionary of information for the pusher implementation - itself. If ``kind`` is ``http``, this should contain ``url`` + 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 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``. + 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 + `kind` is `http`. The details about what fields the homeserver should send to the push gateway are defined in the `Push Gateway Specification`_. Currently the only format available is 'event_id_only'. @@ -240,7 +240,7 @@ paths: 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``. + users. The default is `false`. required: ['kind', 'app_id', 'app_display_name', 'device_display_name', 'pushkey', 'lang', 'data'] responses: diff --git a/data/api/client-server/pushrules.yaml b/data/api/client-server/pushrules.yaml index bd0c80b8..9a595271 100644 --- a/data/api/client-server/pushrules.yaml +++ b/data/api/client-server/pushrules.yaml @@ -32,9 +32,9 @@ paths: summary: Retrieve all push rulesets. description: |- Retrieve all push rulesets for this user. Clients can "drill-down" on - the rulesets by suffixing a ``scope`` to this path e.g. - ``/pushrules/global/``. This will return a subset of this data under the - specified key e.g. the ``global`` key. + the rulesets by suffixing a `scope` to this path e.g. + `/pushrules/global/`. This will return a subset of this data under the + specified key e.g. the `global` key. operationId: getPushRules security: - accessToken: [] @@ -263,7 +263,7 @@ paths: required: true x-example: "global" description: |- - ``global`` to specify global rules. + `global` to specify global rules. - in: path type: string name: kind @@ -283,7 +283,7 @@ paths: 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. + rule itself such as the rule's `actions` and `conditions` if set. examples: application/json: { "actions": [ @@ -326,7 +326,7 @@ paths: required: true x-example: "global" description: |- - ``global`` to specify global rules. + `global` to specify global rules. - in: path type: string name: kind @@ -380,7 +380,7 @@ paths: required: true x-example: "global" description: |- - ``global`` to specify global rules. + `global` to specify global rules. - in: path type: string name: kind @@ -402,7 +402,7 @@ paths: required: false x-example: someRuleId description: |- - Use 'before' with a ``rule_id`` as its value to make the new rule the + 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. - in: query @@ -418,7 +418,7 @@ paths: name: pushrule description: |- The push rule data. Additional top-level keys may be present depending - on the parameters for the rule ``kind``. + on the parameters for the rule `kind`. required: true schema: type: object @@ -440,14 +440,14 @@ paths: 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. + 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. + Only applicable to `content` rules. The glob-style pattern to match against. required: ["actions"] responses: 200: @@ -497,8 +497,8 @@ paths: required: true x-example: "global" description: |- - Either ``global`` or ``device/`` to specify global - rules or device rules for the given ``profile_tag``. + Either `global` or `device/` to specify global + rules or device rules for the given `profile_tag`. - in: path type: string name: kind @@ -554,7 +554,7 @@ paths: required: true x-example: "global" description: |- - ``global`` to specify global rules. + `global` to specify global rules. - in: path type: string name: kind @@ -620,8 +620,8 @@ paths: required: true x-example: "global" description: |- - Either ``global`` or ``device/`` to specify global - rules or device rules for the given ``profile_tag``. + Either `global` or `device/` to specify global + rules or device rules for the given `profile_tag`. - in: path type: string name: kind @@ -685,7 +685,7 @@ paths: required: true x-example: "global" description: |- - ``global`` to specify global rules. + `global` to specify global rules. - in: path type: string name: kind diff --git a/data/api/client-server/read_markers.yaml b/data/api/client-server/read_markers.yaml index 4f5d43ce..aa9d0ecb 100644 --- a/data/api/client-server/read_markers.yaml +++ b/data/api/client-server/read_markers.yaml @@ -60,7 +60,7 @@ paths: type: string description: |- The event ID to set the read receipt location at. This is - equivalent to calling ``/receipt/m.read/$elsewhere:example.org`` + equivalent to calling `/receipt/m.read/$elsewhere:example.org` and is provided here to save that extra call. example: "$elsewhere:example.org" required: ['m.fully_read'] diff --git a/data/api/client-server/receipts.yaml b/data/api/client-server/receipts.yaml index a3e9789e..716946ac 100644 --- a/data/api/client-server/receipts.yaml +++ b/data/api/client-server/receipts.yaml @@ -59,8 +59,8 @@ paths: - in: body name: receipt description: |- - Extra receipt information to attach to ``content`` if any. The - server will automatically set the ``ts`` field. + Extra receipt information to attach to `content` if any. The + server will automatically set the `ts` field. schema: type: object example: { diff --git a/data/api/client-server/redaction.yaml b/data/api/client-server/redaction.yaml index 1dbdf76e..aeef07a5 100644 --- a/data/api/client-server/redaction.yaml +++ b/data/api/client-server/redaction.yaml @@ -36,9 +36,9 @@ paths: This cannot be undone. - Any user with a power level greater than or equal to the ``m.room.redaction`` + Any user with a power level greater than or equal to the `m.room.redaction` event power level may send redaction events in the room. If the user's power - level greater is also greater than or equal to the ``redact`` power level + level greater is also greater than or equal to the `redact` power level of the room, the user may redact events sent by other users. Server administrators may redact events sent by users on their server. diff --git a/data/api/client-server/registration.yaml b/data/api/client-server/registration.yaml index 69316b8f..26203320 100644 --- a/data/api/client-server/registration.yaml +++ b/data/api/client-server/registration.yaml @@ -43,27 +43,27 @@ paths: If registration is successful, this endpoint will issue an access token the client can use to authorize itself in subsequent requests. - If the client does not supply a ``device_id``, the server must + If the client does not supply a `device_id`, the server must auto-generate one. The server SHOULD register an account with a User ID based on the - ``username`` provided, if any. Note that the grammar of Matrix User ID + `username` provided, if any. Note that the grammar of Matrix User ID localparts is restricted, so the server MUST either map the provided - ``username`` onto a ``user_id`` in a logical manner, or reject - ``username``\s which do not comply to the grammar, with - ``M_INVALID_USERNAME``. + `username` onto a `user_id` in a logical manner, or reject + `username`\s which do not comply to the grammar, with + `M_INVALID_USERNAME`. Matrix clients MUST NOT assume that localpart of the registered - ``user_id`` matches the provided ``username``. + `user_id` matches the provided `username`. - The returned access token must be associated with the ``device_id`` + The returned access token must be associated with the `device_id` supplied by the client or generated by the server. The server may invalidate any access token previously associated with that device. See `Relationship between access tokens and devices`_. When registering a guest account, all parameters in the request body - with the exception of ``initial_device_display_name`` MUST BE ignored - by the server. The server MUST pick a ``device_id`` for the account + with the exception of `initial_device_display_name` MUST BE ignored + by the server. The server MUST pick a `device_id` for the account regardless of input. Any user ID returned by this API must conform to the grammar given in the @@ -81,7 +81,7 @@ paths: enum: - guest - user - description: The kind of account to register. Defaults to ``user``. + description: The kind of account to register. Defaults to `user`. - in: body name: body required: true @@ -94,7 +94,7 @@ paths: 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. + authenticate the `register` call itself. allOf: - "$ref": "definitions/auth_data.yaml" username: @@ -118,12 +118,12 @@ paths: type: string description: |- A display name to assign to the newly-created device. Ignored - if ``device_id`` corresponds to a known device. + 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 + 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 @@ -151,7 +151,7 @@ paths: 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. + Required if the `inhibit_login` option is false. home_server: type: string description: |- @@ -159,22 +159,22 @@ paths: 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. + `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 if the `inhibit_login` option is false. required: ['user_id'] 400: description: |- Part of the request was invalid. This may include one of the following error codes: - * ``M_USER_IN_USE`` : The desired user ID is already taken. - * ``M_INVALID_USERNAME`` : The desired user ID is not a valid user name. - * ``M_EXCLUSIVE`` : The desired user ID is in the exclusive namespace + * `M_USER_IN_USE` : The desired user ID is already taken. + * `M_INVALID_USERNAME` : The desired user ID is not a valid user name. + * `M_EXCLUSIVE` : The desired user ID is in the exclusive namespace claimed by an application service. These errors may be returned at any stage of the registration process, @@ -200,7 +200,7 @@ paths: 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 + 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: { @@ -251,12 +251,12 @@ paths: description: |- Part of the request was invalid. This may include one of the following error codes: - * ``M_THREEPID_IN_USE`` : The email address is already registered to an account on this server. + * `M_THREEPID_IN_USE` : The email address is already registered to an account on this server. However, if the homeserver has the ability to send email, it is recommended that the server instead send an email to the user with instructions on how to reset their password. This prevents malicious parties from being able to determine if a given email address has an account on the homeserver in question. - * ``M_SERVER_NOT_TRUSTED`` : The ``id_server`` parameter refers to an identity server + * `M_SERVER_NOT_TRUSTED` : The `id_server` parameter refers to an identity server that is not trusted by this homeserver. examples: application/json: { @@ -301,12 +301,12 @@ paths: description: |- Part of the request was invalid. This may include one of the following error codes: - * ``M_THREEPID_IN_USE`` : The phone number is already registered to an account on this server. + * `M_THREEPID_IN_USE` : The phone number is already registered to an account on this server. However, if the homeserver has the ability to send SMS message, it is recommended that the server instead send an SMS message to the user with instructions on how to reset their password. This prevents malicious parties from being able to determine if a given phone number has an account on the homeserver in question. - * ``M_SERVER_NOT_TRUSTED`` : The ``id_server`` parameter refers to an identity server + * `M_SERVER_NOT_TRUSTED` : The `id_server` parameter refers to an identity server that is not trusted by this homeserver. examples: application/json: { @@ -352,7 +352,7 @@ paths: 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 <#soft-logout>`_ + When `false`, the server can still take advantage of `the soft logout method <#soft-logout>`_ for the user's remaining devices. example: true auth: @@ -386,20 +386,20 @@ paths: The homeserver must check that the given email address **is associated** with an account on this homeserver. This API should be used to request validation tokens when authenticating for the - ``/account/password`` endpoint. + `/account/password` endpoint. This API's parameters and response are identical to that of the |/register/email/requestToken|_ endpoint, except that - ``M_THREEPID_NOT_FOUND`` may be returned if no account matching the + `M_THREEPID_NOT_FOUND` may be returned if no account matching the given email address could be found. The server may instead send an email to the given address prompting the user to create an account. - ``M_THREEPID_IN_USE`` may not be returned. + `M_THREEPID_IN_USE` may not be returned. The homeserver should validate the email itself, either by sending a validation email itself or by using a service it has control over. - .. |/register/email/requestToken| replace:: ``/register/email/requestToken`` + .. |/register/email/requestToken| replace:: `/register/email/requestToken` .. _/register/email/requestToken: #post-matrix-client-%CLIENT_MAJOR_VERSION%-register-email-requesttoken operationId: requestTokenToResetPasswordEmail @@ -428,7 +428,7 @@ paths: 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`` + 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: @@ -445,19 +445,19 @@ paths: The homeserver must check that the given phone number **is associated** with an account on this homeserver. This API should be used to request validation tokens when authenticating for the - ``/account/password`` endpoint. + `/account/password` endpoint. This API's parameters and response are identical to that of the |/register/msisdn/requestToken|_ endpoint, except that - ``M_THREEPID_NOT_FOUND`` may be returned if no account matching the + `M_THREEPID_NOT_FOUND` may be returned if no account matching the given phone number could be found. The server may instead send the SMS to the given phone number prompting the user to create an account. - ``M_THREEPID_IN_USE`` may not be returned. + `M_THREEPID_IN_USE` may not be returned. The homeserver should validate the phone number itself, either by sending a validation message itself or by using a service it has control over. - .. |/register/msisdn/requestToken| replace:: ``/register/msisdn/requestToken`` + .. |/register/msisdn/requestToken| replace:: `/register/msisdn/requestToken` .. _/register/msisdn/requestToken: #post-matrix-client-%CLIENT_MAJOR_VERSION%-register-email-requesttoken operationId: requestTokenToResetPasswordMSISDN @@ -486,7 +486,7 @@ paths: 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`` + 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: @@ -511,7 +511,7 @@ paths: The homeserver may change the flows available depending on whether a valid access token is provided. - Unlike other endpoints, this endpoint does not take an ``id_access_token`` + Unlike other endpoints, this endpoint does not take an `id_access_token` parameter because the homeserver is expected to sign the request to the identity server instead. security: @@ -533,11 +533,11 @@ paths: 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`` + 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``. + homeserver does not know which `id_server` that was, + it must return an `id_server_unbind_result` of + `no-support`. example: "example.org" responses: 200: @@ -552,12 +552,12 @@ paths: - "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 + 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 + `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 + must be `success` if the homeserver has no identifiers to unbind for the user. example: "success" required: @@ -612,15 +612,15 @@ paths: type: boolean description: |- A flag to indicate that the username is available. This should always - be ``true`` when the server replies with 200 OK. + be `true` when the server replies with 200 OK. 400: description: |- Part of the request was invalid or the username is not available. This may include one of the following error codes: - * ``M_USER_IN_USE`` : The desired username is already taken. - * ``M_INVALID_USERNAME`` : The desired username is not a valid user name. - * ``M_EXCLUSIVE`` : The desired username is in the exclusive namespace + * `M_USER_IN_USE` : The desired username is already taken. + * `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: { diff --git a/data/api/client-server/room_initial_sync.yaml b/data/api/client-server/room_initial_sync.yaml index fd8412a4..48f3176c 100644 --- a/data/api/client-server/room_initial_sync.yaml +++ b/data/api/client-server/room_initial_sync.yaml @@ -98,12 +98,12 @@ paths: start: type: string description: |- - A token which correlates to the first value in ``chunk``. + A token which correlates to the first value in `chunk`. Used for pagination. end: type: string description: |- - A token which correlates to the last value in ``chunk``. + A token which correlates to the last value in `chunk`. Used for pagination. chunk: type: array @@ -112,7 +112,7 @@ paths: list of the most recent messages for this room. If the user has left the room this will be the messages that preceeded them leaving. This array - will consist of at most ``limit`` elements. + will consist of at most `limit` elements. items: type: object title: RoomEvent @@ -135,7 +135,7 @@ paths: type: string enum: ["private", "public"] description: |- - Whether this room is visible to the ``/publicRooms`` API + Whether this room is visible to the `/publicRooms` API or not." account_data: type: array diff --git a/data/api/client-server/room_state.yaml b/data/api/client-server/room_state.yaml index 20b9c1fd..2b6fffd4 100644 --- a/data/api/client-server/room_state.yaml +++ b/data/api/client-server/room_state.yaml @@ -35,18 +35,18 @@ paths: .. _`put-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-state-eventtype`: State events can be sent using this endpoint. These events will be - overwritten if ````, ```` and ```` all + overwritten if ``, `` and `` all match. Requests to this endpoint **cannot use transaction IDs** - like other ``PUT`` paths because they cannot be differentiated from the - ``state_key``. Furthermore, ``POST`` is unsupported on state paths. + like other `PUT` paths because they cannot be differentiated from the + `state_key`. Furthermore, `POST` is unsupported on state paths. The body of the request should be the content object of the event; the fields in this object will vary depending on the type of event. See - `Room Events`_ for the ``m.`` event specification. + `Room Events`_ for the `m.` event specification. - If the event type being sent is ``m.room.canonical_alias`` servers + If the event type being sent is `m.room.canonical_alias` servers SHOULD ensure that any new aliases being listed in the event are valid per their grammar/syntax and that they point to the room ID where the state event is to be sent. Servers do not validate aliases which are @@ -116,10 +116,10 @@ paths: Some example error codes include: - * ``M_INVALID_PARAMETER``: One or more aliases within the ``m.room.canonical_alias`` + * `M_INVALID_PARAMETER`: One or more aliases within the `m.room.canonical_alias` event have invalid syntax. - * ``M_BAD_ALIAS``: One or more aliases within the ``m.room.canonical_alias`` event + * `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" diff --git a/data/api/client-server/rooms.yaml b/data/api/client-server/rooms.yaml index 7ead7f41..3d4aed93 100644 --- a/data/api/client-server/rooms.yaml +++ b/data/api/client-server/rooms.yaml @@ -31,7 +31,7 @@ paths: get: summary: Get a single event by event ID. description: |- - Get a single event based on ``roomId/eventId``. You must have permission to + Get a single event based on `roomId/eventId`. You must have permission to retrieve this event e.g. by being a member in the room for this event. operationId: getOneRoomEvent security: @@ -196,7 +196,7 @@ paths: 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 + 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" @@ -213,9 +213,9 @@ paths: - ban description: |- The kind of membership to filter for. Defaults to no filtering if - unspecified. When specified alongside ``not_membership``, the two + 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``. + the same as `membership` **or** *is not* the same as `not_membership`. x-example: "join" - in: query name: not_membership @@ -267,7 +267,7 @@ paths: 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. + 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 diff --git a/data/api/client-server/search.yaml b/data/api/client-server/search.yaml index 6647f955..33d946b0 100644 --- a/data/api/client-server/search.yaml +++ b/data/api/client-server/search.yaml @@ -41,7 +41,7 @@ paths: 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. + `next_batch` result from a previous call to this endpoint. x-example: "YWxsCgpOb25lLDM1ODcwOA" - in: body name: body @@ -104,7 +104,7 @@ paths: enum: ["recent", "rank"] description: |- The order in which to search for results. - By default, this is ``"rank"``. + By default, this is `"rank"`. event_context: title: Include Event Context type: object @@ -117,13 +117,13 @@ paths: title: "Before limit" description: |- How many events before the result are - returned. By default, this is ``5``. + 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``. + returned. By default, this is `5`. include_profile: type: boolean title: "Return profile information" @@ -131,7 +131,7 @@ paths: Requests that the server returns the historic profile information for the users that sent the events that were returned. - By default, this is ``false``. + By default, this is `false`. include_state: type: boolean title: Include current state @@ -231,7 +231,7 @@ paths: The historic profile information of the users that sent the events returned. - The ``string`` key is the user ID for which + The `string` key is the user ID for which the profile belongs to. additionalProperties: type: object @@ -265,10 +265,10 @@ paths: 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``. + `include_state` key set with a value of `true`. - The ``string`` key is the room ID for which the ``State - Event`` array belongs to. + The `string` key is the room ID for which the `State + Event` array belongs to. additionalProperties: type: array title: Room State @@ -281,8 +281,8 @@ paths: 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: + 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 diff --git a/data/api/client-server/sync.yaml b/data/api/client-server/sync.yaml index 7a923eca..3a965b56 100644 --- a/data/api/client-server/sync.yaml +++ b/data/api/client-server/sync.yaml @@ -36,20 +36,20 @@ paths: incremental deltas to the state, and to receive new messages. *Note*: This endpoint supports lazy-loading. See `Filtering <#filtering>`_ - for more information. Lazy-loading members is only supported on a ``StateFilter`` + for more information. Lazy-loading members is only supported on a `StateFilter` for this endpoint. When lazy-loading is enabled, servers MUST include the syncing user's own membership event when they join a room, or when the full state of rooms is requested, to aid discovering the user's avatar & displayname. Further, like other members, the user's own membership event is eligible - for being considered redundant by the server. When a sync is ``limited``, + for being considered redundant by the server. When a sync is `limited`, the server MUST return membership events for events in the gap - (between ``since`` and the start of the returned timeline), regardless + (between `since` and the start of the returned timeline), regardless as to whether or not they are redundant. This ensures that joins/leaves and profile changes which occur during the gap are not lost. - Note that the default behaviour of ``state`` is to include all membership + Note that the default behaviour of `state` is to include all membership events, alongside other state, when lazy-loading is not enabled. operationId: sync security: @@ -61,7 +61,7 @@ paths: 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 - an ID or a JSON object by whether the first character is a ``"{"`` + an ID or a JSON object by whether the first character is a `"{"` open brace. Passing the JSON inline is best suited to one off requests. Creating a filter using the filter API is recommended for clients that reuse the same filter multiple times, for example in @@ -82,16 +82,16 @@ paths: Controls whether to include the full state for all rooms the user is a member of. - If this is set to ``true``, then all state events will be returned, - even if ``since`` is non-empty. The timeline will still be limited - by the ``since`` parameter. In this case, the ``timeout`` parameter + If this is set to `true`, then all state events will be returned, + even if `since` is non-empty. The timeline will still be limited + by the `since` parameter. In this case, the `timeout` parameter will be ignored and the query will return immediately, possibly with an empty timeline. - If ``false``, and ``since`` is non-empty, only state which has - changed since the point indicated by ``since`` will be returned. + If `false`, and `since` is non-empty, only state which has + changed since the point indicated by `since` will be returned. - By default, this is ``false``. + By default, this is `false`. x-example: "false" - in: query name: set_presence @@ -113,7 +113,7 @@ paths: request. If no events (or other data) become available before this time elapses, the server will return a response with empty fields. - By default, this is ``0``, so the server will return immediately + By default, this is `0`, so the server will return immediately even if the response is empty. x-example: 30000 responses: @@ -127,8 +127,8 @@ paths: next_batch: type: string description: |- - The batch token to supply in the ``since`` param of the next - ``/sync`` request. + The batch token to supply in the `since` param of the next + `/sync` request. rooms: title: Rooms type: object @@ -157,7 +157,7 @@ paths: 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 + `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 @@ -169,7 +169,7 @@ paths: 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``, + 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 @@ -179,14 +179,14 @@ paths: "m.joined_member_count": type: integer description: |- - The number of users with ``membership`` of ``join``, + 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``. + 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: @@ -194,14 +194,14 @@ paths: 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 `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 + 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: @@ -264,17 +264,17 @@ paths: type: object description: |- The state of a room that the user has been invited - to. These state events may only have the ``sender``, - ``type``, ``state_key`` and ``content`` keys + to. These state events may only have the `sender`, + `type`, `state_key` and `content` keys present. These events do not replace any state that the client already has for the room, for example if the client has archived the room. Instead the client should keep two separate copies of the - state: the one from the ``invite_state`` and one - from the archived ``state``. If the client joins + state: the one from the `invite_state` and one + from the archived `state`. If the client joins the room then the current state will be given as a - delta against the archived ``state`` not the - ``invite_state``. + delta against the archived `state` not the + `invite_state`. properties: events: description: The StrippedState events that form the invite state. diff --git a/data/api/client-server/tags.yaml b/data/api/client-server/tags.yaml index 081d8a84..94e7be07 100644 --- a/data/api/client-server/tags.yaml +++ b/data/api/client-server/tags.yaml @@ -69,7 +69,7 @@ paths: type: number format: float description: |- - A number in a range ``[0,1]`` describing a relative + A number in a range `[0,1]` describing a relative position of the room under the given tag. additionalProperties: true examples: @@ -125,7 +125,7 @@ paths: type: number format: float description: |- - A number in a range ``[0,1]`` describing a relative + A number in a range `[0,1]` describing a relative position of the room under the given tag. additionalProperties: true example: { diff --git a/data/api/client-server/third_party_membership.yaml b/data/api/client-server/third_party_membership.yaml index 4c5890d1..d56fd99c 100644 --- a/data/api/client-server/third_party_membership.yaml +++ b/data/api/client-server/third_party_membership.yaml @@ -48,7 +48,7 @@ paths: join that room. If the identity server did know the Matrix user identifier for the - third party identifier, the homeserver will append a ``m.room.member`` + third party identifier, the homeserver will append a `m.room.member` event to the room. If the identity server does not know a Matrix user identifier for the @@ -56,7 +56,7 @@ paths: which can be accepted upon providing proof of ownership of the third party identifier. This is achieved by the identity server generating a token, which it gives to the inviting homeserver. The homeserver will - add an ``m.room.third_party_invite`` event into the graph for the room, + add an `m.room.third_party_invite` event into the graph for the room, containing that token. When the invitee binds the invited third party identifier to a Matrix @@ -72,7 +72,7 @@ paths: - The matrix user ID who invited them to the room If a token is requested from the identity server, the homeserver will - append a ``m.room.third_party_invite`` event to the room. + append a `m.room.third_party_invite` event to the room. .. _joining rooms section: `invite-by-user-id-endpoint`_ operationId: inviteBy3PID @@ -109,7 +109,7 @@ paths: medium: type: string # TODO: Link to Identity Service spec when it eixsts - description: The kind of address being passed in the address field, for example ``email``. + description: The kind of address being passed in the address field, for example `email`. address: type: string description: The invitee's third party identifier. @@ -124,7 +124,7 @@ paths: type: object 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: + 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: - The invitee has been banned from the room. - The invitee is already a member of the room. diff --git a/data/api/client-server/typing.yaml b/data/api/client-server/typing.yaml index e7cbe2d7..c7138950 100644 --- a/data/api/client-server/typing.yaml +++ b/data/api/client-server/typing.yaml @@ -32,8 +32,8 @@ paths: summary: Informs the server that the user has started or stopped typing. description: |- This tells the server that the user is typing for the next N - milliseconds where N is the value specified in the ``timeout`` key. - Alternatively, if ``typing`` is ``false``, it tells the server that the + milliseconds where N is the value specified in the `timeout` key. + Alternatively, if `typing` is `false`, it tells the server that the user has stopped typing. operationId: setTyping security: @@ -65,7 +65,7 @@ paths: typing: type: boolean description: |- - Whether the user is typing or not. If ``false``, the ``timeout`` + Whether the user is typing or not. If `false`, the `timeout` key can be omitted. timeout: type: integer diff --git a/data/api/client-server/users.yaml b/data/api/client-server/users.yaml index da8cf03f..255c538b 100644 --- a/data/api/client-server/users.yaml +++ b/data/api/client-server/users.yaml @@ -39,8 +39,8 @@ paths: query remote users as part of the search. The search is performed case-insensitively on user IDs and display - names preferably using a collation determined based upon the - ``Accept-Language`` header provided in the request, if present. + names preferably using a collation determined based upon the + `Accept-Language` header provided in the request, if present. operationId: searchUserDirectory security: - accessToken: [] diff --git a/data/api/client-server/versions.yaml b/data/api/client-server/versions.yaml index 2464af1d..e359de3c 100644 --- a/data/api/client-server/versions.yaml +++ b/data/api/client-server/versions.yaml @@ -29,13 +29,13 @@ paths: description: |- Gets the versions of the specification supported by the server. - Values will take the form ``rX.Y.Z``. + Values will take the form `rX.Y.Z`. - Only the latest ``Z`` value will be reported for each supported ``X.Y`` value. - i.e. if the server implements ``r0.0.0``, ``r0.0.1``, and ``r1.2.0``, it will report ``r0.0.1`` and ``r1.2.0``. + Only the latest `Z` value will be reported for each supported `X.Y` value. + i.e. if the server implements `r0.0.0`, `r0.0.1`, and `r1.2.0`, it will report `r0.0.1` and `r1.2.0`. The server may additionally advertise experimental features it supports - through ``unstable_features``. These features should be namespaced and + through `unstable_features`. These features should be namespaced and may optionally include version information within their name if desired. Features listed here are not for optionally toggling parts of the Matrix specification and should only be used to advertise support for a feature diff --git a/data/api/client-server/wellknown.yaml b/data/api/client-server/wellknown.yaml index 3d1c0ae0..9fff7ea7 100644 --- a/data/api/client-server/wellknown.yaml +++ b/data/api/client-server/wellknown.yaml @@ -28,7 +28,7 @@ paths: description: |- Gets discovery information about the domain. The file may include additional keys, which MUST follow the Java package naming convention, - e.g. ``com.example.myapp.property``. This ensures property names are + e.g. `com.example.myapp.property`. This ensures property names are suitably namespaced for each application and reduces the risk of clashes. diff --git a/data/api/client-server/whoami.yaml b/data/api/client-server/whoami.yaml index ad40eb86..713ed370 100644 --- a/data/api/client-server/whoami.yaml +++ b/data/api/client-server/whoami.yaml @@ -29,13 +29,13 @@ paths: get: summary: Gets information about the owner of an access token. description: |- - Gets information about the owner of a given access token. - - Note that, as with the rest of the Client-Server API, - Application Services may masquerade as users within their - namespace by giving a ``user_id`` query parameter. In this - situation, the server should verify that the given ``user_id`` - is registered by the appservice, and return it in the response + Gets information about the owner of a given access token. + + Note that, as with the rest of the Client-Server API, + Application Services may masquerade as users within their + namespace by giving a `user_id` query parameter. In this + situation, the server should verify that the given `user_id` + is registered by the appservice, and return it in the response body. operationId: getTokenOwner security: diff --git a/data/api/identity/associations.yaml b/data/api/identity/associations.yaml index 82c70fb8..084ccded 100644 --- a/data/api/identity/associations.yaml +++ b/data/api/identity/associations.yaml @@ -35,13 +35,13 @@ paths: - in: query type: string name: sid - description: The Session ID generated by the ``requestToken`` call. + description: The Session ID generated by the `requestToken` call. required: true x-example: 1234 - in: query type: string name: client_secret - description: The client secret passed to the ``requestToken`` call. + description: The client secret passed to the `requestToken` call. required: true x-example: monkeys_are_GREAT responses: @@ -72,9 +72,9 @@ paths: 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``. + 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", @@ -97,12 +97,12 @@ paths: description: |- Publish an association between a session and a Matrix user ID. - Future calls to ``/lookup`` for any of the session\'s 3pids will return + Future calls to `/lookup` for any of the session\'s 3pids will return this association. Note: for backwards compatibility with previous drafts of this specification, the parameters may also be specified as - ``application/x-form-www-urlencoded`` data. However, this usage is + `application/x-form-www-urlencoded` data. However, this usage is deprecated. operationId: bind deprecated: true @@ -119,10 +119,10 @@ paths: properties: sid: type: string - description: The Session ID generated by the ``requestToken`` call. + description: The Session ID generated by the `requestToken` call. client_secret: type: string - description: The client secret passed to the ``requestToken`` call. + description: The client secret passed to the `requestToken` call. mxid: type: string description: The Matrix user ID to associate with the 3pids. @@ -184,9 +184,9 @@ paths: 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``. + 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", @@ -209,15 +209,15 @@ paths: description: |- Remove an association between a session and a Matrix user ID. - Future calls to ``/lookup`` for any of the session's 3pids will not + Future calls to `/lookup` for any of the session's 3pids will not return the removed association. The identity server should authenticate the request in one of two ways: - 1. The request is signed by the homeserver which controls the ``user_id``. - 2. The request includes the ``sid`` and ``client_secret`` parameters, - as per ``/3pid/bind``, which proves ownership of the 3PID. + 1. The request is signed by the homeserver which controls the `user_id`. + 2. The request includes the `sid` and `client_secret` parameters, + as per `/3pid/bind`, which proves ownership of the 3PID. If this endpoint returns a JSON Matrix error, that error should be passed through to the client requesting an unbind through a homeserver, if the @@ -241,10 +241,10 @@ paths: properties: sid: type: string - description: The Session ID generated by the ``requestToken`` call. + description: The Session ID generated by the `requestToken` call. client_secret: type: string - description: The client secret passed to the ``requestToken`` call. + description: The client secret passed to the `requestToken` call. mxid: type: string description: The Matrix user ID to remove from the 3pids. @@ -253,7 +253,7 @@ paths: 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. + if using `sid` and `client_secret` to authenticate this request. properties: medium: type: string diff --git a/data/api/identity/definitions/request_email_validation.yaml b/data/api/identity/definitions/request_email_validation.yaml index 1a7502c7..c8a3af6a 100644 --- a/data/api/identity/definitions/request_email_validation.yaml +++ b/data/api/identity/definitions/request_email_validation.yaml @@ -23,7 +23,7 @@ properties: description: | A unique string generated by the client, and used to identify the validation attempt. It must be a string consisting of the characters - ``[0-9a-zA-Z.=_-]``. Its length must not exceed 255 characters and it + `[0-9a-zA-Z.=_-]`. Its length must not exceed 255 characters and it must not be empty. example: "monkeys_are_GREAT" email: @@ -33,9 +33,9 @@ properties: send_attempt: type: integer description: |- - The server will only send an email if the ``send_attempt`` + The server will only send an email if the `send_attempt` is a number greater than the most recent one which it has seen, - scoped to that ``email`` + ``client_secret`` pair. This is to + scoped to that `email` + `client_secret` pair. This is to avoid repeatedly sending the same email in the case of request retries between the POSTing user and the identity server. The client should increment this value if they desire a new diff --git a/data/api/identity/definitions/request_msisdn_validation.yaml b/data/api/identity/definitions/request_msisdn_validation.yaml index 93cea2ed..2b1c8708 100644 --- a/data/api/identity/definitions/request_msisdn_validation.yaml +++ b/data/api/identity/definitions/request_msisdn_validation.yaml @@ -24,14 +24,14 @@ properties: description: | A unique string generated by the client, and used to identify the validation attempt. It must be a string consisting of the characters - ``[0-9a-zA-Z.=_-]``. Its length must not exceed 255 characters and it + `[0-9a-zA-Z.=_-]`. Its length must not exceed 255 characters and it must not be empty. example: "monkeys_are_GREAT" country: type: string description: |- The two-letter uppercase ISO-3166-1 alpha-2 country code that the - number in ``phone_number`` should be parsed as if it were dialled from. + number in `phone_number` should be parsed as if it were dialled from. example: "GB" phone_number: type: string @@ -40,9 +40,9 @@ properties: send_attempt: type: integer description: |- - The server will only send an SMS if the ``send_attempt`` is a + The server will only send an SMS if the `send_attempt` is a number greater than the most recent one which it has seen, - scoped to that ``country`` + ``phone_number`` + ``client_secret`` + scoped to that `country` + `phone_number` + `client_secret` triple. This is to avoid repeatedly sending the same SMS in the case of request retries between the POSTing user and the identity server. The client should increment this value if diff --git a/data/api/identity/definitions/security.yaml b/data/api/identity/definitions/security.yaml index ef49ff5c..64225ec4 100644 --- a/data/api/identity/definitions/security.yaml +++ b/data/api/identity/definitions/security.yaml @@ -13,6 +13,6 @@ # limitations under the License. accessToken: type: apiKey - description: The access_token returned by a call to ``/register``. + description: The access_token returned by a call to `/register`. name: access_token in: query diff --git a/data/api/identity/definitions/sid.yaml b/data/api/identity/definitions/sid.yaml index c1f1ae64..904f79e1 100644 --- a/data/api/identity/definitions/sid.yaml +++ b/data/api/identity/definitions/sid.yaml @@ -18,7 +18,7 @@ properties: description: | The session ID. Session IDs are opaque strings generated by the identity server. They must consist entirely of the characters - ``[0-9a-zA-Z.=_-]``. Their length must not exceed 255 characters and they + `[0-9a-zA-Z.=_-]`. Their length must not exceed 255 characters and they must not be empty. example: "123abc" required: ['sid'] diff --git a/data/api/identity/email_associations.yaml b/data/api/identity/email_associations.yaml index 69ec7c58..6aa7bf4a 100644 --- a/data/api/identity/email_associations.yaml +++ b/data/api/identity/email_associations.yaml @@ -37,13 +37,13 @@ paths: Note that homeservers offer APIs that proxy this API, adding additional behaviour on top, for example, - ``/register/email/requestToken`` is designed specifically for use when + `/register/email/requestToken` is designed specifically for use when registering an account and therefore will inform the user if the email address given is already registered on the server. Note: for backwards compatibility with previous drafts of this specification, the parameters may also be specified as - ``application/x-form-www-urlencoded`` data. However, this usage is + `application/x-form-www-urlencoded` data. However, this usage is deprecated. operationId: emailRequestToken deprecated: true @@ -61,8 +61,8 @@ paths: description: | An error ocurred. Some possible errors are: - - ``M_INVALID_EMAIL``: The email address provided was invalid. - - ``M_EMAIL_SEND_ERROR``: The validation email could not be sent. + - `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", @@ -77,10 +77,10 @@ paths: Validate ownership of an email address. If the three parameters are consistent with a set generated by a - ``requestToken`` call, ownership of the email address is considered to + `requestToken` call, ownership of the email address is considered to have been validated. This does not publish any information publicly, or associate the email address with any Matrix user ID. Specifically, - calls to ``/lookup`` will not show a binding. + calls to `/lookup` will not show a binding. The identity server is free to match the token case-insensitively, or carry out other mapping operations such as unicode @@ -90,7 +90,7 @@ paths: Note: for backwards compatibility with previous drafts of this specification, the parameters may also be specified as - ``application/x-form-www-urlencoded`` data. However, this usage is + `application/x-form-www-urlencoded` data. However, this usage is deprecated. operationId: emailSubmitTokenPost deprecated: true @@ -107,13 +107,13 @@ paths: properties: sid: type: string - description: The session ID, generated by the ``requestToken`` call. + description: The session ID, generated by the `requestToken` call. client_secret: type: string - description: The client secret that was supplied to the ``requestToken`` call. + 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. + description: The token generated by the `requestToken` call and emailed to the user. required: ["sid", "client_secret", "token"] responses: 200: @@ -136,10 +136,10 @@ paths: Validate ownership of an email address. If the three parameters are consistent with a set generated by a - ``requestToken`` call, ownership of the email address is considered to + `requestToken` call, ownership of the email address is considered to have been validated. This does not publish any information publicly, or associate the email address with any Matrix user ID. Specifically, - calls to ``/lookup`` will not show a binding. + calls to `/lookup` will not show a binding. Note that, in contrast with the POST version, this endpoint will be used by end-users, and so the response should be human-readable. @@ -150,28 +150,28 @@ paths: type: string name: sid required: true - description: The session ID, generated by the ``requestToken`` call. + description: The session ID, generated by the `requestToken` call. x-example: 1234 - in: query type: string name: client_secret required: true - description: The client secret that was supplied to the ``requestToken`` call. + description: The client secret that was supplied to the `requestToken` call. x-example: monkeys_are_GREAT - in: query type: string name: token required: true - description: The token generated by the ``requestToken`` call and emailed to the user. + description: The token generated by the `requestToken` call and emailed to the user. x-example: atoken responses: 200: description: Email address is validated. "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. + 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. diff --git a/data/api/identity/invitation_signing.yaml b/data/api/identity/invitation_signing.yaml index e2ac28b0..fc9da1d2 100644 --- a/data/api/identity/invitation_signing.yaml +++ b/data/api/identity/invitation_signing.yaml @@ -30,8 +30,8 @@ paths: description: |- Sign invitation details. - The identity server will look up ``token`` which was stored in a call - to ``store-invite``, and fetch the sender of the invite. + The identity server will look up `token` which was stored in a call + to `store-invite`, and fetch the sender of the invite. operationId: blindlySignStuff deprecated: true parameters: @@ -50,7 +50,7 @@ paths: description: The Matrix user ID of the user accepting the invitation. token: type: string - description: The token from the call to ``store-invite``. + description: The token from the call to `store-invite`. private_key: type: string description: The private key, encoded as `Unpadded base64`_. diff --git a/data/api/identity/lookup.yaml b/data/api/identity/lookup.yaml index 78fa3e3e..bdce7980 100644 --- a/data/api/identity/lookup.yaml +++ b/data/api/identity/lookup.yaml @@ -131,8 +131,8 @@ paths: - type: string - type: string description: |- - An array of arrays containing the `3PID Types`_ with the ``medium`` - in first position and the ``address`` in second position. + An array of arrays containing the `3PID Types`_ with the `medium` + in first position and the `address` in second position. required: - "threepids" responses: @@ -164,8 +164,8 @@ paths: - type: string - type: string description: |- - An array of array containing the `3PID Types`_ with the ``medium`` - in first position, the ``address`` in second position and Matrix user + An array of array containing the `3PID Types`_ with the `medium` + in first position, the `address` in second position and Matrix user ID in third position. required: - "threepids" diff --git a/data/api/identity/phone_associations.yaml b/data/api/identity/phone_associations.yaml index 65bbff0c..53d4132d 100644 --- a/data/api/identity/phone_associations.yaml +++ b/data/api/identity/phone_associations.yaml @@ -37,13 +37,13 @@ paths: Note that homeservers offer APIs that proxy this API, adding additional behaviour on top, for example, - ``/register/msisdn/requestToken`` is designed specifically for use when + `/register/msisdn/requestToken` is designed specifically for use when registering an account and therefore will inform the user if the phone number given is already registered on the server. Note: for backwards compatibility with previous drafts of this specification, the parameters may also be specified as - ``application/x-form-www-urlencoded`` data. However, this usage is + `application/x-form-www-urlencoded` data. However, this usage is deprecated. operationId: msisdnRequestToken deprecated: true @@ -61,9 +61,9 @@ paths: description: | An error ocurred. Some possible errors are: - - ``M_INVALID_ADDRESS``: The phone number provided was invalid. - - ``M_SEND_ERROR``: The validation SMS could not be sent. - - ``M_DESTINATION_REJECTED``: The identity server cannot deliver an + - `M_INVALID_ADDRESS`: The phone number provided was invalid. + - `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: { @@ -79,10 +79,10 @@ paths: Validate ownership of a phone number. If the three parameters are consistent with a set generated by a - ``requestToken`` call, ownership of the phone number is considered to + `requestToken` call, ownership of the phone number is considered to have been validated. This does not publish any information publicly, or associate the phone number address with any Matrix user - ID. Specifically, calls to ``/lookup`` will not show a binding. + ID. Specifically, calls to `/lookup` will not show a binding. The identity server is free to match the token case-insensitively, or carry out other mapping operations such as unicode @@ -92,7 +92,7 @@ paths: Note: for backwards compatibility with previous drafts of this specification, the parameters may also be specified as - ``application/x-form-www-urlencoded`` data. However, this usage is + `application/x-form-www-urlencoded` data. However, this usage is deprecated. operationId: msisdnSubmitTokenPost deprecated: true @@ -109,13 +109,13 @@ paths: properties: sid: type: string - description: The session ID, generated by the ``requestToken`` call. + description: The session ID, generated by the `requestToken` call. client_secret: type: string - description: The client secret that was supplied to the ``requestToken`` call. + 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. + description: The token generated by the `requestToken` call and sent to the user. required: ["sid", "client_secret", "token"] responses: 200: @@ -138,10 +138,10 @@ paths: Validate ownership of a phone number. If the three parameters are consistent with a set generated by a - ``requestToken`` call, ownership of the phone number address is + `requestToken` call, ownership of the phone number address is considered to have been validated. This does not publish any information publicly, or associate the phone number with any Matrix - user ID. Specifically, calls to ``/lookup`` will not show a binding. + user ID. Specifically, calls to `/lookup` will not show a binding. Note that, in contrast with the POST version, this endpoint will be used by end-users, and so the response should be human-readable. @@ -152,28 +152,28 @@ paths: type: string name: sid required: true - description: The session ID, generated by the ``requestToken`` call. + description: The session ID, generated by the `requestToken` call. x-example: 1234 - in: query type: string name: client_secret required: true - description: The client secret that was supplied to the ``requestToken`` call. + description: The client secret that was supplied to the `requestToken` call. x-example: monkeys_are_GREAT - in: query type: string name: token required: true - description: The token generated by the ``requestToken`` call and sent to the user. + description: The token generated by the `requestToken` call and sent to the user. x-example: atoken responses: 200: description: Phone number is validated. "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. + 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. diff --git a/data/api/identity/store_invite.yaml b/data/api/identity/store_invite.yaml index 4a5d525d..20e40852 100644 --- a/data/api/identity/store_invite.yaml +++ b/data/api/identity/store_invite.yaml @@ -37,23 +37,23 @@ paths: The service will generate a random token and an ephemeral key used for accepting the invite. - The service also generates a ``display_name`` for the inviter, which is - a redacted version of ``address`` which does not leak the full contents - of the ``address``. + The service also generates a `display_name` for the inviter, which is + a redacted version of `address` which does not leak the full contents + of the `address`. The service records persistently all of the above information. It also generates an email containing all of this data, sent to the - ``address`` parameter, notifying them of the invitation. + `address` parameter, notifying them of the invitation. Also, the generated ephemeral public key will be listed as valid on - requests to ``/_matrix/identity/api/v1/pubkey/ephemeral/isvalid``. + requests to `/_matrix/identity/api/v1/pubkey/ephemeral/isvalid`. - Currently, invites may only be issued for 3pids of the ``email`` medium. + Currently, invites may only be issued for 3pids of the `email` medium. Optional fields in the request should be populated to the best of the server's ability. Identity servers may use these variables when notifying - the ``address`` of the pending invite for display purposes. + the `address` of the pending invite for display purposes. operationId: storeInvite deprecated: true parameters: @@ -64,7 +64,7 @@ paths: properties: medium: type: string - description: The literal string ``email``. + description: The literal string `email`. example: "email" address: type: string @@ -82,26 +82,26 @@ paths: 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`` + invited. This should be retrieved from the `m.room.canonical_alias` state event. example: "#somewhere:exmaple.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. + 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. + 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. + from the `m.room.name` state event. example: "Bob's Emporium of Messages" sender_display_name: type: string @@ -122,7 +122,7 @@ paths: type: string description: | The generated token. Must be a string consisting of the - characters ``[0-9a-zA-Z.=_-]``. Its length must not exceed + characters `[0-9a-zA-Z.=_-]`. Its length must not exceed 255 characters and it must not be empty. public_keys: type: array @@ -149,8 +149,8 @@ paths: An error has occured. 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``. + 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", diff --git a/data/api/identity/v2_associations.yaml b/data/api/identity/v2_associations.yaml index b9039a18..e6d78d99 100644 --- a/data/api/identity/v2_associations.yaml +++ b/data/api/identity/v2_associations.yaml @@ -39,13 +39,13 @@ paths: - in: query type: string name: sid - description: The Session ID generated by the ``requestToken`` call. + description: The Session ID generated by the `requestToken` call. required: true x-example: 1234 - in: query type: string name: client_secret - description: The client secret passed to the ``requestToken`` call. + description: The client secret passed to the `requestToken` call. required: true x-example: monkeys_are_GREAT responses: @@ -76,9 +76,9 @@ paths: 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``. + 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", @@ -98,7 +98,7 @@ paths: 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`_. + is an `M_TERMS_NOT_SIGNED` error where the user must `agree to more terms`_. examples: application/json: { "errcode": "M_TERMS_NOT_SIGNED", @@ -112,12 +112,12 @@ paths: description: |- Publish an association between a session and a Matrix user ID. - Future calls to ``/lookup`` for any of the session\'s 3pids will return + Future calls to `/lookup` for any of the session\'s 3pids will return this association. Note: for backwards compatibility with previous drafts of this specification, the parameters may also be specified as - ``application/x-form-www-urlencoded`` data. However, this usage is + `application/x-form-www-urlencoded` data. However, this usage is deprecated. operationId: bindV2 security: @@ -135,10 +135,10 @@ paths: properties: sid: type: string - description: The Session ID generated by the ``requestToken`` call. + description: The Session ID generated by the `requestToken` call. client_secret: type: string - description: The client secret passed to the ``requestToken`` call. + description: The client secret passed to the `requestToken` call. mxid: type: string description: The Matrix user ID to associate with the 3pids. @@ -200,9 +200,9 @@ paths: 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``. + 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", @@ -222,7 +222,7 @@ paths: 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`_. + is an `M_TERMS_NOT_SIGNED` error where the user must `agree to more terms`_. examples: application/json: { "errcode": "M_TERMS_NOT_SIGNED", @@ -236,15 +236,15 @@ paths: description: |- Remove an association between a session and a Matrix user ID. - Future calls to ``/lookup`` for any of the session's 3pids will not + Future calls to `/lookup` for any of the session's 3pids will not return the removed association. The identity server should authenticate the request in one of two ways: - 1. The request is signed by the homeserver which controls the ``user_id``. - 2. The request includes the ``sid`` and ``client_secret`` parameters, - as per ``/3pid/bind``, which proves ownership of the 3PID. + 1. The request is signed by the homeserver which controls the `user_id`. + 2. The request includes the `sid` and `client_secret` parameters, + as per `/3pid/bind`, which proves ownership of the 3PID. If this endpoint returns a JSON Matrix error, that error should be passed through to the client requesting an unbind through a homeserver, if the @@ -269,10 +269,10 @@ paths: properties: sid: type: string - description: The Session ID generated by the ``requestToken`` call. + description: The Session ID generated by the `requestToken` call. client_secret: type: string - description: The client secret passed to the ``requestToken`` call. + description: The client secret passed to the `requestToken` call. mxid: type: string description: The Matrix user ID to remove from the 3pids. @@ -281,7 +281,7 @@ paths: 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. + if using `sid` and `client_secret` to authenticate this request. properties: medium: type: string @@ -317,7 +317,7 @@ paths: the chosen authentication method (such as blocking homeservers from unbinding identifiers). - Another common error code is ``M_TERMS_NOT_SIGNED`` where the user + Another common error code is `M_TERMS_NOT_SIGNED` where the user needs to `agree to more terms`_ in order to continue. examples: application/json: { diff --git a/data/api/identity/v2_auth.yaml b/data/api/identity/v2_auth.yaml index a34f679c..f76550b1 100644 --- a/data/api/identity/v2_auth.yaml +++ b/data/api/identity/v2_auth.yaml @@ -32,7 +32,7 @@ paths: description: |- Exchanges an OpenID token from the homeserver for an access token to access the identity server. The request body is the same as the values - returned by ``/openid/request_token`` in the Client-Server API. + returned by `/openid/request_token` in the Client-Server API. operationId: registerAccount parameters: - in: body @@ -83,7 +83,7 @@ paths: 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`_. + is an `M_TERMS_NOT_SIGNED` error where the user must `agree to more terms`_. examples: application/json: { "errcode": "M_TERMS_NOT_SIGNED", @@ -121,7 +121,7 @@ paths: 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`_. + is an `M_TERMS_NOT_SIGNED` error where the user must `agree to more terms`_. examples: application/json: { "errcode": "M_TERMS_NOT_SIGNED", diff --git a/data/api/identity/v2_email_associations.yaml b/data/api/identity/v2_email_associations.yaml index 76c3747e..9865771b 100644 --- a/data/api/identity/v2_email_associations.yaml +++ b/data/api/identity/v2_email_associations.yaml @@ -40,13 +40,13 @@ paths: Note that homeservers offer APIs that proxy this API, adding additional behaviour on top, for example, - ``/register/email/requestToken`` is designed specifically for use when + `/register/email/requestToken` is designed specifically for use when registering an account and therefore will inform the user if the email address given is already registered on the server. Note: for backwards compatibility with previous drafts of this specification, the parameters may also be specified as - ``application/x-form-www-urlencoded`` data. However, this usage is + `application/x-form-www-urlencoded` data. However, this usage is deprecated. operationId: emailRequestTokenV2 security: @@ -65,8 +65,8 @@ paths: description: | An error ocurred. Some possible errors are: - - ``M_INVALID_EMAIL``: The email address provided was invalid. - - ``M_EMAIL_SEND_ERROR``: The validation email could not be sent. + - `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", @@ -77,7 +77,7 @@ paths: 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`_. + is an `M_TERMS_NOT_SIGNED` error where the user must `agree to more terms`_. examples: application/json: { "errcode": "M_TERMS_NOT_SIGNED", @@ -92,10 +92,10 @@ paths: Validate ownership of an email address. If the three parameters are consistent with a set generated by a - ``requestToken`` call, ownership of the email address is considered to + `requestToken` call, ownership of the email address is considered to have been validated. This does not publish any information publicly, or associate the email address with any Matrix user ID. Specifically, - calls to ``/lookup`` will not show a binding. + calls to `/lookup` will not show a binding. The identity server is free to match the token case-insensitively, or carry out other mapping operations such as unicode @@ -105,7 +105,7 @@ paths: Note: for backwards compatibility with previous drafts of this specification, the parameters may also be specified as - ``application/x-form-www-urlencoded`` data. However, this usage is + `application/x-form-www-urlencoded` data. However, this usage is deprecated. operationId: emailSubmitTokenPostV2 security: @@ -123,13 +123,13 @@ paths: properties: sid: type: string - description: The session ID, generated by the ``requestToken`` call. + description: The session ID, generated by the `requestToken` call. client_secret: type: string - description: The client secret that was supplied to the ``requestToken`` call. + 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. + description: The token generated by the `requestToken` call and emailed to the user. required: ["sid", "client_secret", "token"] responses: 200: @@ -149,7 +149,7 @@ paths: 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`_. + is an `M_TERMS_NOT_SIGNED` error where the user must `agree to more terms`_. examples: application/json: { "errcode": "M_TERMS_NOT_SIGNED", @@ -163,10 +163,10 @@ paths: Validate ownership of an email address. If the three parameters are consistent with a set generated by a - ``requestToken`` call, ownership of the email address is considered to + `requestToken` call, ownership of the email address is considered to have been validated. This does not publish any information publicly, or associate the email address with any Matrix user ID. Specifically, - calls to ``/lookup`` will not show a binding. + calls to `/lookup` will not show a binding. Note that, in contrast with the POST version, this endpoint will be used by end-users, and so the response should be human-readable. @@ -178,35 +178,35 @@ paths: type: string name: sid required: true - description: The session ID, generated by the ``requestToken`` call. + description: The session ID, generated by the `requestToken` call. x-example: 1234 - in: query type: string name: client_secret required: true - description: The client secret that was supplied to the ``requestToken`` call. + description: The client secret that was supplied to the `requestToken` call. x-example: monkeys_are_GREAT - in: query type: string name: token required: true - description: The token generated by the ``requestToken`` call and emailed to the user. + description: The token generated by the `requestToken` call and emailed to the user. x-example: atoken responses: 200: description: Email address is validated. "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. + 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`_. + is an `M_TERMS_NOT_SIGNED` error where the user must `agree to more terms`_. examples: application/json: { "errcode": "M_TERMS_NOT_SIGNED", diff --git a/data/api/identity/v2_invitation_signing.yaml b/data/api/identity/v2_invitation_signing.yaml index 0431233a..c8045779 100644 --- a/data/api/identity/v2_invitation_signing.yaml +++ b/data/api/identity/v2_invitation_signing.yaml @@ -33,8 +33,8 @@ paths: description: |- Sign invitation details. - The identity server will look up ``token`` which was stored in a call - to ``store-invite``, and fetch the sender of the invite. + The identity server will look up `token` which was stored in a call + to `store-invite`, and fetch the sender of the invite. operationId: blindlySignStuffV2 security: - accessToken: [] @@ -54,7 +54,7 @@ paths: description: The Matrix user ID of the user accepting the invitation. token: type: string - description: The token from the call to ``store-invite``. + description: The token from the call to `store-invite`. private_key: type: string description: The private key, encoded as `Unpadded base64`_. @@ -102,7 +102,7 @@ paths: 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`_. + is an `M_TERMS_NOT_SIGNED` error where the user must `agree to more terms`_. examples: application/json: { "errcode": "M_TERMS_NOT_SIGNED", diff --git a/data/api/identity/v2_lookup.yaml b/data/api/identity/v2_lookup.yaml index 8acafd75..9e5b18ec 100644 --- a/data/api/identity/v2_lookup.yaml +++ b/data/api/identity/v2_lookup.yaml @@ -55,7 +55,7 @@ paths: type: string description: |- The pepper the client MUST use in hashing identifiers, and MUST - supply to the ``/lookup`` endpoint when performing lookups. + supply to the `/lookup` endpoint when performing lookups. Servers SHOULD rotate this string often. algorithms: @@ -63,7 +63,7 @@ paths: items: type: string description: |- - The algorithms the server supports. Must contain at least ``sha256``. + The algorithms the server supports. Must contain at least `sha256`. required: ['lookup_pepper', 'algorithms'] "/lookup": post: @@ -84,14 +84,14 @@ paths: 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``. + 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. + The pepper from `/hash_details`. This is required even when the + `algorithm` does not make use of it. example: "matrixrocks" addresses: type: array @@ -99,7 +99,7 @@ paths: 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 + the `algorithm` used. Note that queries which have been incorrectly hashed or formatted will lead to no matches. example: [ "4kenr7N9drpCJ4AfalmlGQVsOn3o2RHjkADUpXJWZUc", @@ -109,7 +109,7 @@ paths: responses: 200: description: - The associations for any matched ``addresses``. + The associations for any matched `addresses`. examples: application/json: { "mappings": { @@ -122,7 +122,7 @@ paths: mappings: type: object description: |- - Any applicable mappings of ``addresses`` to Matrix User IDs. Addresses + 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 @@ -132,13 +132,13 @@ paths: 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 + 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. + `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", diff --git a/data/api/identity/v2_phone_associations.yaml b/data/api/identity/v2_phone_associations.yaml index 6d4ad79b..7db891ba 100644 --- a/data/api/identity/v2_phone_associations.yaml +++ b/data/api/identity/v2_phone_associations.yaml @@ -40,13 +40,13 @@ paths: Note that homeservers offer APIs that proxy this API, adding additional behaviour on top, for example, - ``/register/msisdn/requestToken`` is designed specifically for use when + `/register/msisdn/requestToken` is designed specifically for use when registering an account and therefore will inform the user if the phone number given is already registered on the server. Note: for backwards compatibility with previous drafts of this specification, the parameters may also be specified as - ``application/x-form-www-urlencoded`` data. However, this usage is + `application/x-form-www-urlencoded` data. However, this usage is deprecated. operationId: msisdnRequestTokenV2 security: @@ -65,9 +65,9 @@ paths: description: | An error ocurred. Some possible errors are: - - ``M_INVALID_ADDRESS``: The phone number provided was invalid. - - ``M_SEND_ERROR``: The validation SMS could not be sent. - - ``M_DESTINATION_REJECTED``: The identity server cannot deliver an + - `M_INVALID_ADDRESS`: The phone number provided was invalid. + - `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: { @@ -79,7 +79,7 @@ paths: 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`_. + is an `M_TERMS_NOT_SIGNED` error where the user must `agree to more terms`_. examples: application/json: { "errcode": "M_TERMS_NOT_SIGNED", @@ -94,10 +94,10 @@ paths: Validate ownership of a phone number. If the three parameters are consistent with a set generated by a - ``requestToken`` call, ownership of the phone number is considered to + `requestToken` call, ownership of the phone number is considered to have been validated. This does not publish any information publicly, or associate the phone number address with any Matrix user - ID. Specifically, calls to ``/lookup`` will not show a binding. + ID. Specifically, calls to `/lookup` will not show a binding. The identity server is free to match the token case-insensitively, or carry out other mapping operations such as unicode @@ -107,7 +107,7 @@ paths: Note: for backwards compatibility with previous drafts of this specification, the parameters may also be specified as - ``application/x-form-www-urlencoded`` data. However, this usage is + `application/x-form-www-urlencoded` data. However, this usage is deprecated. operationId: msisdnSubmitTokenPostV2 security: @@ -125,13 +125,13 @@ paths: properties: sid: type: string - description: The session ID, generated by the ``requestToken`` call. + description: The session ID, generated by the `requestToken` call. client_secret: type: string - description: The client secret that was supplied to the ``requestToken`` call. + 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. + description: The token generated by the `requestToken` call and sent to the user. required: ["sid", "client_secret", "token"] responses: 200: @@ -151,7 +151,7 @@ paths: 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`_. + is an `M_TERMS_NOT_SIGNED` error where the user must `agree to more terms`_. examples: application/json: { "errcode": "M_TERMS_NOT_SIGNED", @@ -165,10 +165,10 @@ paths: Validate ownership of a phone number. If the three parameters are consistent with a set generated by a - ``requestToken`` call, ownership of the phone number address is + `requestToken` call, ownership of the phone number address is considered to have been validated. This does not publish any information publicly, or associate the phone number with any Matrix - user ID. Specifically, calls to ``/lookup`` will not show a binding. + user ID. Specifically, calls to `/lookup` will not show a binding. Note that, in contrast with the POST version, this endpoint will be used by end-users, and so the response should be human-readable. @@ -180,35 +180,35 @@ paths: type: string name: sid required: true - description: The session ID, generated by the ``requestToken`` call. + description: The session ID, generated by the `requestToken` call. x-example: 1234 - in: query type: string name: client_secret required: true - description: The client secret that was supplied to the ``requestToken`` call. + description: The client secret that was supplied to the `requestToken` call. x-example: monkeys_are_GREAT - in: query type: string name: token required: true - description: The token generated by the ``requestToken`` call and sent to the user. + description: The token generated by the `requestToken` call and sent to the user. x-example: atoken responses: 200: description: Phone number is validated. "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. + 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`_. + is an `M_TERMS_NOT_SIGNED` error where the user must `agree to more terms`_. examples: application/json: { "errcode": "M_TERMS_NOT_SIGNED", diff --git a/data/api/identity/v2_store_invite.yaml b/data/api/identity/v2_store_invite.yaml index 9b7a653c..36079061 100644 --- a/data/api/identity/v2_store_invite.yaml +++ b/data/api/identity/v2_store_invite.yaml @@ -40,23 +40,23 @@ paths: The service will generate a random token and an ephemeral key used for accepting the invite. - The service also generates a ``display_name`` for the inviter, which is - a redacted version of ``address`` which does not leak the full contents - of the ``address``. + The service also generates a `display_name` for the inviter, which is + a redacted version of `address` which does not leak the full contents + of the `address`. The service records persistently all of the above information. It also generates an email containing all of this data, sent to the - ``address`` parameter, notifying them of the invitation. + `address` parameter, notifying them of the invitation. Also, the generated ephemeral public key will be listed as valid on - requests to ``/_matrix/identity/v2/pubkey/ephemeral/isvalid``. + requests to `/_matrix/identity/v2/pubkey/ephemeral/isvalid`. - Currently, invites may only be issued for 3pids of the ``email`` medium. + Currently, invites may only be issued for 3pids of the `email` medium. Optional fields in the request should be populated to the best of the server's ability. Identity servers may use these variables when notifying - the ``address`` of the pending invite for display purposes. + the `address` of the pending invite for display purposes. operationId: storeInviteV2 security: - accessToken: [] @@ -68,7 +68,7 @@ paths: properties: medium: type: string - description: The literal string ``email``. + description: The literal string `email`. example: "email" address: type: string @@ -86,26 +86,26 @@ paths: 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`` + invited. This should be retrieved from the `m.room.canonical_alias` state event. example: "#somewhere:exmaple.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. + 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. + 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. + from the `m.room.name` state event. example: "Bob's Emporium of Messages" sender_display_name: type: string @@ -126,7 +126,7 @@ paths: type: string description: | The generated token. Must be a string consisting of the - characters ``[0-9a-zA-Z.=_-]``. Its length must not exceed + characters `[0-9a-zA-Z.=_-]`. Its length must not exceed 255 characters and it must not be empty. public_keys: type: array @@ -153,8 +153,8 @@ paths: An error has occured. 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``. + 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", @@ -166,7 +166,7 @@ paths: 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`_. + is an `M_TERMS_NOT_SIGNED` error where the user must `agree to more terms`_. examples: application/json: { "errcode": "M_TERMS_NOT_SIGNED", diff --git a/data/api/identity/v2_terms.yaml b/data/api/identity/v2_terms.yaml index 9b831fba..fcab28b7 100644 --- a/data/api/identity/v2_terms.yaml +++ b/data/api/identity/v2_terms.yaml @@ -106,7 +106,7 @@ paths: 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. + have already added that URL to the `m.accepted_terms` collection. required: ['name', 'url'] required: ['policies'] post: @@ -121,7 +121,7 @@ paths: to the user. Servers SHOULD consider acceptance of any one language's URL as acceptance for all other languages of that policy. - The server should avoid returning ``M_TERMS_NOT_SIGNED`` because the client + The server should avoid returning `M_TERMS_NOT_SIGNED` because the client may not be accepting all terms at once. operationId: agreeToTerms security: diff --git a/data/api/push-gateway/push_notifier.yaml b/data/api/push-gateway/push_notifier.yaml index 754c325a..2f03433b 100644 --- a/data/api/push-gateway/push_notifier.yaml +++ b/data/api/push-gateway/push_notifier.yaml @@ -39,7 +39,7 @@ paths: Notifications about a particular event will normally cause the user to be alerted in some way. It is therefore necessary to perform duplicate - suppression for such notifications using the ``event_id`` field to avoid + suppression for such notifications using the `event_id` field to avoid retries of this HTTP API causing duplicate alerts. The operation of updating counts of unread notifications should be idempotent and therefore do not require duplicate suppression. @@ -111,7 +111,7 @@ paths: type: type: string description: |- - The type of the event as in the event's ``type`` field. + The type of the event as in the event's `type` field. sender: type: string description: |- @@ -131,13 +131,13 @@ paths: 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 + 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 + 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. @@ -145,7 +145,7 @@ paths: type: object title: EventContent description: |- - The ``content`` field from the event, if present. The pusher + 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: @@ -178,10 +178,10 @@ paths: app_id: type: string description: |- - The ``app_id`` given when the pusher was created. + The `app_id` given when the pusher was created. pushkey: type: string - description: The ``pushkey`` given when the pusher was created. + description: The `pushkey` given when the pusher was created. pushkey_ts: type: integer description: |- @@ -193,7 +193,7 @@ paths: 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. + pusher creation minus the `url` key. tweaks: type: object title: Tweaks diff --git a/data/api/server-server/backfill.yaml b/data/api/server-server/backfill.yaml index 74067a80..2fd984e7 100644 --- a/data/api/server-server/backfill.yaml +++ b/data/api/server-server/backfill.yaml @@ -32,8 +32,8 @@ paths: summary: Retrieves the events which precede the given event description: |- Retrieves a sliding-window history of previous PDUs that occurred in the given room. - Starting from the PDU ID(s) given in the ``v`` argument, the PDUs given in ``v`` and - the PDUs that preceded them are retrieved, up to the total number given by the ``limit``. + Starting from the PDU ID(s) given in the `v` argument, the PDUs given in `v` and + the PDUs that preceded them are retrieved, up to the total number given by the `limit`. operationId: backfillRoom security: - signedRequest: [] @@ -65,12 +65,12 @@ paths: event(s), up to the given limit. **Note:** - Though the PDU definitions require that ``prev_events`` and ``auth_events`` be limited + Though the PDU definitions require that `prev_events` and `auth_events` be limited in number, the response of backfill MUST NOT be validated on these specific restrictions. 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. + the `/send`, `/get_missing_events`, and remaining endpoints. schema: $ref: "definitions/unlimited_pdu_transaction.yaml" "/get_missing_events/{roomId}": @@ -78,8 +78,8 @@ paths: summary: Retrieves events that the sender is missing description: |- Retrieves previous events that the sender is missing. This is done by doing a breadth-first - walk of the ``prev_events`` for the ``latest_events``, ignoring any events in ``earliest_events`` - and stopping at the ``limit``. + walk of the `prev_events` for the `latest_events`, ignoring any events in `earliest_events` + and stopping at the `limit`. operationId: getMissingPreviousEvents security: - signedRequest: [] @@ -107,7 +107,7 @@ paths: type: array description: |- The latest event IDs that the sender already has. These are skipped when retrieving - the previous events of ``latest_events``. + the previous events of `latest_events`. items: type: string example: ["$missing_event:example.org"] @@ -121,8 +121,8 @@ paths: responses: 200: description: |- - The previous events for ``latest_events``, excluding any ``earliest_events``, up to the - provided ``limit``. + The previous events for `latest_events`, excluding any `earliest_events`, up to the + provided `limit`. schema: type: object properties: diff --git a/data/api/server-server/definitions/event-schemas/m.device_list_update.yaml b/data/api/server-server/definitions/event-schemas/m.device_list_update.yaml index ba22aace..2a9d9b60 100644 --- a/data/api/server-server/definitions/event-schemas/m.device_list_update.yaml +++ b/data/api/server-server/definitions/event-schemas/m.device_list_update.yaml @@ -32,7 +32,7 @@ allOf: edu_type: type: enum enum: ['m.device_list_update'] - description: The string ``m.device_list_update``. + description: The string `m.device_list_update`. example: "m.device_list_update" content: type: object @@ -57,7 +57,7 @@ allOf: type: integer description: |- An ID sent by the server for this update, unique for a given - user_id. Used to identify any gaps in the sequence of ``m.device_list_update`` + user_id. Used to identify any gaps in the sequence of `m.device_list_update` EDUs broadcast by a server. example: 6 prev_id: @@ -67,7 +67,7 @@ allOf: which have not been referred to already in an EDU's prev_id field. If the receiving server does not recognise any of the prev_ids, it means an EDU has been lost and the server should query a snapshot of the device list - via ``/user/keys/query`` in order to correctly interpret future ``m.device_list_update`` + via `/user/keys/query` in order to correctly interpret future `m.device_list_update` EDUs. May be missing or empty for the first EDU in a sequence. items: type: integer diff --git a/data/api/server-server/definitions/event-schemas/m.direct_to_device.yaml b/data/api/server-server/definitions/event-schemas/m.direct_to_device.yaml index 9d5a7468..916922cf 100644 --- a/data/api/server-server/definitions/event-schemas/m.direct_to_device.yaml +++ b/data/api/server-server/definitions/event-schemas/m.direct_to_device.yaml @@ -25,7 +25,7 @@ allOf: edu_type: type: enum enum: ['m.direct_to_device'] - description: The string ``m.direct_to_device``. + description: The string `m.direct_to_device`. example: "m.direct_to_device" content: type: object @@ -50,7 +50,7 @@ allOf: description: |- The contents of the messages to be sent. These are arranged in a map of user IDs to a map of device IDs to message bodies. - The device ID may also be ``*``, meaning all known devices for the user. + The device ID may also be `*`, meaning all known devices for the user. additionalProperties: type: object title: User Devices diff --git a/data/api/server-server/definitions/event-schemas/m.presence.yaml b/data/api/server-server/definitions/event-schemas/m.presence.yaml index 7f47add4..09d5d0d2 100644 --- a/data/api/server-server/definitions/event-schemas/m.presence.yaml +++ b/data/api/server-server/definitions/event-schemas/m.presence.yaml @@ -23,7 +23,7 @@ allOf: edu_type: type: enum enum: ['m.presence'] - description: The string ``m.presence`` + description: The string `m.presence` example: "m.presence" content: type: object @@ -63,8 +63,8 @@ allOf: type: boolean description: |- True if the user is likely to be interacting with their - client. This may be indicated by the user having a - ``last_active_ago`` within the last few minutes. Defaults + client. This may be indicated by the user having a + `last_active_ago` within the last few minutes. Defaults to false. example: true required: ['user_id', 'presence', 'last_active_ago'] diff --git a/data/api/server-server/definitions/event-schemas/m.receipt.yaml b/data/api/server-server/definitions/event-schemas/m.receipt.yaml index 70a02b49..335e7c27 100644 --- a/data/api/server-server/definitions/event-schemas/m.receipt.yaml +++ b/data/api/server-server/definitions/event-schemas/m.receipt.yaml @@ -26,7 +26,7 @@ allOf: edu_type: type: enum enum: ['m.receipt'] - description: The string ``m.receipt`` + description: The string `m.receipt` example: "m.receipt" content: type: object diff --git a/data/api/server-server/definitions/event-schemas/m.signing_key_update.yaml b/data/api/server-server/definitions/event-schemas/m.signing_key_update.yaml index e372483a..c84cd6c3 100644 --- a/data/api/server-server/definitions/event-schemas/m.signing_key_update.yaml +++ b/data/api/server-server/definitions/event-schemas/m.signing_key_update.yaml @@ -24,7 +24,7 @@ allOf: edu_type: type: enum enum: ['m.signing_key_update'] - description: The string ``m.signing_update``. + description: The string `m.signing_update`. example: "m.signing_key_update" content: type: object diff --git a/data/api/server-server/definitions/event-schemas/m.typing.yaml b/data/api/server-server/definitions/event-schemas/m.typing.yaml index ccbecf53..7f23bae1 100644 --- a/data/api/server-server/definitions/event-schemas/m.typing.yaml +++ b/data/api/server-server/definitions/event-schemas/m.typing.yaml @@ -22,7 +22,7 @@ allOf: edu_type: type: enum enum: ['m.typing'] - description: The string ``m.typing`` + description: The string `m.typing` example: "m.typing" content: type: object diff --git a/data/api/server-server/definitions/invite_event.yaml b/data/api/server-server/definitions/invite_event.yaml index dd2efdd6..3b430d03 100644 --- a/data/api/server-server/definitions/invite_event.yaml +++ b/data/api/server-server/definitions/invite_event.yaml @@ -22,7 +22,7 @@ allOf: sender: type: string description: |- - The matrix ID of the user who sent the original ``m.room.third_party_invite``. + The matrix ID of the user who sent the original `m.room.third_party_invite`. example: "@someone:example.org" origin: type: string @@ -35,7 +35,7 @@ allOf: example: 1234567890 type: type: string - description: The value ``m.room.member``. + description: The value `m.room.member`. example: "m.room.member" state_key: type: string @@ -46,12 +46,12 @@ allOf: title: Membership Event Content description: |- The content of the event, matching what is available in the - `Client-Server API`_. Must include a ``membership`` of ``invite``. + `Client-Server API`_. Must include a `membership` of `invite`. example: {"membership": "invite"} properties: membership: type: string - description: The value ``invite``. + description: The value `invite`. example: "invite" required: ['membership'] required: diff --git a/data/api/server-server/definitions/keys.yaml b/data/api/server-server/definitions/keys.yaml index 306d4d00..bd0aa737 100644 --- a/data/api/server-server/definitions/keys.yaml +++ b/data/api/server-server/definitions/keys.yaml @@ -26,10 +26,10 @@ properties: description: |- Public keys of the homeserver for verifying digital signatures. - The object's key is the algorithm and version combined (``ed25519`` being the - algorithm and ``abc123`` being the version in the example below). Together, + The object's key is the algorithm and version combined (`ed25519` being the + algorithm and `abc123` being the version in the example below). Together, this forms the Key ID. The version must have characters matching the regular - expression ``[a-zA-Z0-9_]``. + expression `[a-zA-Z0-9_]`. additionalProperties: type: object title: Verify Key @@ -49,10 +49,10 @@ properties: description: |- The public keys that the server used to use and when it stopped using them. - The object's key is the algorithm and version combined (``ed25519`` being the - algorithm and ``0ldK3y`` being the version in the example below). Together, + The object's key is the algorithm and version combined (`ed25519` being the + algorithm and `0ldK3y` being the version in the example below). Together, this forms the Key ID. The version must have characters matching the regular - expression ``[a-zA-Z0-9_]``. + expression `[a-zA-Z0-9_]`. additionalProperties: type: object title: Old Verify Key @@ -76,7 +76,7 @@ properties: signatures: type: object description: |- - Digital signatures for this object signed using the ``verify_keys``. + Digital signatures for this object signed using the `verify_keys`. The signature is calculated using the process described at `Signing JSON`_. diff --git a/data/api/server-server/definitions/security.yaml b/data/api/server-server/definitions/security.yaml index 6c9cc808..4e0652e9 100644 --- a/data/api/server-server/definitions/security.yaml +++ b/data/api/server-server/definitions/security.yaml @@ -14,6 +14,6 @@ signedRequest: type: apiKey description: |- - The ``Authorization`` header defined in the `Authentication`_ section. + The `Authorization` header defined in the `Authentication`_ section. name: Authorization in: header diff --git a/data/api/server-server/definitions/transaction.yaml b/data/api/server-server/definitions/transaction.yaml index 08f3738a..cf6aaf31 100644 --- a/data/api/server-server/definitions/transaction.yaml +++ b/data/api/server-server/definitions/transaction.yaml @@ -20,7 +20,7 @@ properties: origin: type: string description: |- - The ``server_name`` of the homeserver sending this transaction. + The `server_name` of the homeserver sending this transaction. example: "example.org" origin_server_ts: type: integer diff --git a/data/api/server-server/definitions/unsigned_pdu_base.yaml b/data/api/server-server/definitions/unsigned_pdu_base.yaml index c97e74de..dae148a1 100644 --- a/data/api/server-server/definitions/unsigned_pdu_base.yaml +++ b/data/api/server-server/definitions/unsigned_pdu_base.yaml @@ -27,7 +27,7 @@ properties: example: "@someone:matrix.org" origin: type: string - description: The ``server_name`` of the homeserver that created this event. + description: The `server_name` of the homeserver that created this event. example: "matrix.org" origin_server_ts: type: integer @@ -42,7 +42,7 @@ properties: type: string description: |- If this key is present, the event is a state event, and it will replace previous events - with the same ``type`` and ``state_key`` in the room state. + with the same `type` and `state_key` in the room state. example: "my_key" content: type: object @@ -77,7 +77,7 @@ properties: depth: type: integer description: |- - The maximum depth of the ``prev_events``, plus one. Must be less than the + The maximum depth of the `prev_events`, plus one. Must be less than the maximum value for an integer (2^63 - 1). If the room's depth is already at the limit, the depth must be set to the limit. example: 12 @@ -117,7 +117,7 @@ properties: type: object title: UnsignedData description: |- - Additional data added by the origin server but not covered by the ``signatures``. More + Additional data added by the origin server but not covered by the `signatures`. More keys than those defined here may be used. example: {"key": "value"} properties: diff --git a/data/api/server-server/events.yaml b/data/api/server-server/events.yaml index 1f8ee537..945af253 100644 --- a/data/api/server-server/events.yaml +++ b/data/api/server-server/events.yaml @@ -94,7 +94,7 @@ paths: summary: Get all the state event IDs of a given room description: |- Retrieves a snapshot of a room's state at a given event, in the form of - event IDs. This performs the same function as calling ``/state/{roomId}``, + event IDs. This performs the same function as calling `/state/{roomId}`, however this returns just the event IDs rather than the full events. operationId: getRoomStateIds security: diff --git a/data/api/server-server/invites-v1.yaml b/data/api/server-server/invites-v1.yaml index c054bdd5..f7bf30f8 100644 --- a/data/api/server-server/invites-v1.yaml +++ b/data/api/server-server/invites-v1.yaml @@ -36,8 +36,8 @@ paths: room by the inviting homeserver. Servers should prefer to use the v2 API for invites instead of the v1 API. Servers - which receive a v1 invite request must assume that the room version is either ``"1"`` - or ``"2"``. + which receive a v1 invite request must assume that the room version is either `"1"` + or `"2"`. Note that events have a different format depending on the room version - check the `room version specification`_ for precise event formats. **The request and response @@ -113,7 +113,7 @@ paths: maxItems: 2 items: - type: integer - description: The value ``200``. + description: The value `200`. example: 200 - type: object description: An object containing the signed invite event. diff --git a/data/api/server-server/invites-v2.yaml b/data/api/server-server/invites-v2.yaml index 58d32049..33140b28 100644 --- a/data/api/server-server/invites-v2.yaml +++ b/data/api/server-server/invites-v2.yaml @@ -164,7 +164,7 @@ paths: 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`` + to join has a version that is not listed in the `ver` parameters. The error should be passed through to clients so that they @@ -177,8 +177,8 @@ paths: room_version: type: string description: |- - The version of the room. Required if the ``errcode`` - is ``M_INCOMPATIBLE_ROOM_VERSION``. + The version of the room. Required if the `errcode` + is `M_INCOMPATIBLE_ROOM_VERSION`. examples: application/json: { "errcode": "M_INCOMPATIBLE_ROOM_VERSION", diff --git a/data/api/server-server/joins-v1.yaml b/data/api/server-server/joins-v1.yaml index e9654cd8..da9485bb 100644 --- a/data/api/server-server/joins-v1.yaml +++ b/data/api/server-server/joins-v1.yaml @@ -57,7 +57,7 @@ paths: name: ver description: |- The room versions the sending server has support for. Defaults - to ``[1]``. + to `[1]`. x-example: ["1", "2"] responses: 200: @@ -99,7 +99,7 @@ paths: example: 1234567890 type: type: string - description: The value ``m.room.member``. + description: The value `m.room.member`. example: "m.room.member" state_key: type: string @@ -113,7 +113,7 @@ paths: properties: membership: type: string - description: The value ``join``. + description: The value `join`. example: "join" required: ['membership'] required: @@ -141,7 +141,7 @@ paths: 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`` + to join has a version that is not listed in the `ver` parameters. The error should be passed through to clients so that they @@ -154,8 +154,8 @@ paths: room_version: type: string description: |- - The version of the room. Required if the ``errcode`` - is ``M_INCOMPATIBLE_ROOM_VERSION``. + The version of the room. Required if the `errcode` + is `M_INCOMPATIBLE_ROOM_VERSION`. examples: application/json: { "errcode": "M_INCOMPATIBLE_ROOM_VERSION", @@ -177,7 +177,7 @@ paths: summary: Submit a signed join event to a resident server description: |- **Note:** - Servers should instead prefer to use the v2 ``/send_join`` endpoint. + Servers should instead prefer to use the v2 `/send_join` endpoint. Submits a signed join event to the resident server for it to accept it into the room's graph. Note that events have @@ -224,7 +224,7 @@ paths: example: 1234567890 type: type: string - description: The value ``m.room.member``. + description: The value `m.room.member`. example: "m.room.member" state_key: type: string @@ -238,7 +238,7 @@ paths: properties: membership: type: string - description: The value ``join``. + description: The value `join`. example: "join" required: ['membership'] required: @@ -269,7 +269,7 @@ paths: maxItems: 2 items: - type: integer - description: The value ``200``. + description: The value `200`. example: 200 - $ref: "./definitions/send_join_response.yaml" examples: diff --git a/data/api/server-server/joins-v2.yaml b/data/api/server-server/joins-v2.yaml index 7f1d675e..94cdef19 100644 --- a/data/api/server-server/joins-v2.yaml +++ b/data/api/server-server/joins-v2.yaml @@ -87,7 +87,7 @@ paths: example: 1234567890 type: type: string - description: The value ``m.room.member``. + description: The value `m.room.member`. example: "m.room.member" state_key: type: string @@ -101,7 +101,7 @@ paths: properties: membership: type: string - description: The value ``join``. + description: The value `join`. example: "join" required: ['membership'] required: diff --git a/data/api/server-server/keys_query.yaml b/data/api/server-server/keys_query.yaml index 4989f7fa..cad6b882 100644 --- a/data/api/server-server/keys_query.yaml +++ b/data/api/server-server/keys_query.yaml @@ -93,11 +93,11 @@ paths: 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 + 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`` + 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 diff --git a/data/api/server-server/leaving-v1.yaml b/data/api/server-server/leaving-v1.yaml index ff12bbce..2579d68c 100644 --- a/data/api/server-server/leaving-v1.yaml +++ b/data/api/server-server/leaving-v1.yaml @@ -53,7 +53,7 @@ paths: responses: 200: description: |- - A template to be used to call ``/send_leave``. Note that + 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`_ for precise event formats. **The response body here describes the common event fields in more detail and may be missing other @@ -90,7 +90,7 @@ paths: example: 1234567890 type: type: string - description: The value ``m.room.member``. + description: The value `m.room.member`. example: "m.room.member" state_key: type: string @@ -104,7 +104,7 @@ paths: properties: membership: type: string - description: The value ``leave``. + description: The value `leave`. example: "leave" required: ['membership'] required: @@ -144,7 +144,7 @@ paths: summary: Submit a signed leave event to a resident server description: |- **Note:** - Servers should instead prefer to use the v2 ``/send_leave`` endpoint. + Servers should instead prefer to use the v2 `/send_leave` endpoint. Submits a signed leave event to the resident server for it to accept it into the room's graph. Note that events have @@ -191,7 +191,7 @@ paths: example: 1234567890 type: type: string - description: The value ``m.room.member``. + description: The value `m.room.member`. example: "m.room.member" state_key: type: string @@ -205,7 +205,7 @@ paths: properties: membership: type: string - description: The value ``leave``. + description: The value `leave`. example: "leave" required: ['membership'] depth: @@ -242,7 +242,7 @@ paths: maxItems: 2 items: - type: integer - description: The value ``200``. + description: The value `200`. example: 200 - type: object title: Empty Object diff --git a/data/api/server-server/leaving-v2.yaml b/data/api/server-server/leaving-v2.yaml index 7069b6c0..bd1023fe 100644 --- a/data/api/server-server/leaving-v2.yaml +++ b/data/api/server-server/leaving-v2.yaml @@ -87,7 +87,7 @@ paths: example: 1234567890 type: type: string - description: The value ``m.room.member``. + description: The value `m.room.member`. example: "m.room.member" state_key: type: string @@ -101,7 +101,7 @@ paths: properties: membership: type: string - description: The value ``leave``. + description: The value `leave`. example: "leave" required: ['membership'] depth: diff --git a/data/api/server-server/public_rooms.yaml b/data/api/server-server/public_rooms.yaml index 5324eac3..3c8d7ea6 100644 --- a/data/api/server-server/public_rooms.yaml +++ b/data/api/server-server/public_rooms.yaml @@ -61,7 +61,7 @@ paths: type: string description: |- The specific third party network/protocol to request from the homeserver. - Can only be used if ``include_all_networks`` is false. + Can only be used if `include_all_networks` is false. x-example: "irc" responses: 200: @@ -77,7 +77,7 @@ paths: of joined members, with the largest rooms first. Note that this endpoint receives and returns the same format that is seen - in the Client-Server API's ``POST /publicRooms`` endpoint. + in the Client-Server API's `POST /publicRooms` endpoint. operationId: queryPublicRooms security: - signedRequest: [] @@ -122,7 +122,7 @@ paths: type: string description: |- The specific third party network/protocol to request from the - homeserver. Can only be used if ``include_all_networks`` is false. + homeserver. Can only be used if `include_all_networks` is false. example: "irc" example: { "limit": 10, diff --git a/data/api/server-server/query.yaml b/data/api/server-server/query.yaml index 29826b32..42b64ea8 100644 --- a/data/api/server-server/query.yaml +++ b/data/api/server-server/query.yaml @@ -137,13 +137,13 @@ paths: responses: 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, + 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, the response should include the fields of the user's profile that can be made public, such as the display name and avatar. 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``. + should exclude it from the response body or give it the value `null`. schema: type: object properties: diff --git a/data/api/server-server/third_party_invite.yaml b/data/api/server-server/third_party_invite.yaml index fbd2a9d9..f9a2bf76 100644 --- a/data/api/server-server/third_party_invite.yaml +++ b/data/api/server-server/third_party_invite.yaml @@ -31,7 +31,7 @@ paths: put: summary: Request a server to auth a third party invite event description: |- - The receiving server will verify the partial ``m.room.member`` event + The receiving server will verify the partial `m.room.member` event given in the request body. If valid, the receiving server will issue an invite as per the `Inviting to a room`_ section before returning a response to this request. @@ -48,14 +48,14 @@ paths: - in: body name: body type: object - description: A partial ``m.room.member`` event + description: A partial `m.room.member` event required: true schema: type: object properties: type: type: string - description: The event type. Must be ``m.room.member`` + description: The event type. Must be `m.room.member` example: "m.room.member" room_id: type: string @@ -66,7 +66,7 @@ paths: sender: type: string description: |- - The user ID of the user who sent the original ``m.room.third_party_invite`` + The user ID of the user who sent the original `m.room.third_party_invite` event. example: "@joe:matrix.org" state_key: @@ -80,7 +80,7 @@ paths: properties: membership: type: string - description: The membership state. Must be ``invite`` + description: The membership state. Must be `invite` example: invite third_party_invite: type: object @@ -288,7 +288,7 @@ paths: type: object title: Identity Server Signature description: |- - The signature from the identity server. The ``string`` key + The signature from the identity server. The `string` key is the identity server's domain name, such as vector.im additionalProperties: type: object diff --git a/data/api/server-server/transactions.yaml b/data/api/server-server/transactions.yaml index a6348e13..8690c7aa 100644 --- a/data/api/server-server/transactions.yaml +++ b/data/api/server-server/transactions.yaml @@ -36,7 +36,7 @@ paths: transaction body will be processed. The sending server must wait and retry for a 200 OK response before sending a - transaction with a different ``txnId`` to the receiving server. + transaction with a different `txnId` to the receiving server. Note that events have a different format depending on the room version - check the `room version specification`_ for precise event formats. diff --git a/data/api/server-server/user_devices.yaml b/data/api/server-server/user_devices.yaml index 6bff54c0..0c2348da 100644 --- a/data/api/server-server/user_devices.yaml +++ b/data/api/server-server/user_devices.yaml @@ -58,8 +58,8 @@ paths: 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 + 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: diff --git a/data/api/server-server/user_keys.yaml b/data/api/server-server/user_keys.yaml index c7cf6b76..bcda1737 100644 --- a/data/api/server-server/user_keys.yaml +++ b/data/api/server-server/user_keys.yaml @@ -72,7 +72,7 @@ paths: 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. + map from devices to a map from `:` to the key object. See the `Client-Server Key Algorithms`_ section for more information on the Key Object format. @@ -158,7 +158,7 @@ paths: 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`` + `/keys/upload`, with the addition of an `unsigned` property. additionalProperties: type: object @@ -184,8 +184,8 @@ paths: 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 + `/keys/device_signing/upload`, along with the signatures + uploaded via `/keys/signatures/upload` that the user is allowed to see. additionalProperties: allOf: @@ -205,7 +205,7 @@ paths: 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``. + `/keys/device_signing/upload`. additionalProperties: allOf: - $ref: ../client-server/definitions/cross_signing_key.yaml diff --git a/data/api/server-server/wellknown.yaml b/data/api/server-server/wellknown.yaml index bc390bd5..24d2ae42 100644 --- a/data/api/server-server/wellknown.yaml +++ b/data/api/server-server/wellknown.yaml @@ -33,8 +33,8 @@ paths: 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 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. diff --git a/data/event-schemas/moderation_policy_rule.yaml b/data/event-schemas/moderation_policy_rule.yaml index 34ad4d9a..a57a1ffe 100644 --- a/data/event-schemas/moderation_policy_rule.yaml +++ b/data/event-schemas/moderation_policy_rule.yaml @@ -14,14 +14,14 @@ properties: entity: description: |- - The entity affected by this rule. Glob characters ``*`` and ``?`` can be used + The entity affected by this rule. Glob characters `*` and `?` can be used to match zero or more and one or more characters respectively. type: string recommendation: - description: The suggested action to take. Currently only ``m.ban`` is specified. + description: The suggested action to take. Currently only `m.ban` is specified. type: string reason: - description: The human-readable description for the ``recommendation``. + description: The human-readable description for the `recommendation`. type: string type: object required: diff --git a/data/event-schemas/schema/core-event-schema/msgtype_infos/image_info.yaml b/data/event-schemas/schema/core-event-schema/msgtype_infos/image_info.yaml index ff40efcb..0958fc8a 100644 --- a/data/event-schemas/schema/core-event-schema/msgtype_infos/image_info.yaml +++ b/data/event-schemas/schema/core-event-schema/msgtype_infos/image_info.yaml @@ -12,7 +12,7 @@ properties: differ from the intrinsic dimensions of the image file. type: integer mimetype: - description: The mimetype of the image, e.g. ``image/jpeg``. + description: The mimetype of the image, e.g. `image/jpeg`. type: string size: description: Size of the image in bytes. @@ -31,6 +31,6 @@ properties: thumbnail_info: allOf: - $ref: thumbnail_info.yaml - description: Metadata about the image referred to in ``thumbnail_url``. + description: Metadata about the image referred to in `thumbnail_url`. title: ImageInfo type: object diff --git a/data/event-schemas/schema/core-event-schema/msgtype_infos/thumbnail_info.yaml b/data/event-schemas/schema/core-event-schema/msgtype_infos/thumbnail_info.yaml index 82ffaf5e..79f7c253 100644 --- a/data/event-schemas/schema/core-event-schema/msgtype_infos/thumbnail_info.yaml +++ b/data/event-schemas/schema/core-event-schema/msgtype_infos/thumbnail_info.yaml @@ -12,7 +12,7 @@ properties: differ from the intrinsic dimensions of the image file. type: integer mimetype: - description: The mimetype of the image, e.g. ``image/jpeg``. + description: The mimetype of the image, e.g. `image/jpeg`. type: string size: description: Size of the image in bytes. diff --git a/data/event-schemas/schema/core-event-schema/room_event.yaml b/data/event-schemas/schema/core-event-schema/room_event.yaml index 6a74acdc..7eaae223 100644 --- a/data/event-schemas/schema/core-event-schema/room_event.yaml +++ b/data/event-schemas/schema/core-event-schema/room_event.yaml @@ -5,7 +5,7 @@ properties: room_id: description: |- The ID of the room associated with this event. Will not be present on events - that arrive through ``/sync``, despite being required everywhere else. + that arrive through `/sync`, despite being required everywhere else. type: string required: - room_id diff --git a/data/event-schemas/schema/core-event-schema/sync_state_event.yaml b/data/event-schemas/schema/core-event-schema/sync_state_event.yaml index dc48f941..e7a061f5 100644 --- a/data/event-schemas/schema/core-event-schema/sync_state_event.yaml +++ b/data/event-schemas/schema/core-event-schema/sync_state_event.yaml @@ -20,7 +20,7 @@ description: In addition to the Room Event fields, State Events have the followi additional fields. properties: prev_content: - description: Optional. The previous ``content`` for this event. If there is no + description: Optional. The previous `content` for this event. If there is no previous content, this key will be missing. title: EventContent type: object @@ -29,7 +29,7 @@ properties: of room state. This value is often a zero-length string. The presence of this key makes this event a State Event. - State keys starting with an ``@`` are reserved for referencing user IDs, such + State keys starting with an `@` are reserved for referencing user IDs, such as room members. With the exception of a few events, state events set with a given user's ID as the state key MUST only be set by that user. type: string diff --git a/data/event-schemas/schema/core-event-schema/unsigned_prop.yaml b/data/event-schemas/schema/core-event-schema/unsigned_prop.yaml index 36c37230..aace29ff 100644 --- a/data/event-schemas/schema/core-event-schema/unsigned_prop.yaml +++ b/data/event-schemas/schema/core-event-schema/unsigned_prop.yaml @@ -29,6 +29,6 @@ properties: transaction_id: description: | The client-supplied transaction ID, for example, provided via - ``PUT /_matrix/client/r0/rooms/{roomId}/send/{eventType}/{txnId}``, + `PUT /_matrix/client/r0/rooms/{roomId}/send/{eventType}/{txnId}`, if the client being given the event is the same one which sent it. type: string diff --git a/data/event-schemas/schema/m.call.hangup.yaml b/data/event-schemas/schema/m.call.hangup.yaml index c0478f5a..116d5af7 100644 --- a/data/event-schemas/schema/m.call.hangup.yaml +++ b/data/event-schemas/schema/m.call.hangup.yaml @@ -18,7 +18,7 @@ }, "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.", + "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" diff --git a/data/event-schemas/schema/m.direct.yaml b/data/event-schemas/schema/m.direct.yaml index 8cbbf38f..f00b83bc 100644 --- a/data/event-schemas/schema/m.direct.yaml +++ b/data/event-schemas/schema/m.direct.yaml @@ -3,7 +3,7 @@ allOf: - $ref: core-event-schema/event.yaml description: |- A map of which rooms are considered 'direct' rooms for specific users - is kept in ``account_data`` in an event of type ``m.direct``. The + is kept in `account_data` in an event of type `m.direct`. The content of this event is an object where the keys are the user IDs and values are lists of room ID strings of the 'direct' rooms for that user ID. diff --git a/data/event-schemas/schema/m.dummy.yaml b/data/event-schemas/schema/m.dummy.yaml index 8e4b6f94..6677cacf 100644 --- a/data/event-schemas/schema/m.dummy.yaml +++ b/data/event-schemas/schema/m.dummy.yaml @@ -4,13 +4,13 @@ allOf: description: |- This event type is used to indicate new Olm sessions for end-to-end encryption. - Typically it is encrypted as an ``m.room.encrypted`` event, then sent as a `to-device`_ + Typically it is encrypted as an `m.room.encrypted` event, then sent as a `to-device`_ event. The event does not have any content associated with it. The sending client is expected to send a key share request shortly after this message, causing the receiving client to - process this ``m.dummy`` event as the most recent event and using the keyshare request - to set up the session. The keyshare request and ``m.dummy`` combination should result + process this `m.dummy` event as the most recent event and using the keyshare request + to set up the session. The keyshare request and `m.dummy` combination should result in the original sending client receiving keys over the newly established session. properties: content: diff --git a/data/event-schemas/schema/m.forwarded_room_key.yaml b/data/event-schemas/schema/m.forwarded_room_key.yaml index 7350a25b..a7b45b69 100644 --- a/data/event-schemas/schema/m.forwarded_room_key.yaml +++ b/data/event-schemas/schema/m.forwarded_room_key.yaml @@ -4,7 +4,7 @@ allOf: description: |- This event type is used to forward keys for end-to-end encryption. Typically - it is encrypted as an ``m.room.encrypted`` event, then sent as a `to-device`_ + it is encrypted as an `m.room.encrypted` event, then sent as a `to-device`_ event. properties: content: @@ -49,8 +49,8 @@ properties: Indicates that the key cannot be used to decrypt all the messages from the session because a portion of the session was withheld as described in `Reporting that decryption keys are withheld`_. This - object must include the ``code`` and ``reason`` properties from the - ``m.room_key.withheld`` message that was received by the sender of + object must include the `code` and `reason` properties from the + `m.room_key.withheld` message that was received by the sender of this message. required: - algorithm diff --git a/data/event-schemas/schema/m.identity_server.yaml b/data/event-schemas/schema/m.identity_server.yaml index 75d2409f..acd0eb92 100644 --- a/data/event-schemas/schema/m.identity_server.yaml +++ b/data/event-schemas/schema/m.identity_server.yaml @@ -11,10 +11,10 @@ properties: base_url: type: string description: |- - The URL of the identity server the user prefers to use, or ``null`` + The URL of the identity server the user prefers to use, or `null` if the user does not want to use an identity server. This value is - similar in structure to the ``base_url`` for identity servers in the - ``.well-known/matrix/client`` schema. + similar in structure to the `base_url` for identity servers in the + `.well-known/matrix/client` schema. type: enum: - m.identity_server diff --git a/data/event-schemas/schema/m.ignored_user_list.yaml b/data/event-schemas/schema/m.ignored_user_list.yaml index 7f7a6604..0f0b2f85 100644 --- a/data/event-schemas/schema/m.ignored_user_list.yaml +++ b/data/event-schemas/schema/m.ignored_user_list.yaml @@ -2,8 +2,8 @@ allOf: - $ref: core-event-schema/event.yaml description: |- - A map of users which are considered ignored is kept in ``account_data`` - in an event type of ``m.ignored_user_list``. + A map of users which are considered ignored is kept in `account_data` + in an event type of `m.ignored_user_list`. properties: content: type: object diff --git a/data/event-schemas/schema/m.key.verification.accept.yaml b/data/event-schemas/schema/m.key.verification.accept.yaml index 3f579cc4..d3cdbc67 100644 --- a/data/event-schemas/schema/m.key.verification.accept.yaml +++ b/data/event-schemas/schema/m.key.verification.accept.yaml @@ -3,7 +3,7 @@ allOf: - $ref: core-event-schema/event.yaml description: |- - Accepts a previously sent ``m.key.verification.start`` message. Typically sent as a + Accepts a previously sent `m.key.verification.start` message. Typically sent as a `to-device`_ event. properties: content: @@ -12,27 +12,27 @@ properties: type: string description: |- An opaque identifier for the verification process. Must be the same as - the one used for the ``m.key.verification.start`` message. + the one used for the `m.key.verification.start` message. key_agreement_protocol: type: string description: |- The key agreement protocol the device is choosing to use, out of the - options in the ``m.key.verification.start`` message. + options in the `m.key.verification.start` message. hash: type: string description: |- The hash method the device is choosing to use, out of the options in - the ``m.key.verification.start`` message. + the `m.key.verification.start` message. message_authentication_code: type: string description: |- The message authentication code the device is choosing to use, out of - the options in the ``m.key.verification.start`` message. + the options in the `m.key.verification.start` message. short_authentication_string: type: array description: |- The SAS methods both devices involved in the verification process - understand. Must be a subset of the options in the ``m.key.verification.start`` + understand. Must be a subset of the options in the `m.key.verification.start` message. items: type: string @@ -42,7 +42,7 @@ properties: description: |- The hash (encoded as unpadded base64) of the concatenation of the device's ephemeral public key (encoded as unpadded base64) and the canonical JSON - representation of the ``m.key.verification.start`` message. + representation of the `m.key.verification.start` message. required: - transaction_id - method diff --git a/data/event-schemas/schema/m.key.verification.cancel.yaml b/data/event-schemas/schema/m.key.verification.cancel.yaml index 36ffc9ea..7f11b877 100644 --- a/data/event-schemas/schema/m.key.verification.cancel.yaml +++ b/data/event-schemas/schema/m.key.verification.cancel.yaml @@ -14,8 +14,8 @@ properties: reason: type: string description: |- - A human readable description of the ``code``. The client should only rely on this - string if it does not understand the ``code``. + A human readable description of the `code`. The client should only rely on this + string if it does not understand the `code`. code: type: string # Note: this is not an enum because we go into detail about the different @@ -27,34 +27,34 @@ properties: codes should use the Java package naming convention if not in the following list: - ``m.user``: The user cancelled the verification. + `m.user`: The user cancelled the verification. - ``m.timeout``: The verification process timed out. Verification processes + `m.timeout`: The verification process timed out. Verification processes can define their own timeout parameters. - ``m.unknown_transaction``: The device does not know about the given transaction + `m.unknown_transaction`: The device does not know about the given transaction ID. - ``m.unknown_method``: The device does not know how to handle the requested - method. This should be sent for ``m.key.verification.start`` messages and + `m.unknown_method`: The device does not know how to handle the requested + method. This should be sent for `m.key.verification.start` messages and messages defined by individual verification processes. - ``m.unexpected_message``: The device received an unexpected message. Typically + `m.unexpected_message`: The device received an unexpected message. Typically raised when one of the parties is handling the verification out of order. - ``m.key_mismatch``: The key was not verified. + `m.key_mismatch`: The key was not verified. - ``m.user_mismatch``: The expected user did not match the user verified. + `m.user_mismatch`: The expected user did not match the user verified. - ``m.invalid_message``: The message received was invalid. + `m.invalid_message`: The message received was invalid. - ``m.accepted``: A ``m.key.verification.request`` was accepted by a different + `m.accepted`: A `m.key.verification.request` was accepted by a different device. The device receiving this error can ignore the verification request. Clients should be careful to avoid error loops. For example, if a device sends - an incorrect message and the client returns ``m.invalid_message`` to which it - gets an unexpected response with ``m.unexpected_message``, the client should not - respond again with ``m.unexpected_message`` to avoid the other device potentially + an incorrect message and the client returns `m.invalid_message` to which it + gets an unexpected response with `m.unexpected_message`, the client should not + respond again with `m.unexpected_message` to avoid the other device potentially sending another error response. .. The above blank line is important for RST. diff --git a/data/event-schemas/schema/m.key.verification.key.yaml b/data/event-schemas/schema/m.key.verification.key.yaml index 6dc4954b..b8c14797 100644 --- a/data/event-schemas/schema/m.key.verification.key.yaml +++ b/data/event-schemas/schema/m.key.verification.key.yaml @@ -12,7 +12,7 @@ properties: type: string description: |- An opaque identifier for the verification process. Must be the same as - the one used for the ``m.key.verification.start`` message. + the one used for the `m.key.verification.start` message. key: type: string description: |- diff --git a/data/event-schemas/schema/m.key.verification.mac.yaml b/data/event-schemas/schema/m.key.verification.mac.yaml index 769ebe15..fb06cfc2 100644 --- a/data/event-schemas/schema/m.key.verification.mac.yaml +++ b/data/event-schemas/schema/m.key.verification.mac.yaml @@ -12,7 +12,7 @@ properties: type: string description: |- An opaque identifier for the verification process. Must be the same as - the one used for the ``m.key.verification.start`` message. + the one used for the `m.key.verification.start` message. mac: type: object description: |- @@ -24,7 +24,7 @@ properties: keys: type: string description: |- - The MAC of the comma-separated, sorted, list of key IDs given in the ``mac`` + The MAC of the comma-separated, sorted, list of key IDs given in the `mac` property, encoded as unpadded base64. required: - transaction_id diff --git a/data/event-schemas/schema/m.key.verification.start$m.sas.v1.yaml b/data/event-schemas/schema/m.key.verification.start$m.sas.v1.yaml index f4deb3c8..621c9382 100644 --- a/data/event-schemas/schema/m.key.verification.start$m.sas.v1.yaml +++ b/data/event-schemas/schema/m.key.verification.start$m.sas.v1.yaml @@ -3,7 +3,7 @@ allOf: - $ref: core-event-schema/event.yaml description: |- - Begins a SAS key verification process using the ``m.sas.v1`` method. Typically sent as a `to-device`_ event. + Begins a SAS key verification process using the `m.sas.v1` method. Typically sent as a `to-device`_ event. properties: content: properties: @@ -16,7 +16,7 @@ properties: description: |- An opaque identifier for the verification process. Must be unique with respect to the devices involved. Must be the same as the - ``transaction_id`` given in the ``m.key.verification.request`` + `transaction_id` given in the `m.key.verification.request` if this process is originating from a request. method: type: string @@ -27,29 +27,29 @@ properties: type: array description: |- The key agreement protocols the sending device understands. Should - include at least ``curve25519-hkdf-sha256``. + include at least `curve25519-hkdf-sha256`. items: type: string hashes: type: array description: |- The hash methods the sending device understands. Must include at least - ``sha256``. + `sha256`. items: type: string message_authentication_codes: type: array description: |- The message authentication codes that the sending device understands. - Must include at least ``hkdf-hmac-sha256``. + Must include at least `hkdf-hmac-sha256`. items: type: string short_authentication_string: type: array description: |- The SAS methods the sending device (and the sending device's user) - understands. Must include at least ``decimal``. Optionally can include - ``emoji``. + understands. Must include at least `decimal`. Optionally can include + `emoji`. items: type: string enum: ["decimal", "emoji"] diff --git a/data/event-schemas/schema/m.key.verification.start.yaml b/data/event-schemas/schema/m.key.verification.start.yaml index faa7a96a..17341a3d 100644 --- a/data/event-schemas/schema/m.key.verification.start.yaml +++ b/data/event-schemas/schema/m.key.verification.start.yaml @@ -3,9 +3,9 @@ allOf: - $ref: core-event-schema/event.yaml description: |- - Begins a key verification process. Typically sent as a `to-device`_ event. The ``method`` + Begins a key verification process. Typically sent as a `to-device`_ event. The `method` field determines the type of verification. The fields in the event will differ depending - on the ``method``. This definition includes fields that are in common among all variants. + on the `method`. This definition includes fields that are in common among all variants. properties: content: properties: @@ -18,7 +18,7 @@ properties: description: |- An opaque identifier for the verification process. Must be unique with respect to the devices involved. Must be the same as the - ``transaction_id`` given in the ``m.key.verification.request`` + `transaction_id` given in the `m.key.verification.request` if this process is originating from a request. method: type: string @@ -28,8 +28,8 @@ properties: type: string description: |- Optional method to use to verify the other user's key with. Applicable - when the ``method`` chosen only verifies one user's key. This field will - never be present if the ``method`` verifies keys both ways. + when the `method` chosen only verifies one user's key. This field will + never be present if the `method` verifies keys both ways. required: - from_device - transaction_id diff --git a/data/event-schemas/schema/m.receipt.yaml b/data/event-schemas/schema/m.receipt.yaml index 8594dd7c..4b04e6d6 100644 --- a/data/event-schemas/schema/m.receipt.yaml +++ b/data/event-schemas/schema/m.receipt.yaml @@ -18,7 +18,7 @@ "m.read": { "type": "object", "title": "Users", - "description": "A collection of users who have sent ``m.read`` receipts for this event.", + "description": "A collection of users who have sent `m.read` receipts for this event.", "patternProperties": { "^@": { "type": "object", diff --git a/data/event-schemas/schema/m.room.avatar.yaml b/data/event-schemas/schema/m.room.avatar.yaml index a0ecb21c..7d4b90b1 100644 --- a/data/event-schemas/schema/m.room.avatar.yaml +++ b/data/event-schemas/schema/m.room.avatar.yaml @@ -8,7 +8,7 @@ properties: info: allOf: - $ref: core-event-schema/msgtype_infos/image_info.yaml - description: Metadata about the image referred to in ``url``. + description: Metadata about the image referred to in `url`. url: description: The URL to the image. type: string diff --git a/data/event-schemas/schema/m.room.canonical_alias.yaml b/data/event-schemas/schema/m.room.canonical_alias.yaml index f227871a..7547bd3a 100644 --- a/data/event-schemas/schema/m.room.canonical_alias.yaml +++ b/data/event-schemas/schema/m.room.canonical_alias.yaml @@ -17,7 +17,7 @@ properties: alt_aliases: description: | Alternative aliases the room advertises. This list can have aliases - despite the ``alias`` field being null, empty, or otherwise not present. + despite the `alias` field being null, empty, or otherwise not present. type: array items: type: string diff --git a/data/event-schemas/schema/m.room.create.yaml b/data/event-schemas/schema/m.room.create.yaml index a6fe331e..80ff046e 100644 --- a/data/event-schemas/schema/m.room.create.yaml +++ b/data/event-schemas/schema/m.room.create.yaml @@ -6,13 +6,13 @@ properties: content: properties: creator: - description: The ``user_id`` of the room creator. This is set by the homeserver. + description: The `user_id` of the room creator. This is set by the homeserver. type: string m.federate: - description: Whether users on other servers can join this room. Defaults to ``true`` if key does not exist. + description: Whether users on other servers can join this room. Defaults to `true` if key does not exist. type: boolean room_version: - description: The version of the room. Defaults to ``"1"`` if the key does not exist. + description: The version of the room. Defaults to `"1"` if the key does not exist. type: string predecessor: description: A reference to the room this room replaces, if the previous room was upgraded. diff --git a/data/event-schemas/schema/m.room.encryption.yaml b/data/event-schemas/schema/m.room.encryption.yaml index d7c4d429..9f443b5e 100644 --- a/data/event-schemas/schema/m.room.encryption.yaml +++ b/data/event-schemas/schema/m.room.encryption.yaml @@ -15,12 +15,12 @@ properties: rotation_period_ms: type: integer description: |- - How long the session should be used before changing it. ``604800000`` + How long the session should be used before changing it. `604800000` (a week) is the recommended default. rotation_period_msgs: type: integer description: |- - How many messages should be sent before changing the session. ``100`` is the + How many messages should be sent before changing the session. `100` is the recommended default. required: - algorithm diff --git a/data/event-schemas/schema/m.room.join_rules.yaml b/data/event-schemas/schema/m.room.join_rules.yaml index b8e8501c..faa0f249 100644 --- a/data/event-schemas/schema/m.room.join_rules.yaml +++ b/data/event-schemas/schema/m.room.join_rules.yaml @@ -1,7 +1,7 @@ --- allOf: - $ref: core-event-schema/state_event.yaml -description: 'A room may be ``public`` meaning anyone can join the room without any prior action. Alternatively, it can be ``invite`` meaning that a user who wishes to join the room must first receive an invite to the room from someone already inside of the room. Currently, ``knock`` and ``private`` are reserved keywords which are not implemented.' +description: 'A room may be `public` meaning anyone can join the room without any prior action. Alternatively, it can be `invite` meaning that a user who wishes to join the room must first receive an invite to the room from someone already inside of the room. Currently, `knock` and `private` are reserved keywords which are not implemented.' properties: content: properties: diff --git a/data/event-schemas/schema/m.room.member.yaml b/data/event-schemas/schema/m.room.member.yaml index 172cdd30..3afc6bb9 100644 --- a/data/event-schemas/schema/m.room.member.yaml +++ b/data/event-schemas/schema/m.room.member.yaml @@ -2,34 +2,34 @@ allOf: - $ref: core-event-schema/state_event.yaml description: |- - Adjusts the membership state for a user in a room. It is preferable to use the membership APIs (``/rooms//invite`` etc) when performing membership actions rather than adjusting the state directly as there are a restricted set of valid transformations. For example, user A cannot force user B to join a room, and trying to force this state change directly will fail. + Adjusts the membership state for a user in a room. It is preferable to use the membership APIs (`/rooms//invite` etc) when performing membership actions rather than adjusting the state directly as there are a restricted set of valid transformations. For example, user A cannot force user B to join a room, and trying to force this state change directly will fail. 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. + - `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. + - `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). + - `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``). + - `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`` - This is a reserved word, which currently has no meaning. + - `knock` - This is a reserved word, which currently has no meaning. - 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. + 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. - This event may also include an ``invite_room_state`` key inside the event's ``unsigned`` data. - If present, this contains an array of ``StrippedState`` Events. These events provide information + This event may also include an `invite_room_state` key inside the event's `unsigned` data. + If present, this contains an array of `StrippedState` Events. These events provide information on a subset of state events such as the room name. - The user for which a membership applies is represented by the ``state_key``. Under some conditions, - the ``sender`` and ``state_key`` may not match - this may be interpreted as the ``sender`` affecting - the membership state of the ``state_key`` user. + The user for which a membership applies is represented by the `state_key`. Under some conditions, + the `sender` and `state_key` may not match - this may be interpreted as the `sender` affecting + the membership state of the `state_key` user. - The ``membership`` for a given user can change over time. The table below represents the various changes + The `membership` for a given user can change over time. The table below represents the various changes over time and how clients and servers must interpret those changes. Previous membership can be retrieved - from the ``prev_content`` object on an event. If not present, the user's previous membership must be assumed - as ``leave``. + from the `prev_content` object on an event. If not present, the user's previous membership must be assumed + as `leave`. .. TODO: Improve how this table is written? We use a csv-table to get around vertical header restrictions. @@ -37,12 +37,12 @@ description: |- :header-rows: 1 :stub-columns: 1 - "","to ``invite``","to ``join``","to ``leave``","to ``ban``","to ``knock``" - "from ``invite``","No change.","User joined the room.","If the ``state_key`` is the same as the ``sender``, the user rejected the invite. Otherwise, the ``state_key`` user had their invite revoked.","User was banned.","Not implemented." - "from ``join``","Must never happen.","``displayname`` or ``avatar_url`` changed.","If the ``state_key`` is the same as the ``sender``, the user left. Otherwise, the ``state_key`` user was kicked.","User was kicked and banned.","Not implemented." - "from ``leave``","New invitation sent.","User joined.","No change.","User was banned.","Not implemented." - "from ``ban``","Must never happen.","Must never happen.","User was unbanned.","No change.","Not implemented." - "from ``knock``","Not implemented.","Not implemented.","Not implemented.","Not implemented.","Not implemented." + "","to `invite`","to `join`","to `leave`","to `ban`","to `knock`" + "from `invite`","No change.","User joined the room.","If the `state_key` is the same as the `sender`, the user rejected the invite. Otherwise, the `state_key` user had their invite revoked.","User was banned.","Not implemented." + "from `join`","Must never happen.","`displayname` or `avatar_url` changed.","If the `state_key` is the same as the `sender`, the user left. Otherwise, the `state_key` user was kicked.","User was kicked and banned.","Not implemented." + "from `leave`","New invitation sent.","User joined.","No change.","User was banned.","Not implemented." + "from `ban`","Must never happen.","Must never happen.","User was unbanned.","No change.","Not implemented." + "from `knock`","Not implemented.","Not implemented.","Not implemented.","Not implemented.","Not implemented." properties: content: @@ -115,8 +115,8 @@ properties: type: object state_key: description: |- - The ``user_id`` this membership event relates to. In all cases except for when ``membership`` is - ``join``, the user ID sending the event does not need to match the user ID in the ``state_key``, + The `user_id` this membership event relates to. In all cases except for when `membership` is + `join`, the user ID sending the event does not need to match the user ID in the `state_key`, unlike other events. Regular authorisation rules still apply. type: string type: @@ -129,7 +129,7 @@ properties: - type: object properties: invite_room_state: - description: 'A subset of the state of the room at the time of the invite, if ``membership`` is ``invite``. Note that this state is informational, and SHOULD NOT be trusted; once the client has joined the room, it SHOULD fetch the live state from the server and discard the invite_room_state. Also, clients must not rely on any particular state being present here; they SHOULD behave properly (with possibly a degraded but not a broken experience) in the absence of any particular events here. If they are set on the room, at least the state for ``m.room.avatar``, ``m.room.canonical_alias``, ``m.room.join_rules``, and ``m.room.name`` SHOULD be included.' + description: 'A subset of the state of the room at the time of the invite, if `membership` is `invite`. Note that this state is informational, and SHOULD NOT be trusted; once the client has joined the room, it SHOULD fetch the live state from the server and discard the invite_room_state. Also, clients must not rely on any particular state being present here; they SHOULD behave properly (with possibly a degraded but not a broken experience) in the absence of any particular events here. If they are set on the room, at least the state for `m.room.avatar`, `m.room.canonical_alias`, `m.room.join_rules`, and `m.room.name` SHOULD be included.' items: $ref: "stripped_state.yaml" type: array diff --git a/data/event-schemas/schema/m.room.message$m.audio.yaml b/data/event-schemas/schema/m.room.message$m.audio.yaml index fb049fc9..ce59820c 100644 --- a/data/event-schemas/schema/m.room.message$m.audio.yaml +++ b/data/event-schemas/schema/m.room.message$m.audio.yaml @@ -9,13 +9,13 @@ properties: description: "A description of the audio e.g. 'Bee Gees - Stayin' Alive', or some kind of content description for accessibility e.g. 'audio attachment'." type: string info: - description: Metadata for the audio clip referred to in ``url``. + description: Metadata for the audio clip referred to in `url`. properties: duration: description: The duration of the audio in milliseconds. type: integer mimetype: - description: The mimetype of the audio e.g. ``audio/aac``. + description: The mimetype of the audio e.g. `audio/aac`. type: string size: description: The size of the audio clip in bytes. diff --git a/data/event-schemas/schema/m.room.message$m.emote.yaml b/data/event-schemas/schema/m.room.message$m.emote.yaml index f67a184b..43e2639d 100644 --- a/data/event-schemas/schema/m.room.message$m.emote.yaml +++ b/data/event-schemas/schema/m.room.message$m.emote.yaml @@ -1,7 +1,7 @@ --- allOf: - $ref: core-event-schema/room_event.yaml -description: "This message is similar to ``m.text`` except that the sender is 'performing' the action contained in the ``body`` key, similar to ``/me`` in IRC. This message should be prefixed by the name of the sender. This message could also be represented in a different colour to distinguish it from regular ``m.text`` messages." +description: "This message is similar to `m.text` except that the sender is 'performing' the action contained in the `body` key, similar to `/me` in IRC. This message should be prefixed by the name of the sender. This message could also be represented in a different colour to distinguish it from regular `m.text` messages." properties: content: properties: @@ -14,12 +14,12 @@ properties: type: string format: description: |- - The format used in the ``formatted_body``. Currently only - ``org.matrix.custom.html`` is supported. + The format used in the `formatted_body`. Currently only + `org.matrix.custom.html` is supported. type: string formatted_body: description: |- - The formatted version of the ``body``. This is required if ``format`` + The formatted version of the `body`. This is required if `format` is specified. type: string required: diff --git a/data/event-schemas/schema/m.room.message$m.file.yaml b/data/event-schemas/schema/m.room.message$m.file.yaml index 54a999ec..a3466f78 100644 --- a/data/event-schemas/schema/m.room.message$m.file.yaml +++ b/data/event-schemas/schema/m.room.message$m.file.yaml @@ -12,10 +12,10 @@ properties: description: The original filename of the uploaded file. type: string info: - description: Information about the file referred to in ``url``. + description: Information about the file referred to in `url`. properties: mimetype: - description: The mimetype of the file e.g. ``application/msword``. + description: The mimetype of the file e.g. `application/msword`. type: string size: description: The size of the file in bytes. @@ -34,7 +34,7 @@ properties: thumbnail_info: allOf: - $ref: core-event-schema/msgtype_infos/thumbnail_info.yaml - description: Metadata about the image referred to in ``thumbnail_url``. + description: Metadata about the image referred to in `thumbnail_url`. title: FileInfo type: object msgtype: diff --git a/data/event-schemas/schema/m.room.message$m.image.yaml b/data/event-schemas/schema/m.room.message$m.image.yaml index 8944ce96..98d201f4 100644 --- a/data/event-schemas/schema/m.room.message$m.image.yaml +++ b/data/event-schemas/schema/m.room.message$m.image.yaml @@ -11,7 +11,7 @@ properties: info: allOf: - $ref: core-event-schema/msgtype_infos/image_info.yaml - description: Metadata about the image referred to in ``url``. + description: Metadata about the image referred to in `url`. msgtype: enum: - m.image 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 ffc4edce..cc52bb97 100644 --- a/data/event-schemas/schema/m.room.message$m.location.yaml +++ b/data/event-schemas/schema/m.room.message$m.location.yaml @@ -32,7 +32,7 @@ properties: thumbnail_info: allOf: - $ref: core-event-schema/msgtype_infos/thumbnail_info.yaml - description: Metadata about the image referred to in ``thumbnail_url``. + description: Metadata about the image referred to in `thumbnail_url`. title: LocationInfo required: - msgtype diff --git a/data/event-schemas/schema/m.room.message$m.notice.yaml b/data/event-schemas/schema/m.room.message$m.notice.yaml index 19c4f985..7b735d60 100644 --- a/data/event-schemas/schema/m.room.message$m.notice.yaml +++ b/data/event-schemas/schema/m.room.message$m.notice.yaml @@ -1,7 +1,7 @@ --- allOf: - $ref: core-event-schema/room_event.yaml -description: 'The ``m.notice`` type is primarily intended for responses from automated clients. An ``m.notice`` message must be treated the same way as a regular ``m.text`` message with two exceptions. Firstly, clients should present ``m.notice`` messages to users in a distinct manner, and secondly, ``m.notice`` messages must never be automatically responded to. This helps to prevent infinite-loop situations where two automated clients continuously exchange messages.' +description: 'The `m.notice` type is primarily intended for responses from automated clients. An `m.notice` message must be treated the same way as a regular `m.text` message with two exceptions. Firstly, clients should present `m.notice` messages to users in a distinct manner, and secondly, `m.notice` messages must never be automatically responded to. This helps to prevent infinite-loop situations where two automated clients continuously exchange messages.' properties: content: properties: @@ -14,12 +14,12 @@ properties: type: string format: description: |- - The format used in the ``formatted_body``. Currently only - ``org.matrix.custom.html`` is supported. + The format used in the `formatted_body`. Currently only + `org.matrix.custom.html` is supported. type: string formatted_body: description: |- - The formatted version of the ``body``. This is required if ``format`` + The formatted version of the `body`. This is required if `format` is specified. type: string required: diff --git a/data/event-schemas/schema/m.room.message$m.server_notice.yaml b/data/event-schemas/schema/m.room.message$m.server_notice.yaml index f1848821..ca7144b0 100644 --- a/data/event-schemas/schema/m.room.message$m.server_notice.yaml +++ b/data/event-schemas/schema/m.room.message$m.server_notice.yaml @@ -19,12 +19,12 @@ properties: admin_contact: description: |- A URI giving a contact method for the server administrator. Required if the - notice type is ``m.server_notice.usage_limit_reached``. + notice type is `m.server_notice.usage_limit_reached`. type: string limit_type: description: |- The kind of usage limit the server has exceeded. Required if the notice type is - ``m.server_notice.usage_limit_reached``. + `m.server_notice.usage_limit_reached`. type: string required: - msgtype diff --git a/data/event-schemas/schema/m.room.message$m.text.yaml b/data/event-schemas/schema/m.room.message$m.text.yaml index b481bcea..4cba2bd6 100644 --- a/data/event-schemas/schema/m.room.message$m.text.yaml +++ b/data/event-schemas/schema/m.room.message$m.text.yaml @@ -14,12 +14,12 @@ properties: type: string format: description: |- - The format used in the ``formatted_body``. Currently only - ``org.matrix.custom.html`` is supported. + The format used in the `formatted_body`. Currently only + `org.matrix.custom.html` is supported. type: string formatted_body: description: |- - The formatted version of the ``body``. This is required if ``format`` + The formatted version of the `body`. This is required if `format` is specified. type: string required: diff --git a/data/event-schemas/schema/m.room.message$m.video.yaml b/data/event-schemas/schema/m.room.message$m.video.yaml index 1a3c3e40..9bf3e09c 100644 --- a/data/event-schemas/schema/m.room.message$m.video.yaml +++ b/data/event-schemas/schema/m.room.message$m.video.yaml @@ -9,7 +9,7 @@ properties: description: "A description of the video e.g. 'Gangnam style', or some kind of content description for accessibility e.g. 'video attachment'." type: string info: - description: Metadata about the video clip referred to in ``url``. + description: Metadata about the video clip referred to in `url`. properties: duration: description: The duration of the video in milliseconds. @@ -21,7 +21,7 @@ properties: description: The width of the video in pixels. type: integer mimetype: - description: The mimetype of the video e.g. ``video/mp4``. + description: The mimetype of the video e.g. `video/mp4`. type: string size: description: The size of the video in bytes. @@ -40,7 +40,7 @@ properties: thumbnail_info: allOf: - $ref: core-event-schema/msgtype_infos/thumbnail_info.yaml - description: Metadata about the image referred to in ``thumbnail_url``. + description: Metadata about the image referred to in `thumbnail_url`. title: VideoInfo type: object msgtype: diff --git a/data/event-schemas/schema/m.room.message.feedback.yaml b/data/event-schemas/schema/m.room.message.feedback.yaml index fa3390fa..dc8f4b58 100644 --- a/data/event-schemas/schema/m.room.message.feedback.yaml +++ b/data/event-schemas/schema/m.room.message.feedback.yaml @@ -1,7 +1,7 @@ --- allOf: - $ref: core-event-schema/room_event.yaml -description: '**NB: Usage of this event is discouraged in favour of the** `receipts module`_. **Most clients will not recognise this event.** Feedback events are events sent to acknowledge a message in some way. There are two supported acknowledgements: ``delivered`` (sent when the event has been received) and ``read`` (sent when the event has been observed by the end-user). The ``target_event_id`` should reference the ``m.room.message`` event being acknowledged.' +description: '**NB: Usage of this event is discouraged in favour of the** `receipts module`_. **Most clients will not recognise this event.** Feedback events are events sent to acknowledge a message in some way. There are two supported acknowledgements: `delivered` (sent when the event has been received) and `read` (sent when the event has been observed by the end-user). The `target_event_id` should reference the `m.room.message` event being acknowledged.' properties: content: properties: diff --git a/data/event-schemas/schema/m.room.message.yaml b/data/event-schemas/schema/m.room.message.yaml index 45025c99..546b5e19 100644 --- a/data/event-schemas/schema/m.room.message.yaml +++ b/data/event-schemas/schema/m.room.message.yaml @@ -1,7 +1,7 @@ --- allOf: - $ref: core-event-schema/room_event.yaml -description: 'This event is used when sending messages in a room. Messages are not limited to be text. The ``msgtype`` key outlines the type of message, e.g. text, audio, image, video, etc. The ``body`` key is text and MUST be used with every kind of ``msgtype`` as a fallback mechanism for when a client cannot render a message. This allows clients to display *something* even if it is just plain text.' +description: 'This event is used when sending messages in a room. Messages are not limited to be text. The `msgtype` key outlines the type of message, e.g. text, audio, image, video, etc. The `body` key is text and MUST be used with every kind of `msgtype` as a fallback mechanism for when a client cannot render a message. This allows clients to display *something* even if it is just plain text.' properties: content: properties: @@ -9,7 +9,7 @@ properties: description: The textual representation of this message. type: string msgtype: - description: 'The type of message, e.g. ``m.image``, ``m.text``' + description: 'The type of message, e.g. `m.image`, `m.text`' type: string required: - msgtype diff --git a/data/event-schemas/schema/m.room.name.yaml b/data/event-schemas/schema/m.room.name.yaml index 3e3d15ac..bbc5fc9a 100644 --- a/data/event-schemas/schema/m.room.name.yaml +++ b/data/event-schemas/schema/m.room.name.yaml @@ -7,12 +7,12 @@ description: |- is a human-friendly string designed to be displayed to the end-user. The room name is not unique, as multiple rooms can have the same room name set. - A room with an ``m.room.name`` event with an absent, null, or empty - ``name`` field should be treated the same as a room with no ``m.room.name`` + A room with an `m.room.name` event with an absent, null, or empty + `name` field should be treated the same as a room with no `m.room.name` event. An event of this type is automatically created when creating a room using - ``/createRoom`` with the ``name`` key. + `/createRoom` with the `name` key. properties: content: properties: diff --git a/data/event-schemas/schema/m.room.power_levels.yaml b/data/event-schemas/schema/m.room.power_levels.yaml index 6e026d6c..39c1988c 100644 --- a/data/event-schemas/schema/m.room.power_levels.yaml +++ b/data/event-schemas/schema/m.room.power_levels.yaml @@ -5,42 +5,42 @@ description: |- This event specifies the minimum level a user must have in order to perform a certain action. It also specifies the levels of each user in the room. - If a ``user_id`` is in the ``users`` list, then that ``user_id`` has the + If a `user_id` is in the `users` list, then that `user_id` has the associated power level. Otherwise they have the default level - ``users_default``. If ``users_default`` is not supplied, it is assumed to be - 0. If the room contains no ``m.room.power_levels`` event, the room's creator has + `users_default`. If `users_default` is not supplied, it is assumed to be + 0. If the room contains no `m.room.power_levels` event, the room's creator has a power level of 100, and all other users have a power level of 0. - The level required to send a certain event is governed by ``events``, - ``state_default`` and ``events_default``. If an event type is specified in - ``events``, then the user must have at least the level specified in order to + The level required to send a certain event is governed by `events`, + `state_default` and `events_default`. If an event type is specified in + `events`, then the user must have at least the level specified in order to send that event. If the event type is not supplied, it defaults to - ``events_default`` for Message Events and ``state_default`` for State + `events_default` for Message Events and `state_default` for State Events. - If there is no ``state_default`` in the ``m.room.power_levels`` event, the - ``state_default`` is 50. If there is no ``events_default`` in the - ``m.room.power_levels`` event, the ``events_default`` is 0. If the room - contains no ``m.room.power_levels`` event, *both* the ``state_default`` and - ``events_default`` are 0. + If there is no `state_default` in the `m.room.power_levels` event, the + `state_default` is 50. If there is no `events_default` in the + `m.room.power_levels` event, the `events_default` is 0. If the room + contains no `m.room.power_levels` event, *both* the `state_default` and + `events_default` are 0. The power level required to invite a user to the room, kick a user from the room, ban a user from the room, or redact an event sent by another user, is - defined by ``invite``, ``kick``, ``ban``, and ``redact``, respectively. Each + defined by `invite`, `kick`, `ban`, and `redact`, respectively. Each of these levels defaults to 50 if they are not specified in the - ``m.room.power_levels`` event, or if the room contains no ``m.room.power_levels`` + `m.room.power_levels` event, or if the room contains no `m.room.power_levels` event. **Note:** - As noted above, in the absence of an ``m.room.power_levels`` event, the - ``state_default`` is 0, and all users are considered to have power level 0. + As noted above, in the absence of an `m.room.power_levels` event, the + `state_default` is 0, and all users are considered to have power level 0. That means that **any** member of the room can send an - ``m.room.power_levels`` event, changing the permissions in the room. + `m.room.power_levels` event, changing the permissions in the room. Server implementations should therefore ensure that each room has an - ``m.room.power_levels`` event as soon as it is created. See also the - documentation of the ``/createRoom`` API. + `m.room.power_levels` event as soon as it is created. See also the + documentation of the `/createRoom` API. properties: content: @@ -57,7 +57,7 @@ properties: events_default: description: |- The default level required to send message events. Can be - overridden by the ``events`` key. Defaults to 0 if unspecified. + overridden by the `events` key. Defaults to 0 if unspecified. type: integer invite: description: The level required to invite a user. Defaults to 50 if unspecified. @@ -71,30 +71,30 @@ properties: state_default: description: |- The default level required to send state events. Can be overridden - by the ``events`` key. Defaults to 50 if unspecified. + by the `events` key. Defaults to 50 if unspecified. type: integer users: additionalProperties: type: integer - description: The power levels for specific users. This is a mapping from ``user_id`` to power level for that user. + description: The power levels for specific users. This is a mapping from `user_id` to power level for that user. title: User power levels type: object users_default: description: |- The default power level for every user in the room, unless their - ``user_id`` is mentioned in the ``users`` key. Defaults to 0 if + `user_id` is mentioned in the `users` key. Defaults to 0 if unspecified. type: integer notifications: properties: room: type: integer - description: The level required to trigger an ``@room`` notification. Defaults to 50 if unspecified. + description: The level required to trigger an `@room` notification. Defaults to 50 if unspecified. additionalProperties: type: integer description: |- The power level requirements for specific notification types. - This is a mapping from ``key`` to power level for that notifications key. + This is a mapping from `key` to power level for that notifications key. title: Notifications type: object type: object diff --git a/data/event-schemas/schema/m.room.redaction.yaml b/data/event-schemas/schema/m.room.redaction.yaml index b66c540c..143e7eff 100644 --- a/data/event-schemas/schema/m.room.redaction.yaml +++ b/data/event-schemas/schema/m.room.redaction.yaml @@ -1,7 +1,7 @@ --- allOf: - $ref: core-event-schema/room_event.yaml -description: 'This event is created by the server to describe which event has been redacted, by whom, and optionally why. The event that has been redacted is specified in the ``redacts`` event level key. Redacting an event means that all keys not required by the protocol are stripped off, allowing messages to be hidden or allowing admins to remove offensive or illegal content.' +description: 'This event is created by the server to describe which event has been redacted, by whom, and optionally why. The event that has been redacted is specified in the `redacts` event level key. Redacting an event means that all keys not required by the protocol are stripped off, allowing messages to be hidden or allowing admins to remove offensive or illegal content.' properties: content: properties: diff --git a/data/event-schemas/schema/m.room.server_acl.yaml b/data/event-schemas/schema/m.room.server_acl.yaml index 60424cc6..3a7128f0 100644 --- a/data/event-schemas/schema/m.room.server_acl.yaml +++ b/data/event-schemas/schema/m.room.server_acl.yaml @@ -7,19 +7,19 @@ description: |- server ACL. Servers that do not uphold the ACLs MUST be added to the denied hosts list in order for the ACLs to remain effective. - The ``allow`` and ``deny`` lists are lists of globs supporting ``?`` and ``*`` + The `allow` and `deny` lists are lists of globs supporting `?` and `*` as wildcards. When comparing against the server ACLs, the suspect server's port - number must not be considered. Therefore ``evil.com``, ``evil.com:8448``, and - ``evil.com:1234`` would all match rules that apply to ``evil.com``, for example. + number must not be considered. Therefore `evil.com`, `evil.com:8448`, and + `evil.com:1234` would all match rules that apply to `evil.com`, for example. The ACLs are applied to servers when they make requests, and are applied in the following order: - 1. If there is no ``m.room.server_acl`` event in the room state, allow. - #. If the server name is an IP address (v4 or v6) literal, and ``allow_ip_literals`` - is present and ``false``, deny. - #. If the server name matches an entry in the ``deny`` list, deny. - #. If the server name matches an entry in the ``allow`` list, allow. + 1. If there is no `m.room.server_acl` event in the room state, allow. + #. If the server name is an IP address (v4 or v6) literal, and `allow_ip_literals` + is present and `false`, deny. + #. If the server name matches an entry in the `deny` list, deny. + #. If the server name matches an entry in the `allow` list, allow. #. Otherwise, deny. **Note:** @@ -28,17 +28,17 @@ description: |- allowed to connect and interact with a given room. **Warning:** - Failing to provide an ``allow`` rule of some kind will prevent **all** + Failing to provide an `allow` rule of some kind will prevent **all** servers from participating in the room, including the sender. This renders - the room unusable. A common allow rule is ``[ "*" ]`` which would still - permit the use of the ``deny`` list without losing the room. + the room unusable. A common allow rule is `[ "*" ]` which would still + permit the use of the `deny` list without losing the room. **Warning:** All compliant servers must implement server ACLs. However, legacy or noncompliant servers exist which do not uphold ACLs, and these MUST be manually appended to the denied hosts list when setting an ACL to prevent them from leaking events from banned servers into a room. Currently, the only way to determine noncompliant hosts is - to check the ``prev_events`` of leaked events, therefore detecting servers which + to check the `prev_events` of leaked events, therefore detecting servers which are not upholding the ACLs. Server versions can also be used to try to detect hosts that will not uphold the ACLs, although this is not comprehensive. Server ACLs were added in Synapse v0.32.0, although other server implementations and versions exist in the world. @@ -54,15 +54,15 @@ properties: True to allow server names that are IP address literals. False to deny. Defaults to true if missing or otherwise not a boolean. - This is strongly recommended to be set to ``false`` as servers running + This is strongly recommended to be set to `false` as servers running with IP literal names are strongly discouraged in order to require legitimate homeservers to be backed by a valid registered domain name. allow: type: array description: |- The server names to allow in the room, excluding any port information. - Wildcards may be used to cover a wider range of hosts, where ``*`` - matches zero or more characters and ``?`` matches exactly one character. + Wildcards may be used to cover a wider range of hosts, where `*` + matches zero or more characters and `?` matches exactly one character. **This defaults to an empty list when not provided, effectively disallowing every server.** @@ -72,8 +72,8 @@ properties: type: array description: |- The server names to disallow in the room, excluding any port information. - Wildcards may be used to cover a wider range of hosts, where ``*`` - matches zero or more characters and ``?`` matches exactly one character. + Wildcards may be used to cover a wider range of hosts, where `*` + matches zero or more characters and `?` matches exactly one character. This defaults to an empty list when not provided. items: diff --git a/data/event-schemas/schema/m.room.third_party_invite.yaml b/data/event-schemas/schema/m.room.third_party_invite.yaml index 794bd232..f4188192 100644 --- a/data/event-schemas/schema/m.room.third_party_invite.yaml +++ b/data/event-schemas/schema/m.room.third_party_invite.yaml @@ -2,7 +2,7 @@ $schema: http://json-schema.org/draft-04/schema# allOf: - $ref: core-event-schema/state_event.yaml -description: "Acts as an ``m.room.member`` invite event, where there isn't a target user_id to invite. This event contains a token and a public key whose private key must be used to sign the token. Any user who can present that signature may use this invitation to join the target room." +description: "Acts as an `m.room.member` invite event, where there isn't a target user_id to invite. This event contains a token and a public key whose private key must be used to sign the token. Any user who can present that signature may use this invitation to join the target room." properties: content: properties: diff --git a/data/event-schemas/schema/m.room.topic.yaml b/data/event-schemas/schema/m.room.topic.yaml index ad2a3ba2..78a3d878 100644 --- a/data/event-schemas/schema/m.room.topic.yaml +++ b/data/event-schemas/schema/m.room.topic.yaml @@ -1,7 +1,7 @@ --- allOf: - $ref: core-event-schema/state_event.yaml -description: 'A topic is a short message detailing what is currently being discussed in the room. It can also be used as a way to display extra information about the room, which may not be suitable for the room name. The room topic can also be set when creating a room using ``/createRoom`` with the ``topic`` key.' +description: 'A topic is a short message detailing what is currently being discussed in the room. It can also be used as a way to display extra information about the room, which may not be suitable for the room name. The room topic can also be set when creating a room using `/createRoom` with the `topic` key.' properties: content: properties: diff --git a/data/event-schemas/schema/m.room_key.withheld.yaml b/data/event-schemas/schema/m.room_key.withheld.yaml index a2cddbfa..797b51f9 100644 --- a/data/event-schemas/schema/m.room_key.withheld.yaml +++ b/data/event-schemas/schema/m.room_key.withheld.yaml @@ -6,31 +6,31 @@ description: |- This event type is used to indicate that the sender is not sharing room keys with the recipient. It is sent as a to-device event. - Possible values for ``code`` include: + Possible values for `code` include: - * ``m.blacklisted``: the user/device was blacklisted. - * ``m.unverified``: the user/device was not verified, and the sender is only + * `m.blacklisted`: the user/device was blacklisted. + * `m.unverified`: the user/device was not verified, and the sender is only sharing keys with verified users/devices. - * ``m.unauthorised``: the user/device is not allowed to have the key. For + * `m.unauthorised`: the user/device is not allowed to have the key. For example, this could be sent in response to a key request if the user/device was not in the room when the original message was sent. - * ``m.unavailable``: sent in reply to a key request if the device that the + * `m.unavailable`: sent in reply to a key request if the device that the key is requested from does not have the requested key. - * ``m.no_olm``: an olm session could not be established. + * `m.no_olm`: an olm session could not be established. In most cases, this event refers to a specific room key. The one exception to this is when the sender is unable to establish an olm session with the recipient. When this happens, multiple sessions will be affected. In order to avoid filling the recipient\'s device mailbox, the sender should only send - one ``m.room_key.withheld`` message with no ``room_id`` nor ``session_id`` + one `m.room_key.withheld` message with no `room_id` nor `session_id` set. If the sender retries and fails to create an olm session again in the - future, it should not send another ``m.room_key.withheld`` message with a - ``code`` of ``m.no_olm``, unless another olm session was previously + future, it should not send another `m.room_key.withheld` message with a + `code` of `m.no_olm`, unless another olm session was previously established successfully. In response to receiving an - ``m.room_key.withheld`` message with a ``code`` of ``m.no_olm``, the - recipient may start an olm session with the sender and send an ``m.dummy`` + `m.room_key.withheld` message with a `code` of `m.no_olm`, the + recipient may start an olm session with the sender and send an `m.dummy` message to notify the sender of the new olm session. The recipient may - assume that this ``m.room_key.withheld`` message applies to all encrypted + assume that this `m.room_key.withheld` message applies to all encrypted room messages sent before it receives the message. properties: content: @@ -43,12 +43,12 @@ properties: room_id: type: string description: |- - Required if ``code`` is not ``m.no_olm``. The room for the key that + Required if `code` is not `m.no_olm`. The room for the key that this event is about. session_id: type: string description: |- - Required of ``code`` is not ``m.no_olm``. The session ID of the key + Required of `code` is not `m.no_olm`. The session ID of the key that this event is aboutis for. sender_key: type: string @@ -73,7 +73,7 @@ properties: description: |- A human-readable reason for why the key was not sent. The receiving client should only use this string if it does not understand the - ``code``. + `code`. required: - algorithm - sender_key diff --git a/data/event-schemas/schema/m.room_key.yaml b/data/event-schemas/schema/m.room_key.yaml index ef8c51c0..8f140aab 100644 --- a/data/event-schemas/schema/m.room_key.yaml +++ b/data/event-schemas/schema/m.room_key.yaml @@ -4,7 +4,7 @@ allOf: description: |- This event type is used to exchange keys for end-to-end encryption. Typically - it is encrypted as an ``m.room.encrypted`` event, then sent as a `to-device`_ event. + it is encrypted as an `m.room.encrypted` event, then sent as a `to-device`_ event. properties: content: properties: diff --git a/data/event-schemas/schema/m.room_key_request.yaml b/data/event-schemas/schema/m.room_key_request.yaml index c08ac0e3..a456b8fe 100644 --- a/data/event-schemas/schema/m.room_key_request.yaml +++ b/data/event-schemas/schema/m.room_key_request.yaml @@ -10,8 +10,8 @@ properties: properties: body: description: |- - Information about the requested key. Required when ``action`` is - ``request``. + Information about the requested key. Required when `action` is + `request`. properties: algorithm: type: string diff --git a/data/event-schemas/schema/m.sticker.yaml b/data/event-schemas/schema/m.sticker.yaml index 1dd1173c..5856cca6 100644 --- a/data/event-schemas/schema/m.sticker.yaml +++ b/data/event-schemas/schema/m.sticker.yaml @@ -15,11 +15,11 @@ properties: allOf: - $ref: core-event-schema/msgtype_infos/image_info.yaml description: |- - Metadata about the image referred to in ``url`` including a thumbnail + Metadata about the image referred to in `url` including a thumbnail representation. url: description: |- - The URL to the sticker image. This must be a valid ``mxc://`` URI. + The URL to the sticker image. This must be a valid `mxc://` URI. type: string required: - body diff --git a/data/event-schemas/schema/m.tag.yaml b/data/event-schemas/schema/m.tag.yaml index 8da093bd..afa22420 100644 --- a/data/event-schemas/schema/m.tag.yaml +++ b/data/event-schemas/schema/m.tag.yaml @@ -24,7 +24,7 @@ "type": "number", "format": "float", "description": - "A number in a range ``[0,1]`` describing a relative position of the room under the given tag." + "A number in a range `[0,1]` describing a relative position of the room under the given tag." } } } diff --git a/data/event-schemas/schema/stripped_state.yaml b/data/event-schemas/schema/stripped_state.yaml index ec591bf1..92306dc9 100644 --- a/data/event-schemas/schema/stripped_state.yaml +++ b/data/event-schemas/schema/stripped_state.yaml @@ -21,21 +21,21 @@ title: StrippedState type: object description: |- - A stripped down state event, with only the ``type``, ``state_key``, - ``sender``, and ``content`` keys. + A stripped down state event, with only the `type`, `state_key`, + `sender`, and `content` keys. properties: content: - description: The ``content`` for the event. + description: The `content` for the event. title: EventContent type: object state_key: - description: The ``state_key`` for the event. + description: The `state_key` for the event. type: string type: - description: The ``type`` for the event. + description: The `type` for the event. type: string sender: - description: The ``sender`` for the event. + description: The `sender` for the event. type: string required: - type