2d43ff1234
Some information was missed when this was reviewed. This commit adds some additional documentation for how these objects interact with each other.
113 lines
4.1 KiB
YAML
113 lines
4.1 KiB
YAML
# 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:
|
|
title: Field Types
|
|
description: |-
|
|
The type definitions for the fields defined in the ``user_fields`` and
|
|
``location_fields``. Each entry in those arrays MUST have an entry here. The
|
|
``string`` key for this object is field name itself.
|
|
|
|
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: An placeholder serving as a valid example of the field value.
|
|
type: string
|
|
required: ['regexp', 'placeholder']
|
|
required: ['fieldname']
|
|
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']
|