1 files changed, 36 insertions, 17 deletions

diff --git a/lib/application-service/definitions/protocol.h b/lib/application-service/definitions/protocol.h
index 4aa400ab..2aca7d66 100644
--- a/lib/application-service/definitions/protocol.h
+++ b/lib/application-service/definitions/protocol.h
@@ -6,9 +6,10 @@
 
 #include "converters.h"
 
+#include <QtCore/QHash>
 #include <QtCore/QJsonObject>
-#include <QtCore/QVector>
 #include "converters.h"
+#include <QtCore/QVector>
 
 namespace QMatrixClient
 {
@@ -17,7 +18,9 @@ namespace QMatrixClient
     /// Definition of valid values for a field.
     struct FieldType
     {
-        /// A regular expression for validation of a field's value.
+        /// 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.
         QString regexp;
         /// An placeholder serving as a valid example of the field value.
         QString placeholder;
@@ -30,34 +33,50 @@ namespace QMatrixClient
         FieldType operator()(const QJsonObject& jo) const;
     };
 
-    /// All location or user fields should have an entry here.
-    struct FieldTypes
+    struct ProtocolInstance
     {
-        /// Definition of valid values for a field.
-        Omittable<FieldType> fieldname;
+        /// A human-readable description for the protocol, such as the name.
+        QString desc;
+        /// An optional content URI representing the protocol. Overrides the one provided
+        /// at the higher level Protocol object.
+        QString icon;
+        /// Preset values for ``fields`` the client may use to search by.
+        QJsonObject fields;
+        /// A unique identifier across all instances.
+        QString networkId;
     };
 
-    QJsonObject toJson(const FieldTypes& pod);
+    QJsonObject toJson(const ProtocolInstance& pod);
 
-    template <> struct FromJsonObject<FieldTypes>
+    template <> struct FromJsonObject<ProtocolInstance>
     {
-        FieldTypes operator()(const QJsonObject& jo) const;
+        ProtocolInstance operator()(const QJsonObject& jo) const;
     };
 
     struct ThirdPartyProtocol
     {
-        /// Fields used to identify a third party user.
+        /// 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.
         QStringList userFields;
-        /// Fields used to identify a third party location.
+        /// 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.
         QStringList locationFields;
-        /// An icon representing the third party protocol.
+        /// A content URI representing an icon for the third party protocol.
         QString icon;
-        /// All location or user fields should have an entry here.
-        Omittable<FieldTypes> fieldTypes;
+        /// 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.
+        QHash<QString, FieldType> fieldTypes;
         /// A list of objects representing independent instances of configuration.
-        /// For instance multiple networks on IRC if multiple are bridged by the
-        /// same bridge.
-        QVector<QJsonObject> instances;
+        /// For example, multiple networks on IRC if multiple are provided by the
+        /// same application service.
+        QVector<ProtocolInstance> instances;
     };
 
     QJsonObject toJson(const ThirdPartyProtocol& pod);