From 36fcb6b1ef487f837488f9544c8c7b423594b9ef Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Mon, 13 Jan 2025 12:44:32 +0100 Subject: [PATCH] Document the instance_id field of Protocol Instance MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- .../definitions/protocol.yaml | 110 ++---------------- .../definitions/protocol_base.yaml | 80 +++++++++++++ .../definitions/protocol_instance.yaml | 37 ++++++ .../client-server/definitions/protocol.yaml | 44 +++++++ .../definitions/protocol_metadata.yaml | 0 data/api/client-server/list_public_rooms.yaml | 5 +- .../api/client-server/third_party_lookup.yaml | 4 +- data/api/server-server/public_rooms.yaml | 12 +- 8 files changed, 188 insertions(+), 104 deletions(-) create mode 100644 data/api/application-service/definitions/protocol_base.yaml create mode 100644 data/api/application-service/definitions/protocol_instance.yaml create mode 100644 data/api/client-server/definitions/protocol.yaml rename data/api/{application-service => client-server}/definitions/protocol_metadata.yaml (100%) diff --git a/data/api/application-service/definitions/protocol.yaml b/data/api/application-service/definitions/protocol.yaml index ff6300dbd..eb56ab26b 100644 --- a/data/api/application-service/definitions/protocol.yaml +++ b/data/api/application-service/definitions/protocol.yaml @@ -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 diff --git a/data/api/application-service/definitions/protocol_base.yaml b/data/api/application-service/definitions/protocol_base.yaml new file mode 100644 index 000000000..0238104fb --- /dev/null +++ b/data/api/application-service/definitions/protocol_base.yaml @@ -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'] diff --git a/data/api/application-service/definitions/protocol_instance.yaml b/data/api/application-service/definitions/protocol_instance.yaml new file mode 100644 index 000000000..ef8f25661 --- /dev/null +++ b/data/api/application-service/definitions/protocol_instance.yaml @@ -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'] diff --git a/data/api/client-server/definitions/protocol.yaml b/data/api/client-server/definitions/protocol.yaml new file mode 100644 index 000000000..9bfd579a7 --- /dev/null +++ b/data/api/client-server/definitions/protocol.yaml @@ -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'] diff --git a/data/api/application-service/definitions/protocol_metadata.yaml b/data/api/client-server/definitions/protocol_metadata.yaml similarity index 100% rename from data/api/application-service/definitions/protocol_metadata.yaml rename to data/api/client-server/definitions/protocol_metadata.yaml diff --git a/data/api/client-server/list_public_rooms.yaml b/data/api/client-server/list_public_rooms.yaml index 497ccb443..ffd202a48 100644 --- a/data/api/client-server/list_public_rooms.yaml +++ b/data/api/client-server/list_public_rooms.yaml @@ -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 diff --git a/data/api/client-server/third_party_lookup.yaml b/data/api/client-server/third_party_lookup.yaml index 3055b8aec..a13a8137c 100644 --- a/data/api/client-server/third_party_lookup.yaml +++ b/data/api/client-server/third_party_lookup.yaml @@ -33,7 +33,7 @@ paths: content: application/json: schema: - $ref: ../application-service/definitions/protocol_metadata.yaml + $ref: definitions/protocol_metadata.yaml tags: - Third-party Lookup "/thirdparty/protocol/{protocol}": @@ -59,7 +59,7 @@ paths: content: application/json: schema: - $ref: ../application-service/definitions/protocol.yaml + $ref: definitions/protocol.yaml "404": description: The protocol is unknown. content: diff --git a/data/api/server-server/public_rooms.yaml b/data/api/server-server/public_rooms.yaml index 5bfa0f71f..565f1aa45 100644 --- a/data/api/server-server/public_rooms.yaml +++ b/data/api/server-server/public_rooms.yaml @@ -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