-
-
Notifications
You must be signed in to change notification settings - Fork 103
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Document the instance_id field of Protocol Instance
It is used as the `third_party_instance_id` of `POST /_matrix/client/v3/publicRooms`. It has always been present since before the thirdparty protocol endpoints were added to the spec. Signed-off-by: Kévin Commaille <[email protected]>
- Loading branch information
Showing
8 changed files
with
188 additions
and
104 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
80 changes: 80 additions & 0 deletions
80
data/api/application-service/definitions/protocol_base.yaml
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,80 @@ | ||
| # Copyright 2018 New Vector Ltd | ||
| # | ||
| # Licensed under the Apache License, Version 2.0 (the "License"); | ||
| # you may not use this file except in compliance with the License. | ||
| # You may obtain a copy of the License at | ||
| # | ||
| # http://www.apache.org/licenses/LICENSE-2.0 | ||
| # | ||
| # Unless required by applicable law or agreed to in writing, software | ||
| # distributed under the License is distributed on an "AS IS" BASIS, | ||
| # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
| # See the License for the specific language governing permissions and | ||
| # limitations under the License. | ||
| title: Protocol | ||
| type: object | ||
| properties: | ||
| user_fields: | ||
| description: |- | ||
| 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. | ||
| example: ["network", "nickname"] | ||
| location_fields: | ||
| description: |- | ||
| 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. | ||
| example: ["network", "channel"] | ||
| icon: | ||
| description: A content URI representing an icon for the third-party protocol. | ||
| type: string | ||
| example: "mxc://example.org/aBcDeFgH" | ||
| field_types: | ||
| description: |- | ||
| The type definitions for the fields defined in `user_fields` and | ||
| `location_fields`. Each entry in those arrays MUST have an entry here. | ||
| The `string` key for this object is the field name itself. | ||
| May be an empty object if no fields are defined. | ||
| type: object | ||
| additionalProperties: | ||
| title: Field Type | ||
| description: Definition of valid values for a field. | ||
| type: object | ||
| properties: | ||
| regexp: | ||
| description: |- | ||
| A regular expression for validation of a field's value. This may be relatively | ||
| coarse to verify the value as the application service providing this protocol | ||
| may apply additional validation or filtering. | ||
| type: string | ||
| placeholder: | ||
| description: A placeholder serving as a valid example of the field value. | ||
| type: string | ||
| required: ['regexp', 'placeholder'] | ||
| example: { | ||
| "network": { | ||
| "regexp": "([a-z0-9]+\\.)*[a-z0-9]+", | ||
| "placeholder": "irc.example.org" | ||
| }, | ||
| "nickname": { | ||
| "regexp": "[^\\s#]+", | ||
| "placeholder": "username" | ||
| }, | ||
| "channel": { | ||
| "regexp": "#[^\\s]+", | ||
| "placeholder": "#foobar" | ||
| } | ||
| } | ||
| required: ['user_fields', 'location_fields', 'icon', 'field_types', 'instances'] |
37 changes: 37 additions & 0 deletions
37
data/api/application-service/definitions/protocol_instance.yaml
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,37 @@ | ||
| # Copyright 2018 New Vector Ltd | ||
| # | ||
| # Licensed under the Apache License, Version 2.0 (the "License"); | ||
| # you may not use this file except in compliance with the License. | ||
| # You may obtain a copy of the License at | ||
| # | ||
| # http://www.apache.org/licenses/LICENSE-2.0 | ||
| # | ||
| # Unless required by applicable law or agreed to in writing, software | ||
| # distributed under the License is distributed on an "AS IS" BASIS, | ||
| # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
| # See the License for the specific language governing permissions and | ||
| # limitations under the License. | ||
| type: object | ||
| title: Protocol Instance | ||
| properties: | ||
| desc: | ||
| type: string | ||
| description: A human-readable description for the protocol, such as the name. | ||
| example: "Freenode" | ||
| icon: | ||
| type: string | ||
| description: |- | ||
| An optional content URI representing the protocol. Overrides the one provided | ||
| at the higher level Protocol object. | ||
| example: "mxc://example.org/JkLmNoPq" | ||
| fields: | ||
| type: object | ||
| description: Preset values for `fields` the client may use to search by. | ||
| example: { | ||
| "network": "freenode" | ||
| } | ||
| network_id: | ||
| type: string | ||
| description: A unique identifier across all instances. | ||
| example: "freenode" | ||
| required: ['desc', 'fields', 'network_id'] |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,44 @@ | ||
| # Copyright 2018 New Vector Ltd | ||
| # | ||
| # Licensed under the Apache License, Version 2.0 (the "License"); | ||
| # you may not use this file except in compliance with the License. | ||
| # You may obtain a copy of the License at | ||
| # | ||
| # http://www.apache.org/licenses/LICENSE-2.0 | ||
| # | ||
| # Unless required by applicable law or agreed to in writing, software | ||
| # distributed under the License is distributed on an "AS IS" BASIS, | ||
| # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
| # See the License for the specific language governing permissions and | ||
| # limitations under the License. | ||
| allOf: | ||
| - $ref: ../../application-service/definitions/protocol_base.yaml | ||
| - type: object | ||
| properties: | ||
| instances: | ||
| description: |- | ||
| A list of objects representing independent instances of configuration. | ||
| For example, multiple networks on IRC if multiple are provided by the | ||
| same application service. | ||
| The instances are modified by the homeserver from the response of | ||
| [`GET /_matrix/app/v1/thirdparty/protocol/{protocol}`](/application-service-api/#get_matrixappv1thirdpartyprotocolprotocol) | ||
| to include an `instance_id` to serve as a unique identifier for each | ||
| instance on the homeserver. | ||
| type: array | ||
| items: | ||
| allOf: | ||
| - $ref: ../../application-service/definitions/protocol_instance.yaml | ||
| - type: object | ||
| properties: | ||
| instance_id: | ||
| type: string | ||
| description: |- | ||
| A unique identifier for this instance on the homeserver. This field is added | ||
| to the response of [`GET /_matrix/app/v1/thirdparty/protocol/{protocol}`](/application-service-api/#get_matrixappv1thirdpartyprotocolprotocol) | ||
| by the homeserver. | ||
| This is the identifier to use as the `third_party_instance_id` in a request to | ||
| [`POST /_matrix/client/v3/publicRooms`](/client-server-api/#post_matrixclientv3publicrooms). | ||
| example: "irc-freenode" | ||
| required: ['desc', 'fields', 'network_id', 'instance_id'] |
File renamed without changes.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters