From af2c1f1881a88c9679ff13df2c840973d64dead2 Mon Sep 17 00:00:00 2001
From: Shahana Farooqui <shahana.farooqui@gmail.com>
Date: Fri, 31 Mar 2023 12:26:16 +1030
Subject: [PATCH] doc: schemas for commando-listrunes & commando-blacklist

---
 doc/schemas/commando-blacklist.request.json |  17 ++++
 doc/schemas/commando-blacklist.schema.json  |  32 ++++++
 doc/schemas/commando-listrunes.request.json |  13 +++
 doc/schemas/commando-listrunes.schema.json  | 107 ++++++++++++++++++++
 4 files changed, 169 insertions(+)
 create mode 100644 doc/schemas/commando-blacklist.request.json
 create mode 100644 doc/schemas/commando-blacklist.schema.json
 create mode 100644 doc/schemas/commando-listrunes.request.json
 create mode 100644 doc/schemas/commando-listrunes.schema.json

diff --git a/doc/schemas/commando-blacklist.request.json b/doc/schemas/commando-blacklist.request.json
new file mode 100644
index 000000000..1bb542355
--- /dev/null
+++ b/doc/schemas/commando-blacklist.request.json
@@ -0,0 +1,17 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [],
+  "added": "v23.05",
+  "properties": {
+    "start": {
+      "type": "u64",
+      "description": "first rune unique id to blacklist"
+    },
+    "end": {
+      "type": "u64",
+      "description": "final rune unique id to blacklist (defaults to start)"
+    }
+  }
+}
diff --git a/doc/schemas/commando-blacklist.schema.json b/doc/schemas/commando-blacklist.schema.json
new file mode 100644
index 000000000..86fb09386
--- /dev/null
+++ b/doc/schemas/commando-blacklist.schema.json
@@ -0,0 +1,32 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "blacklist"
+  ],
+  "properties": {
+    "blacklist": {
+      "type": "array",
+      "description": "the resulting blacklist ranges after the command",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "start",
+          "end"
+        ],
+        "properties": {
+          "start": {
+            "type": "u64",
+            "description": "Unique id of first rune in this blacklist range"
+          },
+          "end": {
+            "type": "u64",
+            "description": "Unique id of last rune in this blacklist range"
+          }
+        }
+      }
+    }
+  }
+}
diff --git a/doc/schemas/commando-listrunes.request.json b/doc/schemas/commando-listrunes.request.json
new file mode 100644
index 000000000..9cb47ee44
--- /dev/null
+++ b/doc/schemas/commando-listrunes.request.json
@@ -0,0 +1,13 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [],
+  "added": "v23.05",
+  "properties": {
+    "rune": {
+      "type": "string",
+      "description": "optional rune to list"
+    }
+  }
+}
diff --git a/doc/schemas/commando-listrunes.schema.json b/doc/schemas/commando-listrunes.schema.json
new file mode 100644
index 000000000..05e479591
--- /dev/null
+++ b/doc/schemas/commando-listrunes.schema.json
@@ -0,0 +1,107 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "runes"
+  ],
+  "properties": {
+    "runes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "rune",
+          "unique_id",
+          "restrictions",
+          "restrictions_as_english"
+        ],
+        "properties": {
+          "rune": {
+            "type": "string",
+            "description": "Base64 encoded rune"
+          },
+          "unique_id": {
+            "type": "string",
+            "description": "Unique id assigned when the rune was generated; this is always a u64 for commando runes"
+          },
+          "restrictions": {
+            "type": "array",
+            "description": "The restrictions on what commands this rune can authorize",
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "alternatives",
+                "english"
+              ],
+              "properties": {
+                "alternatives": {
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": [
+                      "fieldname",
+                      "value",
+                      "condition",
+                      "english"
+                    ],
+                    "properties": {
+                      "fieldname": {
+                        "type": "string",
+                        "description": "The field this restriction applies to; see commando-rune(7)"
+                      },
+                      "value": {
+                        "type": "string",
+                        "description": "The value accepted for this field"
+                      },
+                      "condition": {
+                        "type": "string",
+                        "description": "The way to compare fieldname and value"
+                      },
+                      "english": {
+                        "type": "string",
+                        "description": "English readable description of this alternative"
+                      }
+                    }
+                  },
+                  "english": {
+                    "type": "string",
+                    "description": "English readable summary of alternatives above"
+                  }
+                }
+              }
+            }
+          },
+          "restrictions_as_english": {
+            "type": "string",
+            "description": "English readable description of the restrictions array above"
+          },
+          "stored": {
+            "type": "boolean",
+            "enum": [
+              false
+            ],
+            "description": "This is false if the rune does not appear in our datastore (only possible when `rune` is specified)"
+          },
+          "blacklisted": {
+            "type": "boolean",
+            "enum": [
+              true
+            ],
+            "description": "The rune has been blacklisted; see commando-blacklist(7)"
+          },
+          "our_rune": {
+            "type": "boolean",
+            "enum": [
+              false
+            ],
+            "description": "This is not a rune for this node (only possible when `rune` is specified)"
+          }
+        }
+      }
+    }
+  }
+}