4 files changed, 66 insertions, 38 deletions
diff --git a/lib/application-service/definitions/location.cpp b/lib/application-service/definitions/location.cpp
index 1ccff315..958a55bf 100644
--- a/lib/application-service/definitions/location.cpp
+++ b/lib/application-service/definitions/location.cpp
@@ -9,9 +9,9 @@ using namespace QMatrixClient;
 QJsonObject QMatrixClient::toJson(const ThirdPartyLocation& pod)
 {
     QJsonObject jo;
-    addParam<IfNotEmpty>(jo, QStringLiteral("alias"), pod.alias);
-    addParam<IfNotEmpty>(jo, QStringLiteral("protocol"), pod.protocol);
-    addParam<IfNotEmpty>(jo, QStringLiteral("fields"), pod.fields);
+    addParam<>(jo, QStringLiteral("alias"), pod.alias);
+    addParam<>(jo, QStringLiteral("protocol"), pod.protocol);
+    addParam<>(jo, QStringLiteral("fields"), pod.fields);
     return jo;
 }
 
diff --git a/lib/application-service/definitions/protocol.cpp b/lib/application-service/definitions/protocol.cpp
index 13e58382..04bb7dfc 100644
--- a/lib/application-service/definitions/protocol.cpp
+++ b/lib/application-service/definitions/protocol.cpp
@@ -9,8 +9,8 @@ using namespace QMatrixClient;
 QJsonObject QMatrixClient::toJson(const FieldType& pod)
 {
     QJsonObject jo;
-    addParam<IfNotEmpty>(jo, QStringLiteral("regexp"), pod.regexp);
-    addParam<IfNotEmpty>(jo, QStringLiteral("placeholder"), pod.placeholder);
+    addParam<>(jo, QStringLiteral("regexp"), pod.regexp);
+    addParam<>(jo, QStringLiteral("placeholder"), pod.placeholder);
     return jo;
 }
 
@@ -25,18 +25,27 @@ FieldType FromJsonObject<FieldType>::operator()(const QJsonObject& jo) const
     return result;
 }
 
-QJsonObject QMatrixClient::toJson(const FieldTypes& pod)
+QJsonObject QMatrixClient::toJson(const ProtocolInstance& pod)
 {
     QJsonObject jo;
-    addParam<IfNotEmpty>(jo, QStringLiteral("fieldname"), pod.fieldname);
+    addParam<>(jo, QStringLiteral("desc"), pod.desc);
+    addParam<IfNotEmpty>(jo, QStringLiteral("icon"), pod.icon);
+    addParam<>(jo, QStringLiteral("fields"), pod.fields);
+    addParam<>(jo, QStringLiteral("network_id"), pod.networkId);
     return jo;
 }
 
-FieldTypes FromJsonObject<FieldTypes>::operator()(const QJsonObject& jo) const
+ProtocolInstance FromJsonObject<ProtocolInstance>::operator()(const QJsonObject& jo) const
 {
-    FieldTypes result;
-    result.fieldname =
-        fromJson<FieldType>(jo.value("fieldname"_ls));
+    ProtocolInstance result;
+    result.desc =
+        fromJson<QString>(jo.value("desc"_ls));
+    result.icon =
+        fromJson<QString>(jo.value("icon"_ls));
+    result.fields =
+        fromJson<QJsonObject>(jo.value("fields"_ls));
+    result.networkId =
+        fromJson<QString>(jo.value("network_id"_ls));
 
     return result;
 }
@@ -44,11 +53,11 @@ FieldTypes FromJsonObject<FieldTypes>::operator()(const QJsonObject& jo) const
 QJsonObject QMatrixClient::toJson(const ThirdPartyProtocol& pod)
 {
     QJsonObject jo;
-    addParam<IfNotEmpty>(jo, QStringLiteral("user_fields"), pod.userFields);
-    addParam<IfNotEmpty>(jo, QStringLiteral("location_fields"), pod.locationFields);
-    addParam<IfNotEmpty>(jo, QStringLiteral("icon"), pod.icon);
-    addParam<IfNotEmpty>(jo, QStringLiteral("field_types"), pod.fieldTypes);
-    addParam<IfNotEmpty>(jo, QStringLiteral("instances"), pod.instances);
+    addParam<>(jo, QStringLiteral("user_fields"), pod.userFields);
+    addParam<>(jo, QStringLiteral("location_fields"), pod.locationFields);
+    addParam<>(jo, QStringLiteral("icon"), pod.icon);
+    addParam<>(jo, QStringLiteral("field_types"), pod.fieldTypes);
+    addParam<>(jo, QStringLiteral("instances"), pod.instances);
     return jo;
 }
 
@@ -62,9 +71,9 @@ ThirdPartyProtocol FromJsonObject<ThirdPartyProtocol>::operator()(const QJsonObj
     result.icon =
         fromJson<QString>(jo.value("icon"_ls));
     result.fieldTypes =
-        fromJson<FieldTypes>(jo.value("field_types"_ls));
+        fromJson<QHash<QString, FieldType>>(jo.value("field_types"_ls));
     result.instances =
-        fromJson<QVector<QJsonObject>>(jo.value("instances"_ls));
+        fromJson<QVector<ProtocolInstance>>(jo.value("instances"_ls));
 
     return result;
 }
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);
diff --git a/lib/application-service/definitions/user.cpp b/lib/application-service/definitions/user.cpp
index dbe4c104..ca334236 100644
--- a/lib/application-service/definitions/user.cpp
+++ b/lib/application-service/definitions/user.cpp
@@ -9,9 +9,9 @@ using namespace QMatrixClient;
 QJsonObject QMatrixClient::toJson(const ThirdPartyUser& pod)
 {
     QJsonObject jo;
-    addParam<IfNotEmpty>(jo, QStringLiteral("userid"), pod.userid);
-    addParam<IfNotEmpty>(jo, QStringLiteral("protocol"), pod.protocol);
-    addParam<IfNotEmpty>(jo, QStringLiteral("fields"), pod.fields);
+    addParam<>(jo, QStringLiteral("userid"), pod.userid);
+    addParam<>(jo, QStringLiteral("protocol"), pod.protocol);
+    addParam<>(jo, QStringLiteral("fields"), pod.fields);
     return jo;
 }