diff --git a/attic/drafts/model/rooms.rst b/attic/drafts/model/rooms.rst index 2f57f2bc..01d25c2f 100644 --- a/attic/drafts/model/rooms.rst +++ b/attic/drafts/model/rooms.rst @@ -246,7 +246,7 @@ anyway. In this arrangement there is now a room with both users may join but neither has the power to invite any others. Both users now have the confidence that (at least within the messaging system itself) their messages remain private and -cannot later be provably leaked to a third party. They can freely set the topic +cannot later be provably leaked to a third-party. They can freely set the topic or name if they choose and add or edit any other state of the room. The update powerlevel of each of these fixed properties should be 1, to lock out the users from being able to alter them. diff --git a/attic/drafts/model/third-party-id.rst b/attic/drafts/model/third-party-id.rst index 838a6799..ccbd005f 100644 --- a/attic/drafts/model/third-party-id.rst +++ b/attic/drafts/model/third-party-id.rst @@ -1,9 +1,9 @@ ====================== -Third Party Identities +Third-party Identities ====================== -A description of how email addresses, mobile phone numbers and other third -party identifiers can be used to authenticate and discover users in Matrix. +A description of how email addresses, mobile phone numbers and other third-party +identifiers can be used to authenticate and discover users in Matrix. Overview @@ -15,16 +15,16 @@ and phone numbers for contacts in their address book. They want to communicate with those contacts in Matrix without manually exchanging a Matrix User ID with them. -Third Party IDs +Third-party IDs --------------- [[TODO(markjh): Describe the format of a 3PID]] -Third Party ID Associations +Third-party ID Associations --------------------------- -An Associaton is a binding between a Matrix User ID and a Third Party ID (3PID). +An Associaton is a binding between a Matrix User ID and a Third-party ID (3PID). Each 3PID can be associated with one Matrix User ID at a time. [[TODO(markjh): JSON format of the association.]] diff --git a/changelogs/application_service/newsfragments/1447.clarification b/changelogs/application_service/newsfragments/1447.clarification new file mode 100644 index 00000000..ca5f3aea --- /dev/null +++ b/changelogs/application_service/newsfragments/1447.clarification @@ -0,0 +1 @@ +Fix various typos throughout the specification. \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1447.clarification b/changelogs/client_server/newsfragments/1447.clarification new file mode 100644 index 00000000..ca5f3aea --- /dev/null +++ b/changelogs/client_server/newsfragments/1447.clarification @@ -0,0 +1 @@ +Fix various typos throughout the specification. \ No newline at end of file diff --git a/changelogs/legacy/application_service.rst b/changelogs/legacy/application_service.rst index 51a97637..a59e1bb9 100644 --- a/changelogs/legacy/application_service.rst +++ b/changelogs/legacy/application_service.rst @@ -22,5 +22,5 @@ r0.1.0 This is the first release of the Application Service specification. It includes support for application services being able to interact with -homeservers and bridge third party networks, such as IRC, over to Matrix +homeservers and bridge third-party networks, such as IRC, over to Matrix in a standard and accessible way. diff --git a/changelogs/legacy/client_server.rst b/changelogs/legacy/client_server.rst index c5b8fae9..ef71bbbc 100644 --- a/changelogs/legacy/client_server.rst +++ b/changelogs/legacy/client_server.rst @@ -211,7 +211,7 @@ Backwards Compatible Changes - Add a common standard for user, room, and group mentions in messages. (`#1547 `_) - Add server ACLs as an option for controlling federation in a room. (`#1550 `_) - Add new push rules for encrypted events and ``@room`` notifications. (`#1551 `_) -- Add third party network room directories, as provided by application services. (`#1554 `_) +- Add third-party network room directories, as provided by application services. (`#1554 `_) - Document the ``validated_at`` and ``added_at`` fields on ``GET /acount/3pid``. (`#1567 `_) - Add an ``inhibit_login`` registration option. (`#1589 `_) - Recommend that servers set a Content Security Policy for the content repository. (`#1600 `_) @@ -554,7 +554,7 @@ Since the draft stage, the following major changes have been made: - Push notification - History visibility - Search - - Invites based on third party identifiers + - Invites based on third-party identifiers - Room tagging - Guest access - Client config diff --git a/changelogs/legacy/identity_service.rst b/changelogs/legacy/identity_service.rst index 7cccc0cf..6941e275 100644 --- a/changelogs/legacy/identity_service.rst +++ b/changelogs/legacy/identity_service.rst @@ -48,7 +48,7 @@ r0.1.0 ====== This is the first release of the Identity Service API. With this API, clients and -homeservers can store bindings between third party identifiers such as email addresses +homeservers can store bindings between third-party identifiers such as email addresses and phone numbers, associating them with Matrix user IDs. Additionally, identity -servers offer the ability to invite third party users to Matrix rooms by storing +servers offer the ability to invite third-party users to Matrix rooms by storing the invite until the identifier is bound. diff --git a/changelogs/server_server/newsfragments/1447.clarification b/changelogs/server_server/newsfragments/1447.clarification new file mode 100644 index 00000000..ca5f3aea --- /dev/null +++ b/changelogs/server_server/newsfragments/1447.clarification @@ -0,0 +1 @@ +Fix various typos throughout the specification. \ No newline at end of file diff --git a/content/_index.md b/content/_index.md index 62e2ef85..6396e4a3 100644 --- a/content/_index.md +++ b/content/_index.md @@ -372,7 +372,7 @@ servers that are in the room that can be used to join via. Users in Matrix are identified via their Matrix user ID. However, existing 3rd party ID namespaces can also be used in order to identify Matrix users. A Matrix "Identity" describes both the user ID and any -other existing IDs from third party namespaces *linked* to their +other existing IDs from third-party namespaces *linked* to their account. Matrix users can *link* third-party IDs (3PIDs) such as email addresses, social network accounts and phone numbers to their user ID. Linking 3PIDs creates a mapping from a 3PID to a user ID. This mapping diff --git a/content/appendices.md b/content/appendices.md index 203c650a..72bda5e9 100644 --- a/content/appendices.md +++ b/content/appendices.md @@ -892,7 +892,7 @@ unique servers based on the following criteria: ## 3PID Types -Third Party Identifiers (3PIDs) represent identifiers on other +Third-party Identifiers (3PIDs) represent identifiers on other namespaces that might be associated with a particular person. They comprise a tuple of `medium` which is a string that identifies the namespace in which the identifier exists, and an `address`: a string diff --git a/content/application-service-api.md b/content/application-service-api.md index fa24d6fd..7a14869a 100644 --- a/content/application-service-api.md +++ b/content/application-service-api.md @@ -232,18 +232,18 @@ mappings. {{% http-api spec="application-service" api="query_room" %}} -#### Third party networks +#### Third-party networks Application services may declare which protocols they support via their registration configuration for the homeserver. These networks are -generally for third party services such as IRC that the application +generally for third-party services such as IRC that the application service is managing. Application services may populate a Matrix room directory for their registered protocols, as defined in the Client-Server API Extensions. -Each protocol may have several "locations" (also known as "third party +Each protocol may have several "locations" (also known as "third-party locations" or "3PLs"). A location within a protocol is a place in the -third party network, such as an IRC channel. Users of the third party +third-party network, such as an IRC channel. Users of the third-party network may also be represented by the application service. Locations and users can be searched by fields defined by the application @@ -399,13 +399,13 @@ the user implied by `sender_localpart`. #### Application service room directories Application services can maintain their own room directories for their -defined third party protocols. These room directories may be accessed by +defined third-party protocols. These room directories may be accessed by clients through additional parameters on the `/publicRooms` client-server endpoint. {{% http-api spec="client-server" api="appservice_room_directory" %}} -### Referencing messages from a third party network +### Referencing messages from a third-party network Application services should include an `external_url` in the `content` of events it emits to indicate where the message came from. This diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index d2759a46..617d9259 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -150,15 +150,15 @@ Sent when a threepid given to an API cannot be used because no record matching the threepid was found. `M_THREEPID_AUTH_FAILED` -Authentication could not be performed on the third party identifier. +Authentication could not be performed on the third-party identifier. `M_THREEPID_DENIED` -The server does not permit this third party identifier. This may happen +The server does not permit this third-party identifier. This may happen if the server only permits, for example, email addresses from a particular domain. `M_SERVER_NOT_TRUSTED` -The client's request used a third party server, e.g. identity server, +The client's request used a third-party server, e.g. identity server, that this server does not trust. `M_UNSUPPORTED_ROOM_VERSION` @@ -764,8 +764,8 @@ explicitly as follows: "type": "m.login.password", "identifier": { "type": "m.id.thirdparty", - "medium": "", - "address": "" + "medium": "", + "address": "" }, "password": "", "session": "" @@ -1071,8 +1071,8 @@ ID media. ```json "identifier": { "type": "m.id.thirdparty", - "medium": "", - "address": "" + "medium": "", + "address": "" } ``` @@ -1132,8 +1132,8 @@ the homeserver using the [`/account/3pid`](#get_matrixclientv3account3pid) API r { "type": "m.login.password", "identifier": { - "medium": "", - "address": "" + "medium": "", + "address": "" }, "password": "" } @@ -1258,7 +1258,7 @@ can be added and bound at the same time, depending on context. #### Notes on identity servers Identity servers in Matrix store bindings (relationships) between a -user's third party identifier, typically email or phone number, and +user's third-party identifier, typically email or phone number, and their user ID. Once a user has chosen an identity server, that identity server should be used by all clients. @@ -2566,7 +2566,7 @@ that profile. | [Room Upgrades](#room-upgrades) | Required | Required | Required | Required | Optional | | [Server Administration](#server-administration) | Optional | Optional | Optional | Optional | Optional | | [Event Context](#event-context) | Optional | Optional | Optional | Optional | Optional | -| [Third Party Networks](#third-party-networks) | Optional | Optional | Optional | Optional | Optional | +| [Third-party Networks](#third-party-networks) | Optional | Optional | Optional | Optional | Optional | | [Send-to-Device Messaging](#send-to-device-messaging) | Optional | Optional | Optional | Optional | Optional | | [Device Management](#device-management) | Optional | Optional | Optional | Optional | Optional | | [End-to-End Encryption](#end-to-end-encryption) | Optional | Optional | Optional | Optional | Optional | diff --git a/content/client-server-api/modules/openid.md b/content/client-server-api/modules/openid.md index 6e0c2d04..1aff30cd 100644 --- a/content/client-server-api/modules/openid.md +++ b/content/client-server-api/modules/openid.md @@ -1,8 +1,8 @@ ### OpenID -This module allows users to verify their identity with a third party -service. The third party service does need to be matrix-aware in that it +This module allows users to verify their identity with a third-party +service. The third-party service does need to be matrix-aware in that it will need to know to resolve matrix homeservers to exchange the user's token for identity information. diff --git a/content/client-server-api/modules/third_party_invites.md b/content/client-server-api/modules/third_party_invites.md index fcf0b86a..aff7b530 100644 --- a/content/client-server-api/modules/third_party_invites.md +++ b/content/client-server-api/modules/third_party_invites.md @@ -1,12 +1,12 @@ -### Third party invites +### Third-party invites This module adds in support for inviting new members to a room where -their Matrix user ID is not known, instead addressing them by a third -party identifier such as an email address. There are two flows here; one -if a Matrix user ID is known for the third party identifier, and one if +their Matrix user ID is not known, instead addressing them by a third-party +identifier such as an email address. There are two flows here; one +if a Matrix user ID is known for the third-party identifier, and one if not. Either way, the client calls `/invite` with the details of the -third party identifier. +third-party identifier. The homeserver asks the identity server whether a Matrix user ID is known for that identifier: @@ -22,7 +22,7 @@ When the invitee's homeserver receives the notification of the binding, it should insert an `m.room.member` event into the room's graph for that user, with `content.membership` = `invite`, as well as a `content.third_party_invite` property which contains proof that the -invitee does indeed own that third party identifier. See the +invitee does indeed own that third-party identifier. See the [m.room.member](#mroommember) schema for more information. #### Events @@ -31,14 +31,14 @@ invitee does indeed own that third party identifier. See the #### Client behaviour -A client asks a server to invite a user by their third party identifier. +A client asks a server to invite a user by their third-party identifier. {{% http-api spec="client-server" api="third_party_membership" %}} #### Server behaviour Upon receipt of an `/invite`, the server is expected to look up the -third party identifier with the provided identity server. If the lookup +third-party identifier with the provided identity server. If the lookup yields a result for a Matrix User ID then the normal invite process can be initiated. This process ends up looking like this: @@ -104,12 +104,12 @@ looking like this: All homeservers MUST verify the signature in the event's `content.third_party_invite.signed` object. -The third party user will then need to verify their identity, which +The third-party user will then need to verify their identity, which results in a call from the identity server to the homeserver that bound -the third party identifier to a user. The homeserver then exchanges the +the third-party identifier to a user. The homeserver then exchanges the `m.room.third_party_invite` event in the room for a complete `m.room.member` event for `membership: invite` for the user that has -bound the third party identifier. +bound the third-party identifier. If a homeserver is joining a room for the first time because of an `m.room.third_party_invite`, the server which is already participating @@ -123,7 +123,7 @@ view of the room. They may, however, indicate to their clients that a member's membership is questionable. For example, given H1, H2, and H3 as homeservers, UserA as a user of H1, -and an identity server IS, the full sequence for a third party invite +and an identity server IS, the full sequence for a third-party invite would look like the following. This diagram assumes H1 and H2 are residents of the room while H3 is attempting to join. @@ -144,7 +144,7 @@ residents of the room while H3 is attempting to join. | | | POST /store-invite | | | | | |---------------------------------------------------------------------------------------------->| | | | | | | - | | | | Token, keys, etc for third party invite | + | | | | Token, keys, etc for third-party invite | | | |<----------------------------------------------------------------------------------------------| | | | | | | | | | (Federation) Emit m.room.third_party_invite | | | @@ -214,13 +214,13 @@ still be performed, so the attack surface here is minimized. There are a number of privacy and trust implications to this module. It is important for user privacy that leaking the mapping between a -matrix user ID and a third party identifier is hard. In particular, -being able to look up all third party identifiers from a matrix user ID -(and accordingly, being able to link each third party identifier) should -be avoided wherever possible. To this end, the third party identifier is +matrix user ID and a third-party identifier is hard. In particular, +being able to look up all third-party identifiers from a matrix user ID +(and accordingly, being able to link each third-party identifier) should +be avoided wherever possible. To this end, the third-party identifier is not put in any event, rather an opaque display name provided by the identity server is put into the events. Clients should not remember or -display third party identifiers from invites, other than for the use of +display third-party identifiers from invites, other than for the use of the inviter themself. Homeservers are not required to trust any particular identity server(s). diff --git a/content/client-server-api/modules/third_party_networks.md b/content/client-server-api/modules/third_party_networks.md index a0db5785..e4d9cf53 100644 --- a/content/client-server-api/modules/third_party_networks.md +++ b/content/client-server-api/modules/third_party_networks.md @@ -1,18 +1,18 @@ -### Third Party Networks +### Third-party Networks -Application services can provide access to third party networks via +Application services can provide access to third-party networks via bridging. This allows Matrix users to communicate with users on other communication platforms, with messages ferried back and forth by the application service. A single application service may bridge multiple -third party networks, and many individual locations within those -networks. A single third party network location may be bridged to +third-party networks, and many individual locations within those +networks. A single third-party network location may be bridged to multiple Matrix rooms. -#### Third Party Lookups +#### Third-party Lookups -A client may wish to provide a rich interface for joining third party -locations and connecting with third party users. Information necessary -for such an interface is provided by third party lookups. +A client may wish to provide a rich interface for joining third-party +locations and connecting with third-party users. Information necessary +for such an interface is provided by third-party lookups. {{% http-api spec="client-server" api="third_party_lookup" %}} diff --git a/content/identity-service-api.md b/content/identity-service-api.md index a9676120..9e2d5cdf 100644 --- a/content/identity-service-api.md +++ b/content/identity-service-api.md @@ -98,11 +98,11 @@ There was an error sending an email. Typically seen when attempting to verify ownership of a given email address. `M_INVALID_ADDRESS` -The provided third party address was not valid. +The provided third-party address was not valid. `M_SEND_ERROR` There was an error sending a notification. Typically seen when -attempting to verify ownership of a given third party address. +attempting to verify ownership of a given third-party address. `M_UNRECOGNIZED` The request contained an unrecognised value, such as an unknown token or @@ -114,9 +114,9 @@ not implemented or a 405 HTTP status code if the endpoint is implemented, but the incorrect HTTP method is used. `M_THREEPID_IN_USE` -The third party identifier is already in use by another user. Typically +The third-party identifier is already in use by another user. Typically this error will have an additional `mxid` property to indicate who owns -the third party identifier. +the third-party identifier. `M_UNKNOWN` An unknown error has occurred. @@ -369,7 +369,7 @@ To start a session, the client makes a request to the appropriate token to the user, and the user provides the token to the client. The client then provides the token to the appropriate `/submitToken` endpoint, completing the session. At this point, the client should -`/bind` the third party identifier or leave it for another entity to +`/bind` the third-party identifier or leave it for another entity to bind. ### Format of a validation token diff --git a/content/server-server-api.md b/content/server-server-api.md index bcf0db4e..ff14bd04 100644 --- a/content/server-server-api.md +++ b/content/server-server-api.md @@ -938,9 +938,9 @@ the event to other servers in the room. ## Third-party invites {{% boxes/note %}} -More information about third party invites is available in the +More information about third-party invites is available in the [Client-Server API](/client-server-api) under -the Third Party Invites module. +the Third-party Invites module. {{% /boxes/note %}} When a user wants to invite another user in a room but doesn't know the @@ -1076,7 +1076,7 @@ more specific queries that can be made. ## OpenID -Third party services can exchange an access token previously generated +Third-party services can exchange an access token previously generated by the Client-Server API for information about a user. This can help verify that a user is who they say they are without granting full access to the user's account. diff --git a/data/api/application-service/definitions/location.yaml b/data/api/application-service/definitions/location.yaml index 5a0f92c8..12cdad59 100644 --- a/data/api/application-service/definitions/location.yaml +++ b/data/api/application-service/definitions/location.yaml @@ -17,11 +17,11 @@ properties: type: string example: "#freenode_#matrix:matrix.org" protocol: - description: The protocol ID that the third party location is a part of. + description: The protocol ID that the third-party location is a part of. type: string example: "irc" fields: - description: Information used to identify this third party location. + description: Information used to identify this third-party location. type: object example: { "network": "freenode", diff --git a/data/api/application-service/definitions/location_batch.yaml b/data/api/application-service/definitions/location_batch.yaml index 3f6de9df..35875ddb 100644 --- a/data/api/application-service/definitions/location_batch.yaml +++ b/data/api/application-service/definitions/location_batch.yaml @@ -12,6 +12,6 @@ # See the License for the specific language governing permissions and # limitations under the License. type: array -description: List of matched third party locations. +description: List of matched third-party locations. items: $ref: location.yaml diff --git a/data/api/application-service/definitions/protocol.yaml b/data/api/application-service/definitions/protocol.yaml index b16eedfc..f29d72e8 100644 --- a/data/api/application-service/definitions/protocol.yaml +++ b/data/api/application-service/definitions/protocol.yaml @@ -16,28 +16,28 @@ type: object properties: user_fields: description: |- - Fields which may be used to identify a third party user. These should be + Fields which may be used to identify a third-party user. These should be ordered to suggest the way that entities may be grouped, where higher groupings are ordered first. For example, the name of a network should be searched before the nickname of a user. type: array items: type: string - description: Field used to identify a third party user. + description: Field used to identify a third-party user. example: ["network", "nickname"] location_fields: description: |- - Fields which may be used to identify a third party location. These should be + Fields which may be used to identify a third-party location. These should be ordered to suggest the way that entities may be grouped, where higher groupings are ordered first. For example, the name of a network should be searched before the name of a channel. type: array items: type: string - description: Field used to identify a third party location. + description: Field used to identify a third-party location. example: ["network", "channel"] icon: - description: A content URI representing an icon for the third party protocol. + description: A content URI representing an icon for the third-party protocol. type: string example: "mxc://example.org/aBcDeFgH" field_types: diff --git a/data/api/application-service/definitions/protocol_metadata.yaml b/data/api/application-service/definitions/protocol_metadata.yaml index e7bf45da..cd2af89f 100644 --- a/data/api/application-service/definitions/protocol_metadata.yaml +++ b/data/api/application-service/definitions/protocol_metadata.yaml @@ -12,7 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. type: object -description: Dictionary of supported third party protocols. +description: Dictionary of supported third-party protocols. additionalProperties: $ref: protocol.yaml example: { diff --git a/data/api/application-service/definitions/user.yaml b/data/api/application-service/definitions/user.yaml index 258e7c13..3178b56d 100644 --- a/data/api/application-service/definitions/user.yaml +++ b/data/api/application-service/definitions/user.yaml @@ -15,15 +15,15 @@ # TODO: Change userid to user_id as a breaking change properties: userid: - description: A Matrix User ID represting a third party user. + description: A Matrix User ID represting a third-party user. type: string example: "@_gitter_jim:matrix.org" protocol: - description: The protocol ID that the third party location is a part of. + description: The protocol ID that the third-party location is a part of. type: string example: "gitter" fields: - description: Information used to identify this third party location. + description: Information used to identify this third-party location. type: object example: { "user": "jim" diff --git a/data/api/application-service/definitions/user_batch.yaml b/data/api/application-service/definitions/user_batch.yaml index 3653feb4..f9885996 100644 --- a/data/api/application-service/definitions/user_batch.yaml +++ b/data/api/application-service/definitions/user_batch.yaml @@ -12,6 +12,6 @@ # See the License for the specific language governing permissions and # limitations under the License. type: array -description: List of matched third party users. +description: List of matched third-party users. items: $ref: user.yaml diff --git a/data/api/application-service/protocols.yaml b/data/api/application-service/protocols.yaml index b1e3ce6e..47f62b8f 100644 --- a/data/api/application-service/protocols.yaml +++ b/data/api/application-service/protocols.yaml @@ -32,7 +32,7 @@ paths: summary: Retrieve metadata about a specific protocol that the application service supports. description: |- This API is called by the homeserver when it wants to present clients - with specific information about the various third party networks that + with specific information about the various third-party networks that an application service supports. operationId: getProtocolMetadata security: @@ -78,10 +78,10 @@ paths: $ref: ../client-server/definitions/errors/error.yaml "/thirdparty/user/{protocol}": get: - summary: Retrieve the Matrix User ID of a corresponding third party user. + summary: Retrieve the Matrix User ID of a corresponding third-party user. description: |- This API is called by the homeserver in order to retrieve a Matrix - User ID linked to a user on the third party network, given a set of + User ID linked to a user on the third-party network, given a set of user parameters. operationId: queryUserByProtocol security: @@ -133,9 +133,9 @@ paths: $ref: ../client-server/definitions/errors/error.yaml "/thirdparty/location/{protocol}": get: - summary: Retrieve Matrix-side portal rooms leading to a third party location. + summary: Retrieve Matrix-side portal rooms leading to a third-party location. description: |- - Retrieve a list of Matrix portal rooms that lead to the matched third party location. + Retrieve a list of Matrix portal rooms that lead to the matched third-party location. operationId: queryLocationByProtocol security: - homeserverAccessToken: [] @@ -151,7 +151,7 @@ paths: type: string description: |- One or more custom fields that are passed to the application - service to help identify the third party location. + service to help identify the third-party location. responses: 200: description: At least one portal room was found. @@ -186,9 +186,9 @@ paths: $ref: ../client-server/definitions/errors/error.yaml "/thirdparty/location": get: - summary: Reverse-lookup third party locations given a Matrix room alias. + summary: Reverse-lookup third-party locations given a Matrix room alias. description: |- - Retrieve an array of third party network locations from a Matrix room + Retrieve an array of third-party network locations from a Matrix room alias. operationId: queryLocationByAlias security: @@ -201,7 +201,7 @@ paths: responses: 200: description: |- - All found third party locations. + All found third-party locations. schema: $ref: definitions/location_batch.yaml 401: @@ -233,9 +233,9 @@ paths: $ref: ../client-server/definitions/errors/error.yaml "/thirdparty/user": get: - summary: Reverse-lookup third party users given a Matrix User ID. + summary: Reverse-lookup third-party users given a Matrix User ID. description: |- - Retrieve an array of third party users from a Matrix User ID. + Retrieve an array of third-party users from a Matrix User ID. operationId: queryUserByID security: - homeserverAccessToken: [] @@ -247,7 +247,7 @@ paths: responses: 200: description: |- - An array of third party users. + An array of third-party users. schema: $ref: definitions/user_batch.yaml 401: diff --git a/data/api/client-server/administrative_contact.yaml b/data/api/client-server/administrative_contact.yaml index 8bee761f..fd6adc94 100644 --- a/data/api/client-server/administrative_contact.yaml +++ b/data/api/client-server/administrative_contact.yaml @@ -30,12 +30,12 @@ securityDefinitions: paths: "/account/3pid": get: - summary: Gets a list of a user's third party identifiers. + summary: Gets a list of a user's third-party identifiers. description: |- - Gets a list of the third party identifiers that the homeserver has + Gets a list of the third-party identifiers that the homeserver has associated with the user's account. - This is *not* the same as the list of third party identifiers bound to + This is *not* the same as the list of third-party identifiers bound to the user's Matrix ID in identity servers. Identifiers in this list may be used by the homeserver as, for example, @@ -64,15 +64,15 @@ paths: type: array items: type: object - title: Third party identifier + title: Third-party identifier properties: medium: type: string - description: The medium of the third party identifier. + description: The medium of the third-party identifier. enum: ["email", "msisdn"] address: type: string - description: The third party identifier address. + description: The third-party identifier address. validated_at: type: integer format: int64 @@ -84,7 +84,7 @@ paths: format: int64 description: The timestamp, in milliseconds, when the homeserver - associated the third party identifier with the user. + associated the third-party identifier with the user. required: ['medium', 'address', 'validated_at', 'added_at'] tags: - Account management @@ -115,7 +115,7 @@ paths: three_pid_creds: title: "ThreePidCredentials" type: object - description: The third party credentials to associate with the account. + description: The third-party credentials to associate with the account. properties: client_secret: type: string @@ -174,7 +174,7 @@ paths: examples: application/json: { "errcode": "M_THREEPID_AUTH_FAILED", - "error": "The third party credentials could not be verified by the identity server." + "error": "The third-party credentials could not be verified by the identity server." } schema: "$ref": "definitions/errors/error.yaml" @@ -290,9 +290,9 @@ paths: - Account management "/account/3pid/delete": post: - summary: Deletes a third party identifier from the user's account + summary: Deletes a third-party identifier from the user's account description: |- - Removes a third party identifier from the user's account. This might not + 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` @@ -318,18 +318,18 @@ paths: example: "example.org" medium: type: string - description: The medium of the third party identifier being removed. + description: The medium of the third-party identifier being removed. enum: ["email", "msisdn"] example: "email" address: type: string - description: The third party address being removed. + description: The third-party address being removed. example: "example@example.org" required: ['medium', 'address'] responses: 200: description: |- - The homeserver has disassociated the third party identifier from the + The homeserver has disassociated the third-party identifier from the user. schema: type: object @@ -355,9 +355,9 @@ paths: - Account management "/account/3pid/unbind": post: - summary: Removes a user's third party identifier from an identity server. + summary: Removes a user's third-party identifier from an identity server. description: |- - Removes a user's third party identifier from the provided identity server + 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` @@ -383,18 +383,18 @@ paths: example: "example.org" medium: type: string - description: The medium of the third party identifier being removed. + description: The medium of the third-party identifier being removed. enum: ["email", "msisdn"] example: "email" address: type: string - description: The third party address being removed. + description: The third-party address being removed. example: "example@example.org" required: ['medium', 'address'] responses: 200: description: |- - The identity server has disassociated the third party identifier from the + The identity server has disassociated the third-party identifier from the user. schema: type: object @@ -446,18 +446,18 @@ paths: $ref: "definitions/request_token_response.yaml" 403: description: |- - The homeserver does not allow the third party identifier as a + The homeserver does not allow the third-party identifier as a contact option. schema: $ref: "definitions/errors/error.yaml" examples: application/json: { "errcode": "M_THREEPID_DENIED", - "error": "Third party identifier is not allowed" + "error": "Third-party identifier is not allowed" } 400: description: |- - The third party identifier is already in use on the homeserver, or + The third-party identifier is already in use on the homeserver, or the request was invalid. The error code `M_SERVER_NOT_TRUSTED` can be returned if the server does not trust/support the identity server provided in the request. @@ -466,7 +466,7 @@ paths: examples: application/json: { "errcode": "M_THREEPID_IN_USE", - "error": "Third party identifier already in use" + "error": "Third-party identifier already in use" } tags: - Account management @@ -496,18 +496,18 @@ paths: $ref: "definitions/request_token_response.yaml" 403: description: |- - The homeserver does not allow the third party identifier as a + The homeserver does not allow the third-party identifier as a contact option. schema: $ref: "definitions/errors/error.yaml" examples: application/json: { "errcode": "M_THREEPID_DENIED", - "error": "Third party identifier is not allowed" + "error": "Third-party identifier is not allowed" } 400: description: |- - The third party identifier is already in use on the homeserver, or + The third-party identifier is already in use on the homeserver, or the request was invalid. The error code `M_SERVER_NOT_TRUSTED` can be returned if the server does not trust/support the identity server provided in the request. @@ -516,7 +516,7 @@ paths: examples: application/json: { "errcode": "M_THREEPID_IN_USE", - "error": "Third party identifier already in use" + "error": "Third-party identifier already in use" } tags: - Account management diff --git a/data/api/client-server/create_room.yaml b/data/api/client-server/create_room.yaml index 07d9c0af..a39cc4f5 100644 --- a/data/api/client-server/create_room.yaml +++ b/data/api/client-server/create_room.yaml @@ -138,7 +138,7 @@ paths: invite_3pid: type: array description: |- - A list of objects representing third party IDs to invite into + A list of objects representing third-party IDs to invite into the room. items: type: object @@ -146,7 +146,7 @@ paths: properties: id_server: type: string - description: The hostname+port of the identity server which should be used for third party identifier lookups. + description: The hostname+port of the identity server which should be used for third-party identifier lookups. id_access_token: type: string description: |- @@ -160,7 +160,7 @@ paths: (see [the list of recognised values](/appendices/#3pid-types)). address: type: string - description: The invitee's third party identifier. + description: The invitee's third-party identifier. required: ["id_server", "id_access_token", "medium", "address"] room_version: type: string diff --git a/data/api/client-server/definitions/third_party_signed.yaml b/data/api/client-server/definitions/third_party_signed.yaml index 4af422b4..071d9491 100644 --- a/data/api/client-server/definitions/third_party_signed.yaml +++ b/data/api/client-server/definitions/third_party_signed.yaml @@ -12,10 +12,10 @@ # See the License for the specific language governing permissions and # limitations under the License. type: object -title: Third Party Signed +title: Third-party Signed description: |- 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. + owns a third-party identity which has been invited to the room. properties: sender: type: string diff --git a/data/api/client-server/inviting.yaml b/data/api/client-server/inviting.yaml index 96e3dae2..53439e95 100644 --- a/data/api/client-server/inviting.yaml +++ b/data/api/client-server/inviting.yaml @@ -36,7 +36,7 @@ paths: *Note that there are two forms of this API, which are documented separately. This version of the API requires that the inviter knows the Matrix identifier of the invitee. The other is documented in the - [third party invites](/client-server-api/#third-party-invites) section.* + [third-party invites](/client-server-api/#third-party-invites) section.* This API invites a user to participate in a particular room. They do not start participating in the room until they actually join the diff --git a/data/api/client-server/list_public_rooms.yaml b/data/api/client-server/list_public_rooms.yaml index 6391bbbd..185a955e 100644 --- a/data/api/client-server/list_public_rooms.yaml +++ b/data/api/client-server/list_public_rooms.yaml @@ -219,7 +219,7 @@ paths: third_party_instance_id: type: string description: |- - The specific third party network/protocol to request from the + The specific third-party network/protocol to request from the homeserver. Can only be used if `include_all_networks` is false. example: "irc" example: { diff --git a/data/api/client-server/login.yaml b/data/api/client-server/login.yaml index 4c348fcd..7c33d1a4 100644 --- a/data/api/client-server/login.yaml +++ b/data/api/client-server/login.yaml @@ -107,10 +107,10 @@ paths: 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: |- diff --git a/data/api/client-server/registration.yaml b/data/api/client-server/registration.yaml index f48385e9..9fe4d4ad 100644 --- a/data/api/client-server/registration.yaml +++ b/data/api/client-server/registration.yaml @@ -272,7 +272,7 @@ paths: examples: application/json: { "errcode": "M_THREEPID_DENIED", - "error": "Third party identifier is not allowed" + "error": "Third-party identifier is not allowed" } 400: description: |- @@ -324,7 +324,7 @@ paths: examples: application/json: { "errcode": "M_THREEPID_DENIED", - "error": "Third party identifier is not allowed" + "error": "Third-party identifier is not allowed" } 400: description: |- @@ -443,18 +443,18 @@ paths: $ref: "definitions/request_token_response.yaml" 403: description: |- - The homeserver does not allow the third party identifier as a + The homeserver does not allow the third-party identifier as a contact option. schema: $ref: "definitions/errors/error.yaml" examples: application/json: { "errcode": "M_THREEPID_DENIED", - "error": "Third party identifier is not allowed" + "error": "Third-party identifier is not allowed" } 400: description: |- - The referenced third party identifier is not recognised by the + The referenced third-party identifier is not recognised by the homeserver, or the request was invalid. The error code `M_SERVER_NOT_TRUSTED` can be returned if the server does not trust/support the identity server provided in the request. @@ -500,18 +500,18 @@ paths: $ref: "definitions/request_token_response.yaml" 403: description: |- - The homeserver does not allow the third party identifier as a + The homeserver does not allow the third-party identifier as a contact option. schema: $ref: "definitions/errors/error.yaml" examples: application/json: { "errcode": "M_THREEPID_DENIED", - "error": "Third party identifier is not allowed" + "error": "Third-party identifier is not allowed" } 400: description: |- - The referenced third party identifier is not recognised by the + The referenced third-party identifier is not recognised by the homeserver, or the request was invalid. The error code `M_SERVER_NOT_TRUSTED` can be returned if the server does not trust/support the identity server provided in the request. diff --git a/data/api/client-server/third_party_lookup.yaml b/data/api/client-server/third_party_lookup.yaml index f56554e3..ba368459 100644 --- a/data/api/client-server/third_party_lookup.yaml +++ b/data/api/client-server/third_party_lookup.yaml @@ -13,7 +13,7 @@ # limitations under the License. swagger: '2.0' info: - title: "Matrix Client-Server Third Party Lookup API" + title: "Matrix Client-Server Third-party Lookup API" version: "1.0.0" host: localhost:8008 schemes: @@ -43,12 +43,12 @@ paths: schema: $ref: ../application-service/definitions/protocol_metadata.yaml tags: - - Third Party Lookup + - Third-party Lookup "/thirdparty/protocol/{protocol}": get: summary: Retrieve metadata about a specific protocol that the homeserver supports. description: |- - Fetches the metadata from the homeserver about a particular third party protocol. + Fetches the metadata from the homeserver about a particular third-party protocol. operationId: getProtocolMetadata security: - accessToken: [] @@ -74,16 +74,16 @@ paths: schema: $ref: definitions/errors/error.yaml tags: - - Third Party Lookup + - Third-party Lookup "/thirdparty/location/{protocol}": get: - summary: Retrieve Matrix-side portals rooms leading to a third party location. + summary: Retrieve Matrix-side portals rooms leading to a third-party location. description: |- Requesting this endpoint with a valid protocol name results in a list of successful mapping results in a JSON array. Each result contains objects to represent the Matrix room or rooms that represent a portal - to this third party network. Each has the Matrix room alias string, - an identifier for the particular third party network protocol, and an + to this third-party network. Each has the Matrix room alias string, + an identifier for the particular third-party network protocol, and an object containing the network-specific fields that comprise this identifier. It should attempt to canonicalise the identifier as much as reasonably possible given the network type. @@ -94,14 +94,14 @@ paths: - in: path name: protocol type: string - description: The protocol used to communicate to the third party network. + description: The protocol used to communicate to the third-party network. required: true x-example: irc - in: query name: searchFields type: string description: |- - One or more custom fields to help identify the third party + One or more custom fields to help identify the third-party location. responses: 200: @@ -117,12 +117,12 @@ paths: schema: $ref: definitions/errors/error.yaml tags: - - Third Party Lookup + - Third-party Lookup "/thirdparty/user/{protocol}": get: - summary: Retrieve the Matrix User ID of a corresponding third party user. + summary: Retrieve the Matrix User ID of a corresponding third-party user. description: |- - Retrieve a Matrix User ID linked to a user on the third party service, given + Retrieve a Matrix User ID linked to a user on the third-party service, given a set of user parameters. operationId: queryUserByProtocol security: @@ -154,12 +154,12 @@ paths: schema: $ref: definitions/errors/error.yaml tags: - - Third Party Lookup + - Third-party Lookup "/thirdparty/location": get: - summary: Reverse-lookup third party locations given a Matrix room alias. + summary: Reverse-lookup third-party locations given a Matrix room alias. description: |- - Retrieve an array of third party network locations from a Matrix room + Retrieve an array of third-party network locations from a Matrix room alias. operationId: queryLocationByAlias security: @@ -174,7 +174,7 @@ paths: responses: 200: description: |- - All found third party locations. + All found third-party locations. schema: $ref: ../application-service/definitions/location_batch.yaml 404: @@ -186,12 +186,12 @@ paths: schema: $ref: definitions/errors/error.yaml tags: - - Third Party Lookup + - Third-party Lookup "/thirdparty/user": get: - summary: Reverse-lookup third party users given a Matrix User ID. + summary: Reverse-lookup third-party users given a Matrix User ID. description: |- - Retrieve an array of third party users from a Matrix User ID. + Retrieve an array of third-party users from a Matrix User ID. operationId: queryUserByID security: - accessToken: [] @@ -205,7 +205,7 @@ paths: responses: 200: description: |- - An array of third party users. + An array of third-party users. schema: $ref: ../application-service/definitions/user_batch.yaml 404: @@ -217,4 +217,4 @@ paths: schema: $ref: definitions/errors/error.yaml tags: - - Third Party Lookup + - Third-party Lookup diff --git a/data/api/client-server/third_party_membership.yaml b/data/api/client-server/third_party_membership.yaml index 27bcad37..c6ce230e 100644 --- a/data/api/client-server/third_party_membership.yaml +++ b/data/api/client-server/third_party_membership.yaml @@ -13,7 +13,7 @@ # limitations under the License. swagger: '2.0' info: - title: "Matrix Client-Server Room Membership API for third party identifiers" + title: "Matrix Client-Server Room Membership API for third-party identifiers" version: "1.0.0" host: localhost:8008 schemes: @@ -33,9 +33,9 @@ paths: description: |- *Note that there are two forms of this API, which are documented separately. This version of the API does not require that the inviter know the Matrix - identifier of the invitee, and instead relies on third party identifiers. + identifier of the invitee, and instead relies on third-party identifiers. The homeserver uses an identity server to perform the mapping from - third party identifier to a Matrix identifier. The other is documented in the* + third-party identifier to a Matrix identifier. The other is documented in the* [joining rooms section](/client-server-api/#post_matrixclientv3roomsroomidinvite). This API invites a user to participate in a particular room. @@ -46,18 +46,18 @@ 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 - passed third party identifier, the homeserver will issue an invitation - which can be accepted upon providing proof of ownership of the third + passed third-party identifier, the homeserver will issue an invitation + 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, containing that token. - When the invitee binds the invited third party identifier to a Matrix + When the invitee binds the invited third-party identifier to a Matrix user ID, the identity server will give the user a list of pending invitations, each containing: @@ -96,7 +96,7 @@ paths: properties: id_server: type: string - description: The hostname+port of the identity server which should be used for third party identifier lookups. + description: The hostname+port of the identity server which should be used for third-party identifier lookups. id_access_token: type: string description: |- @@ -110,7 +110,7 @@ paths: `email` (see [the list of recognised values](/appendices/#3pid-types)). address: type: string - description: The invitee's third party identifier. + description: The invitee's third-party identifier. required: ["id_server", "id_access_token", "medium", "address"] responses: 200: diff --git a/data/api/server-server/public_rooms.yaml b/data/api/server-server/public_rooms.yaml index c65a649a..3079b7c2 100644 --- a/data/api/server-server/public_rooms.yaml +++ b/data/api/server-server/public_rooms.yaml @@ -60,7 +60,7 @@ paths: name: third_party_instance_id type: string description: |- - The specific third party network/protocol to request from the homeserver. + The specific third-party network/protocol to request from the homeserver. Can only be used if `include_all_networks` is false. x-example: "irc" responses: @@ -131,7 +131,7 @@ paths: third_party_instance_id: type: string description: |- - The specific third party network/protocol to request from the + The specific third-party network/protocol to request from the homeserver. Can only be used if `include_all_networks` is false. example: "irc" example: { diff --git a/data/api/server-server/third_party_invite.yaml b/data/api/server-server/third_party_invite.yaml index 9a636aa9..55e4d628 100644 --- a/data/api/server-server/third_party_invite.yaml +++ b/data/api/server-server/third_party_invite.yaml @@ -14,7 +14,7 @@ swagger: '2.0' info: - title: "Matrix Federation Third Party Invites API" + title: "Matrix Federation Third-party Invites API" version: "1.0.0" host: localhost:8448 schemes: @@ -29,7 +29,7 @@ securityDefinitions: paths: "/exchange_third_party_invite/{roomId}": put: - summary: Request a server to auth a third party invite event + summary: Request a server to auth a third-party invite event description: |- The receiving server will verify the partial `m.room.member` event given in the request body. If valid, the receiving server will issue @@ -42,7 +42,7 @@ paths: - in: path name: roomId type: string - description: The room ID to exchange a third party invite in + description: The room ID to exchange a third-party invite in required: true x-example: "!abc123:matrix.org" - in: body @@ -84,14 +84,14 @@ paths: example: invite third_party_invite: type: object - description: The third party invite - title: Third Party Invite + description: The third-party invite + title: Third-party Invite properties: display_name: type: string description: |- A name which can be displayed to represent the user instead of their - third party identifier. + third-party identifier. example: "alice" signed: type: object @@ -203,11 +203,11 @@ paths: "/3pid/onbind": put: summary: |- - Notifies the server that a third party identifier has been bound to one + Notifies the server that a third-party identifier has been bound to one of its users. description: |- Used by identity servers to notify the homeserver that one of its users - has bound a third party identifier successfully, including any pending + has bound a third-party identifier successfully, including any pending room invites the identity server has been made aware of. operationId: onBindThirdPartyIdentifier parameters: @@ -221,36 +221,36 @@ paths: medium: type: string description: |- - The type of third party identifier. Currently only "email" is + The type of third-party identifier. Currently only "email" is a possible value. example: "email" address: type: string description: |- - The third party identifier itself. For example, an email address. + The third-party identifier itself. For example, an email address. example: "alice@example.com" mxid: type: string - description: The user that is now bound to the third party identifier. + description: The user that is now bound to the third-party identifier. example: "@alice:matrix.org" invites: type: array description: |- - A list of pending invites that the third party identifier has received. + A list of pending invites that the third-party identifier has received. items: type: object - title: Third Party Invite + title: Third-party Invite properties: medium: type: string description: |- - The type of third party invite issues. Currently only + The type of third-party invite issues. Currently only "email" is used. example: "email" address: type: string description: |- - The third party identifier that received the invite. + The third-party identifier that received the invite. example: "alice@example.com" mxid: type: string @@ -276,7 +276,7 @@ paths: mxid: type: string description: |- - The user ID that has been bound to the third party + The user ID that has been bound to the third-party identifier. example: "@alice:matrix.org" token: diff --git a/data/event-schemas/schema/m.room.member.yaml b/data/event-schemas/schema/m.room.member.yaml index bf2f7145..24b6005f 100644 --- a/data/event-schemas/schema/m.room.member.yaml +++ b/data/event-schemas/schema/m.room.member.yaml @@ -88,7 +88,7 @@ properties: third_party_invite: properties: display_name: - description: A name which can be displayed to represent the user instead of their third party identifier + description: A name which can be displayed to represent the user instead of their third-party identifier type: string signed: description: 'A block of content which has been signed, which servers can use to verify the event. Clients should ignore this.' 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 f4188192..7a00616b 100644 --- a/data/event-schemas/schema/m.room.third_party_invite.yaml +++ b/data/event-schemas/schema/m.room.third_party_invite.yaml @@ -7,7 +7,7 @@ properties: content: properties: display_name: - description: "A user-readable string which represents the user who has been invited. This should not contain the user's third party ID, as otherwise when the invite is accepted it would leak the association between the matrix ID and the third party ID." + description: "A user-readable string which represents the user who has been invited. This should not contain the user's third-party ID, as otherwise when the invite is accepted it would leak the association between the matrix ID and the third-party ID." type: string key_validity_url: description: "A URL which can be fetched, with querystring public_key=public_key, to validate whether the key has been revoked. The URL must return a JSON object containing a boolean property named 'valid'." @@ -42,5 +42,5 @@ properties: enum: - m.room.third_party_invite type: string -title: 'An invitation to a room issued to a third party identifier, rather than a matrix user ID.' +title: 'An invitation to a room issued to a third-party identifier, rather than a matrix user ID.' type: object