doc: schema for connect.

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>

doc/lightning-connect.7.md

@@ -39,11 +39,21 @@ lightning-fundchannel(7).
 RETURN VALUE
 ------------
 
-On success the peer *id* is returned, as well as a hexidecimal
-*features* bitmap, a *direction* ("in" if they connected to us, "out"
-if we connected to them") and an *address* object as per
-lightning-listnodes(7).  Note that *address* will be less useful if 
-"direction" is "in", especially if a proxy is in use.
+[comment]: # (GENERATE-FROM-SCHEMA-START)
+On success, an object is returned, containing:
+- **id** (pubkey): the peer we connected to
+- **features** (hex): BOLT 9 features bitmap offered by peer
+- **direction** (string): Whether they initiated connection or we did (one of *in*, *out*)
+- **address** (object): Address information (mainly useful if **direction** is *out*):
+  - **type** (string): Type of connection (*torv2*/*torv3* only if **direction** is *out*) (one of *local socket*, *ipv4*, *ipv6*, *torv2*, *torv3*)
+
+  If **type** is *local socket*:
+    - **socket** (string): socket filename
+
+  If **type** is *ipv4*, *ipv6*, *torv2* or *torv3*:
+    - **address** (string): address in expected format for **type**
+    - **port** (u16): port number
+[comment]: # (GENERATE-FROM-SCHEMA-END)
 
 ERRORS
 ------
@@ -78,3 +88,4 @@ RESOURCES
 
 Main web site: <https://github.com/ElementsProject/lightning>
 
+[comment]: # ( SHA256STAMP:bb07acd8aa16708c8d5a4e867c104034f13e4dfe79d574a5f82a394497021c79)

doc/schemas/connect.schema.json

@@ -0,0 +1,68 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "type": "object",
+    "additionalProperties": false,
+    "required": [ "id", "features", "direction", "address" ],
+    "properties": {
+	"id": {
+	    "type": "pubkey",
+	    "description": "the peer we connected to"
+	},
+	"features": {
+	    "type": "hex",
+	    "description": "BOLT 9 features bitmap offered by peer"
+	},
+	"direction": {
+	    "type": "string",
+	    "enum": [ "in", "out" ],
+	    "description": "Whether they initiated connection or we did"
+	},
+	"address": {
+	    "type": "object",
+	    "description": "Address information (mainly useful if **direction** is *out*)",
+	    "additionalProperties": true,
+	    "required": [ "type" ],
+	    "properties": {
+		"type": {
+		    "type": "string",
+		    "enum": [ "local socket", "ipv4", "ipv6", "torv2", "torv3" ],
+		    "description": "Type of connection (*torv2*/*torv3* only if **direction** is *out*)"
+		}
+	    },
+	    "oneOf": [
+		{
+		    "additionalProperties": false,
+		    "required": [ "socket" ],
+		    "properties": {
+			"type": {
+			    "type": "string",
+			    "enum": [ "local socket" ]
+			},
+			"socket": {
+			    "type": "string",
+			    "description": "socket filename"
+			}
+		    }
+		},
+		{
+		    "additionalProperties": false,
+		    "required": [ "address", "port" ],
+		    "properties": {
+			"type": {
+			    "type": "string",
+			    "enum": [ "ipv4", "ipv6", "torv2", "torv3" ]
+			},
+			"address": {
+			    "type": "string",
+			    "description": "address in expected format for **type**"
+			},
+			"port": {
+			    "type": "u16",
+			    "description": "port number"
+			}
+		    }
+		}
+	    ]
+	}
+    }
+}