Update third party network schemas

Some information was missed when this was reviewed. This commit adds some additional documentation for how these objects interact with each other.

api/application-service/definitions/location.yaml

@@ -19,12 +19,14 @@ properties:
   protocol:
     description: The protocol ID that the third party location is a part of.
     type: string
-    example: irc
+    example: "irc"
   fields:
     description: Information used to identify this third party location.
     type: object
-    example:
-      "network": "freenode"
+    example: {
+      "network": "freenode",
       "channel": "#matrix"
+    }
+required: ['alias', 'protocol', 'fields']
 title: Location
 type: object

api/application-service/definitions/protocol.yaml

@@ -11,41 +11,60 @@
 # 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 used to identify a third party user.
+    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 used to identify a third party location.
+    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: An icon representing the third party protocol.
+    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: All location or user fields should have an entry here.
+    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
-    properties:
-      fieldname:
-        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.
-            type: string
-          placeholder:
-            description: An placeholder serving as a valid example of the field value.
-            type: string
+    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]+",
@@ -63,17 +82,32 @@ properties:
   instances:
     description: |-
       A list of objects representing independent instances of configuration.
-      For instance multiple networks on IRC if multiple are bridged by the
-      same bridge.
+      For example, multiple networks on IRC if multiple are provided by the
+      same application service.
     type: array
     items:
       type: object
-      example: {
-        "desc": "Freenode",
-        "icon": "mxc://example.org/JkLmNoPq",
-        "fields": {
-          "network": "freenode.net",
-        }
-      }
-title: Protocol
-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']

api/application-service/definitions/protocol_metadata.yaml

@@ -36,6 +36,7 @@ example: {
     },
     "instances": [
       {
+        "network_id": "freenode",
         "desc": "Freenode",
         "icon": "mxc://example.org/JkLmNoPq",
         "fields": {
@@ -59,6 +60,7 @@ example: {
     },
     "instances": [
       {
+        "network_id": "gitter",
         "desc": "Gitter",
         "icon": "mxc://example.org/zXyWvUt",
         "fields": {}

api/application-service/definitions/user.yaml

@@ -21,11 +21,13 @@ properties:
   protocol:
     description: The protocol ID that the third party location is a part of.
     type: string
-    example: gitter
+    example: "gitter"
   fields:
     description: Information used to identify this third party location.
     type: object
-    example:
+    example: {
       "user": "jim"
+    }
+required: ['userid', 'protocol', 'fields']
 title: User
 type: object