From 5d7203ed6b18a30e55777bba72ee0ee7df965f3d Mon Sep 17 00:00:00 2001
From: Rusty Russell <rusty@rustcorp.com.au>
Date: Wed, 26 May 2021 15:22:01 +0930
Subject: [PATCH] doc/schemas: create close schema.

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
---
 doc/lightning-close.7         | 24 ++++++++++++++------
 doc/lightning-close.7.md      | 15 ++++++++-----
 doc/schemas/close.schema.json | 41 +++++++++++++++++++++++++++++++++++
 3 files changed, 67 insertions(+), 13 deletions(-)
 create mode 100644 doc/schemas/close.schema.json

diff --git a/doc/lightning-close.7 b/doc/lightning-close.7
index e6478dd06..c6313e417 100644
--- a/doc/lightning-close.7
+++ b/doc/lightning-close.7
@@ -83,13 +83,23 @@ if the peer is offline and we are waiting\.
 
 .SH RETURN VALUE
 
-On success, an object with fields \fItx\fR and \fItxid\fR containing the closing
-transaction are returned\. It will also have a field \fItype\fR which is
-either the JSON string \fImutual\fR or the JSON string \fIunilateral\fR\. A
-\fImutual\fR close means that we could negotiate a close with the peer,
-while a \fIunilateral\fR close means that the \fIforce\fR flag was set and we
-had to close the channel without waiting for the counterparty\.
+On success, an object is returned, containing:
 
+.RS
+.IP \[bu]
+\fBtype\fR (string): Whether we successfully negotiated a mutual close, closed without them, or discarded not-yet-opened channel (one of "mutual", "unilateral", "unopened")
+
+.RE
+
+If \fBtype\fR is "mutual" or "unilateral":
+
+.RS
+.IP \[bu]
+\fBtx\fR (hex): the raw bitcoin transaction used to close the channel (if it was open)
+.IP \[bu]
+\fBtxid\fR (txid): the transaction id of the \fItx\fR field
+
+.RE
 
 A unilateral close may still occur at any time if the peer did not
 behave correctly during the close negotiation\.
@@ -110,4 +120,4 @@ ZmnSCPxj \fI<ZmnSCPxj@protonmail.com\fR> is mainly responsible\.
 
 Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
 
-\" SHA256STAMP:c8a4fe414eeb72880346601be2e73f1ad6decb31b4d4e291549d8b339e47b68d
+\" SHA256STAMP:507a9ca707e244eef65c5e16daa5a4d7ba8f59e93e988d252f7e854ae9f44781
diff --git a/doc/lightning-close.7.md b/doc/lightning-close.7.md
index 676272a48..306598ca7 100644
--- a/doc/lightning-close.7.md
+++ b/doc/lightning-close.7.md
@@ -74,12 +74,14 @@ if the peer is offline and we are waiting.
 RETURN VALUE
 ------------
 
-On success, an object with fields *tx* and *txid* containing the closing
-transaction are returned. It will also have a field *type* which is
-either the JSON string *mutual* or the JSON string *unilateral*. A
-*mutual* close means that we could negotiate a close with the peer,
-while a *unilateral* close means that the *force* flag was set and we
-had to close the channel without waiting for the counterparty.
+[comment]: # (GENERATE-FROM-SCHEMA-START)
+On success, an object is returned, containing:
+- **type** (string): Whether we successfully negotiated a mutual close, closed without them, or discarded not-yet-opened channel (one of "mutual", "unilateral", "unopened")
+
+If **type** is "mutual" or "unilateral":
+  - **tx** (hex): the raw bitcoin transaction used to close the channel (if it was open)
+  - **txid** (txid): the transaction id of the *tx* field
+[comment]: # (GENERATE-FROM-SCHEMA-END)
 
 A unilateral close may still occur at any time if the peer did not
 behave correctly during the close negotiation.
@@ -102,3 +104,4 @@ RESOURCES
 
 Main web site: <https://github.com/ElementsProject/lightning>
 
+[comment]: # ( SHA256STAMP:9159304cd705d8135c32e12bd029c0e95baff0d495e6f9092a75888dab2f5fb3)
diff --git a/doc/schemas/close.schema.json b/doc/schemas/close.schema.json
new file mode 100644
index 000000000..b28dee645
--- /dev/null
+++ b/doc/schemas/close.schema.json
@@ -0,0 +1,41 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "type": "object",
+    "required": [ "type" ],
+    "properties": {
+        "type": {
+            "type": "string",
+            "enum": [ "mutual", "unilateral", "unopened" ],
+            "description": "Whether we successfully negotiated a mutual close, closed without them, or discarded not-yet-opened channel"
+        }
+    },
+    "if": {
+        "properties": {
+            "type": {
+                "type": "string",
+                "enum": [ "mutual", "unilateral" ]
+            }
+        }
+    },
+    "then": {
+        "additionalProperties": false,
+        "required": [ "tx", "txid" ],
+        "properties": {
+            "type": { },
+            "tx": {
+                "type": "hex",
+                "description": "the raw bitcoin transaction used to close the channel (if it was open)"
+            },
+            "txid": {
+                "type": "txid",
+                "description": "the transaction id of the *tx* field"
+            }
+        }
+    },
+    "else": {
+        "additionalProperties": false,
+        "properties": {
+            "type": { }
+        }
+    }
+}