@runbooks/schema 0.1.0

package/spec/v1/schema/p1.json

@@ -0,0 +1,408 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://runbooks.directory/spec/v1/schema/p1.json",
+  "title": "Runbook, profile P1",
+  "description": "P0 plus a steps[] block. Five step kinds, deliberately few: enough to describe an ops procedure, and few enough that the mapping to an execution DSL is unambiguous (RUNBOOK.md 5). This schema defines a step in isolation. Anything spanning steps - reachability, cycles, explicit terminals, a decision's default branch - is a graph invariant (section 6) checked by the linter, not here.",
+  "$defs": {
+    "stepId": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9_]{0,31}$",
+      "description": "Unique within a version. Referenced by on_fail, branches and rollback_ref."
+    },
+    "toolRef": {
+      "type": "string",
+      "pattern": "^(mcp:[a-z0-9][a-z0-9-]*|cli:[a-z0-9][a-z0-9._-]*|iam:[a-z0-9-]+:[A-Za-z0-9*]+)$",
+      "description": "Same grammar as runbook.capabilities. A step may name a tool absent from capabilities[]: the schema permits it and the linter rejects it as a blocking T2 error (RUNBOOK.md 12). Schema and linter have different jobs."
+    },
+    "title": {
+      "type": "string",
+      "minLength": 3,
+      "maxLength": 48,
+      "description": "An imperative verb phrase (RUNBOOK.md 18.6): 'Capture current lag', not 'Lag problem'. The 48-character cap is what keeps a node label to two lines."
+    },
+    "step": {
+      "type": "object",
+      "required": [
+        "id",
+        "kind",
+        "title"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/stepId"
+        },
+        "kind": {
+          "enum": [
+            "check",
+            "action",
+            "decision",
+            "wait",
+            "escalate"
+          ]
+        },
+        "title": {
+          "$ref": "#/$defs/title"
+        },
+        "tool": {
+          "$ref": "#/$defs/toolRef"
+        },
+        "command": {
+          "type": "string",
+          "description": "May interpolate {{inputs.<name>}}, and only names declared in runbook.inputs. The reference check is semantic, not structural, so it lives in the linter."
+        },
+        "expect": {
+          "type": "string",
+          "minLength": 3
+        },
+        "assert": {
+          "type": "object",
+          "additionalProperties": false,
+          "minProperties": 1,
+          "description": "A machine-checkable postcondition, required by R2 supervision. `expect` stays prose for the reader; this is what a supervisor evaluates. A step with only prose is unevaluable at R2 - a first-class outcome in which the supervisor halts and asks a human rather than guessing (docs/decisions/Q12-expect-evaluability.md).",
+          "properties": {
+            "exit_code": {
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 255
+            },
+            "stdout_matches": {
+              "type": "string",
+              "description": "Regular expression."
+            },
+            "stdout_not_matches": {
+              "type": "string"
+            },
+            "stderr_empty": {
+              "type": "boolean"
+            },
+            "json_path": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "path",
+                "equals"
+              ],
+              "properties": {
+                "path": {
+                  "type": "string"
+                },
+                "equals": {}
+              }
+            }
+          }
+        },
+        "on_fail": {
+          "type": "string",
+          "pattern": "^(escalate:)?([a-z][a-z0-9_]{0,31}|end:(success|failed|aborted))$"
+        },
+        "question": {
+          "type": "string",
+          "minLength": 3
+        },
+        "branches": {
+          "type": "object",
+          "minProperties": 2,
+          "additionalProperties": {
+            "$ref": "#/$defs/stepId"
+          },
+          "description": "Label to step id. Two or more is structural and checked here; that one of them is a default is graph invariant 3, checked by the linter."
+        },
+        "risk": {
+          "enum": [
+            "read-only",
+            "reversible-write",
+            "destructive",
+            "irreversible"
+          ]
+        },
+        "requires_approval": {
+          "type": "boolean"
+        },
+        "rollback_ref": {
+          "type": "string",
+          "pattern": "^(rb_[0-9A-HJKMNP-TV-Z]{26}|[a-z][a-z0-9_]{0,31})$",
+          "description": "A step in this runbook, or another runbook. Cross-runbook resolution is not in v1; until then a rollback_ref to another runbook is documentation for a human, not a route a supervisor can take."
+        },
+        "duration": {
+          "type": "string",
+          "pattern": "^[0-9]+(s|m|h)$"
+        },
+        "until": {
+          "type": "string",
+          "minLength": 3
+        },
+        "timeout": {
+          "type": "string",
+          "pattern": "^[0-9]+(s|m|h)$"
+        },
+        "retry": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "max"
+          ],
+          "properties": {
+            "max": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 20
+            },
+            "target": {
+              "$ref": "#/$defs/stepId"
+            }
+          },
+          "description": "The only permitted cycle, and it must be finite: an unbounded loop in an autonomous agent costs money and causes incidents (invariant 6)."
+        },
+        "to": {
+          "type": "string",
+          "minLength": 2
+        },
+        "next": {
+          "type": "string",
+          "pattern": "^([a-z][a-z0-9_]{0,31}|end:(success|failed|aborted))$",
+          "description": "The next step, or an explicit terminal. Invariant 7 requires every terminal to be explicit: a graph may not end by running out of next node."
+        },
+        "x-layout": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "x",
+            "y"
+          ],
+          "properties": {
+            "x": {
+              "type": "number"
+            },
+            "y": {
+              "type": "number"
+            }
+          },
+          "description": "An authoring-time position from the constructor. Accepted so that a draft laid out by hand can be submitted, and stripped on publish: auto-layout is canonical, the catalog stores no positions, and every reader of a version sees the same graph (docs/decisions/Q8-layout.md). It never participates in content_hash, so re-laying-out a graph is not a new version."
+        }
+      },
+      "allOf": [
+        {
+          "description": "A check without expect and on_fail cannot be evaluated or routed, so a supervisor would have to improvise both (invariant 4).",
+          "if": {
+            "properties": {
+              "kind": {
+                "const": "check"
+              }
+            },
+            "required": [
+              "kind"
+            ]
+          },
+          "then": {
+            "properties": {
+              "expect": {
+                "type": "string"
+              },
+              "on_fail": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "expect",
+              "on_fail"
+            ]
+          }
+        },
+        {
+          "description": "An action must state its risk. Unstated risk defaults to nothing safe.",
+          "if": {
+            "properties": {
+              "kind": {
+                "const": "action"
+              }
+            },
+            "required": [
+              "kind"
+            ]
+          },
+          "then": {
+            "properties": {
+              "risk": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "risk"
+            ]
+          }
+        },
+        {
+          "description": "Invariant 5: a destructive or irreversible action is always paired - an approval gate before it, or a rollback after it. This is the one rule the whole product exists to enforce, so it is structural rather than advisory.",
+          "if": {
+            "properties": {
+              "kind": {
+                "const": "action"
+              },
+              "risk": {
+                "enum": [
+                  "destructive",
+                  "irreversible"
+                ]
+              }
+            },
+            "required": [
+              "kind",
+              "risk"
+            ]
+          },
+          "then": {
+            "anyOf": [
+              {
+                "properties": {
+                  "requires_approval": {
+                    "const": true
+                  }
+                },
+                "required": [
+                  "requires_approval"
+                ]
+              },
+              {
+                "properties": {
+                  "rollback_ref": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "rollback_ref"
+                ]
+              }
+            ]
+          }
+        },
+        {
+          "description": "A decision needs a question and at least two branches.",
+          "if": {
+            "properties": {
+              "kind": {
+                "const": "decision"
+              }
+            },
+            "required": [
+              "kind"
+            ]
+          },
+          "then": {
+            "properties": {
+              "question": {
+                "type": "string"
+              },
+              "branches": {
+                "type": "object"
+              }
+            },
+            "required": [
+              "question",
+              "branches"
+            ]
+          }
+        },
+        {
+          "description": "A wait must be bounded: either a duration, or a condition with a timeout. An unbounded wait is a hang with better manners.",
+          "if": {
+            "properties": {
+              "kind": {
+                "const": "wait"
+              }
+            },
+            "required": [
+              "kind"
+            ]
+          },
+          "then": {
+            "anyOf": [
+              {
+                "properties": {
+                  "duration": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "duration"
+                ]
+              },
+              {
+                "properties": {
+                  "until": {
+                    "type": "string"
+                  },
+                  "timeout": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "until",
+                  "timeout"
+                ]
+              }
+            ]
+          }
+        },
+        {
+          "description": "Escalation is an exit from the workflow, so it must say where it goes.",
+          "if": {
+            "properties": {
+              "kind": {
+                "const": "escalate"
+              }
+            },
+            "required": [
+              "kind"
+            ]
+          },
+          "then": {
+            "properties": {
+              "to": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "to"
+            ]
+          }
+        }
+      ]
+    }
+  },
+  "allOf": [
+    {
+      "$ref": "https://runbooks.directory/spec/v1/schema/p0.json"
+    },
+    {
+      "type": "object",
+      "required": [
+        "runbook"
+      ],
+      "properties": {
+        "runbook": {
+          "type": "object",
+          "required": [
+            "profile",
+            "steps"
+          ],
+          "properties": {
+            "profile": {
+              "enum": [
+                "P1",
+                "P2"
+              ]
+            },
+            "steps": {
+              "type": "array",
+              "minItems": 1,
+              "items": {
+                "$ref": "#/$defs/step"
+              }
+            }
+          }
+        }
+      }
+    }
+  ]
+}