wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Document instance_id field of /thirdparty/protocols (#2051)

Browse source 
Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
This commit is contained in:
Kévin Commaille 2025-02-13 18:29:56 +01:00 • committed by GitHub
parent dcb39c603a
commit c2ef38f0e5
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
9 changed files with 247 additions and 174 deletions
Download patch file Download diff file Expand all files Collapse all files

110
data/api/application-service/definitions/protocol.yaml
View file

@ -11,101 +11,15 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
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"
}
}
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.
type: array
items:
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']
required: ['user_fields', 'location_fields', 'icon', 'field_types', 'instances']
allOf:
- $ref: 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.
type: array
items:
$ref: protocol_instance.yaml

80
data/api/application-service/definitions/protocol_base.yaml Normal file
View file

@ -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
data/api/application-service/definitions/protocol_instance.yaml Normal file
View file

@ -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']

70
data/api/application-service/definitions/protocol_metadata.yaml
View file

@ -1,70 +0,0 @@
# 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
description: Dictionary of supported third-party protocols.
additionalProperties:
$ref: protocol.yaml
example: {
"irc": {
"user_fields": ["network", "nickname"],
"location_fields": ["network", "channel"],
"icon": "mxc://example.org/aBcDeFgH",
"field_types": {
"network": {
"regexp": "([a-z0-9]+\\.)*[a-z0-9]+",
"placeholder": "irc.example.org"
},
"nickname": {
"regexp": "[^\\s]+",
"placeholder": "username"
},
"channel": {
"regexp": "#[^\\s]+",
"placeholder": "#foobar"
}
},
"instances": [
{
"network_id": "freenode",
"desc": "Freenode",
"icon": "mxc://example.org/JkLmNoPq",
"fields": {
"network": "freenode.net",
}
}
]
},
"gitter": {
"user_fields": ["username"],
"location_fields": ["room"],
"field_types": {
"username": {
"regexp": "@[^\\s]+",
"placeholder": "@username"
},
"room": {
"regexp": "[^\\s]+\\/[^\\s]+",
"placeholder": "matrix-org/matrix-doc"
}
},
"instances": [
{
"network_id": "gitter",
"desc": "Gitter",
"icon": "mxc://example.org/zXyWvUt",
"fields": {}
}
]
}
}

43
data/api/client-server/definitions/protocol.yaml Normal file
View file

@ -0,0 +1,43 @@
# 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"

5
data/api/client-server/list_public_rooms.yaml
View file

@ -233,6 +233,9 @@ paths:
description: |-
The specific third-party network/protocol to request from the
homeserver. Can only be used if `include_all_networks` is false.
This is the `instance_id` of a `Protocol Instance` returned by
[`GET /_matrix/client/v3/thirdparty/protocols`](/client-server-api/#get_matrixclientv3thirdpartyprotocols).
example: irc
example: {
"limit": 10,
@ -244,7 +247,7 @@ paths:
]
},
"include_all_networks": false,
"third_party_instance_id": "irc"
"third_party_instance_id": "irc-freenode"
}
description: Options for which rooms to return.
required: true

62
data/api/client-server/third_party_lookup.yaml
View file

@ -33,7 +33,65 @@ paths:
content:
application/json:
schema:
$ref: ../application-service/definitions/protocol_metadata.yaml
type: object
description: Dictionary of supported third-party protocols.
additionalProperties:
$ref: definitions/protocol.yaml
example: {
"irc": {
"user_fields": ["network", "nickname"],
"location_fields": ["network", "channel"],
"icon": "mxc://example.org/aBcDeFgH",
"field_types": {
"network": {
"regexp": "([a-z0-9]+\\.)*[a-z0-9]+",
"placeholder": "irc.example.org"
},
"nickname": {
"regexp": "[^\\s]+",
"placeholder": "username"
},
"channel": {
"regexp": "#[^\\s]+",
"placeholder": "#foobar"
}
},
"instances": [
{
"network_id": "freenode",
"desc": "Freenode",
"icon": "mxc://example.org/JkLmNoPq",
"instance_id": "irc-freenode",
"fields": {
"network": "freenode.net"
}
}
]
},
"gitter": {
"user_fields": ["username"],
"location_fields": ["room"],
"field_types": {
"username": {
"regexp": "@[^\\s]+",
"placeholder": "@username"
},
"room": {
"regexp": "[^\\s]+\\/[^\\s]+",
"placeholder": "matrix-org/matrix-doc"
}
},
"instances": [
{
"network_id": "gitter",
"desc": "Gitter",
"icon": "mxc://example.org/zXyWvUt",
"instance_id": "gitter-gitter",
"fields": {}
}
]
}
}
tags:
- Third-party Lookup
"/thirdparty/protocol/{protocol}":
@ -59,7 +117,7 @@ paths:
content:
application/json:
schema:
$ref: ../application-service/definitions/protocol.yaml
$ref: definitions/protocol.yaml
"404":
description: The protocol is unknown.
content:

12
data/api/server-server/public_rooms.yaml
View file

@ -54,7 +54,10 @@ paths:
description: |-
The specific third-party network/protocol to request from the homeserver.
Can only be used if `include_all_networks` is false.
example: irc
This is the `instance_id` of a `Protocol Instance` returned by
[`GET /_matrix/client/v3/thirdparty/protocols`](/client-server-api/#get_matrixclientv3thirdpartyprotocols).
example: irc-freenode
schema:
type: string
responses:
@ -124,7 +127,10 @@ paths:
description: |-
The specific third-party network/protocol to request from the
homeserver. Can only be used if `include_all_networks` is false.
example: irc
This is the `instance_id` of a `Protocol Instance` returned by
[`GET /_matrix/client/v3/thirdparty/protocols`](/client-server-api/#get_matrixclientv3thirdpartyprotocols).
example: irc-freenode
example: {
"limit": 10,
"filter": {
@ -135,7 +141,7 @@ paths:
]
},
"include_all_networks": false,
"third_party_instance_id": "irc"
"third_party_instance_id": "irc-freenode"
}
description: Options for which rooms to return, or empty object to use defaults.
required: true