@runbooks/schema 0.1.0

package/spec/v1/schema/attestation.json

@@ -0,0 +1,62 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://runbooks.directory/spec/v1/schema/attestation.json",
+  "title": "Runbook attestation v1",
+  "description": "A signed claim about a run of a specific version of a specific document (RUNBOOK.md 8). T3 exists so that trust can rise above what the catalog can check statically without the catalog owning a runner, which means a third party has to be able to issue a claim we can verify. The subject binds to content_hash rather than to a name: a rename cannot move an attestation and an edit cannot inherit one. The signable bytes are defined in spec/v1/attestations.md and must be byte-identical across implementations.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["attestation_schema", "predicate_type", "subject", "predicate", "signatures"],
+  "properties": {
+    "attestation_schema": { "const": "runbook-attestation/v1" },
+    "predicate_type": { "const": "https://runbooks.directory/attestation/run/v1" },
+    "subject": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["runbook", "semver", "content_hash"],
+      "properties": {
+        "runbook": {
+          "type": "string",
+          "pattern": "^(std|[a-z][a-z0-9-]{0,30}[a-z0-9]|github:[A-Za-z0-9][A-Za-z0-9-]{0,38}|domain:[a-z0-9.-]+)/[a-z0-9]+(-[a-z0-9]+)*$"
+        },
+        "semver": { "type": "string", "pattern": "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)$" },
+        "content_hash": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" }
+      }
+    },
+    "predicate": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["issuer", "env_class", "outcome", "runtime_profile", "issued_at"],
+      "properties": {
+        "issuer": {
+          "type": "string",
+          "format": "uri",
+          "description": "An identity a verifier can look up, not a display name. Its origin is where the key set is found."
+        },
+        "env_class": { "enum": ["local", "ci", "staging", "prod"] },
+        "outcome": { "enum": ["success", "failed", "aborted", "partial"] },
+        "runtime_profile": { "enum": ["R0", "R1", "R2"] },
+        "issued_at": {
+          "type": "string",
+          "format": "date",
+          "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$",
+          "description": "A date, not a timestamp: §14's reasoning applies to anything that leaves a machine."
+        },
+        "report_hash": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" }
+      }
+    },
+    "signatures": {
+      "type": "array",
+      "minItems": 1,
+      "description": "A statement with no signature is a draft, not an attestation.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["key_id", "sig"],
+        "properties": {
+          "key_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$" },
+          "sig": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "base64 of 64 Ed25519 bytes." }
+        }
+      }
+    }
+  }
+}

package/spec/v1/schema/p0.json

@@ -0,0 +1,383 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://runbooks.directory/spec/v1/schema/p0.json",
+  "title": "Runbook, profile P0",
+  "description": "Frontmatter for a P0 (prose) runbook. A superset of Agent Skills: `name` and `description` keep their Agent Skills meaning at the top level, and everything this specification adds lives under the single `runbook` key. See docs/decisions/Q2-frontmatter-namespacing.md.",
+  "type": "object",
+  "required": [
+    "name",
+    "description",
+    "runbook"
+  ],
+  "additionalProperties": true,
+  "properties": {
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
+      "maxLength": 64,
+      "description": "Agent Skills field. ASCII slug, never reused (\u00a79)."
+    },
+    "description": {
+      "type": "string",
+      "minLength": 16,
+      "maxLength": 1024,
+      "description": "Agent Skills field. What the procedure does and when to reach for it."
+    },
+    "runbook": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schema_version",
+        "profile",
+        "domain",
+        "targets",
+        "trigger",
+        "execution",
+        "risk",
+        "capabilities",
+        "publisher",
+        "lang",
+        "license",
+        "source"
+      ],
+      "properties": {
+        "schema_version": {
+          "const": "v1"
+        },
+        "id": {
+          "type": "string",
+          "pattern": "^rb_[0-9A-HJKMNP-TV-Z]{26}$",
+          "description": "ULID assigned by the catalog. Immutable, survives renames (\u00a79). Absent in an authored document."
+        },
+        "semver": {
+          "type": "string",
+          "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-[0-9A-Za-z.-]+)?$",
+          "description": "The version this snapshot is. Assigned by the catalog alongside `id` and `content_hash`; absent in an authored document, present in everything the catalog serves."
+        },
+        "content_hash": {
+          "type": "string",
+          "pattern": "^sha256:[0-9a-f]{64}$",
+          "description": "What this version is (RUNBOOK.md 9). Agent pins point at it and attestations bind to it. Computed over the document with this field and x-layout excluded, so it cannot be part of what it hashes."
+        },
+        "profile": {
+          "enum": [
+            "P0",
+            "P1",
+            "P2"
+          ]
+        },
+        "min_runtime_profile": {
+          "enum": [
+            "R0",
+            "R1",
+            "R2"
+          ],
+          "description": "Lowest client runtime profile permitted to follow this runbook (\u00a713.3). A client refuses a document whose minimum exceeds what it enforces."
+        },
+        "domain": {
+          "enum": [
+            "incident-response",
+            "data-pipelines",
+            "llm-ops",
+            "agent-workflows",
+            "cloud-infra",
+            "databases",
+            "ci-cd",
+            "security"
+          ],
+          "description": "Closed list, changed only by RFC (\u00a74). Navigation and URLs, not classification."
+        },
+        "targets": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+          }
+        },
+        "trigger": {
+          "enum": [
+            "alert",
+            "symptom",
+            "scheduled",
+            "manual",
+            "agent-invoked"
+          ]
+        },
+        "execution": {
+          "enum": [
+            "human-only",
+            "human-with-agent",
+            "agent-autonomous"
+          ]
+        },
+        "risk": {
+          "enum": [
+            "read-only",
+            "reversible-write",
+            "destructive",
+            "irreversible"
+          ]
+        },
+        "blast_radius": {
+          "enum": [
+            "resource",
+            "service",
+            "cluster",
+            "tenant",
+            "global"
+          ]
+        },
+        "duration": {
+          "enum": [
+            "<5m",
+            "5-30m",
+            ">30m"
+          ]
+        },
+        "capabilities": {
+          "type": "array",
+          "uniqueItems": true,
+          "description": "A privilege request, not a description (\u00a72). A client MUST check it against its own allowlist before execution (\u00a712).",
+          "items": {
+            "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*]+)$"
+          }
+        },
+        "applies_to": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          },
+          "description": "Version ranges per target, e.g. {\"postgres\": \">=14 <17\"}."
+        },
+        "publisher": {
+          "type": "string",
+          "pattern": "^(std|[a-z0-9][a-z0-9-]{0,38}|github:[A-Za-z0-9][A-Za-z0-9-]{0,38}|domain:[a-z0-9.-]+\\.[a-z]{2,})$",
+          "description": "Namespace (\u00a77). Claimed, not granted, except `std` which is ours."
+        },
+        "lang": {
+          "type": "string",
+          "pattern": "^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$",
+          "default": "en"
+        },
+        "title_en": {
+          "type": "string",
+          "maxLength": 200
+        },
+        "summary_en": {
+          "type": "string",
+          "maxLength": 1024
+        },
+        "translation_of": {
+          "type": "string",
+          "pattern": "^rb_[0-9A-HJKMNP-TV-Z]{26}$"
+        },
+        "derived_from": {
+          "type": "string",
+          "pattern": "^rb_[0-9A-HJKMNP-TV-Z]{26}$",
+          "description": "The catalog record this was adapted from, when the original is itself in the catalog. Attribution for an adaptation is its source (RUNBOOK.md 10.2), which every record carries; this is the edge that lets a reader see both and keeps deduplication from counting one procedure twice. Requiring it of an adaptation whose original is not in the catalog would be requiring a link to nothing."
+        },
+        "content_class": {
+          "enum": [
+            "ingested",
+            "adapted",
+            "submitted",
+            "curated"
+          ],
+          "description": "How this record got here (RUNBOOK.md 15). `adapted` means the procedure derives from somebody else's document under a licence that allows it, whether a machine segmented it or a person rewrote it by hand. It is the one class with a rule of its own: it does not publish without a human confirming the step segmentation and the risk labelling, because an unreviewed machine adaptation is what that rule is guarding against. Its attribution is `source`, which is mandatory for every record."
+        },
+        "license": {
+          "type": "string",
+          "minLength": 2,
+          "description": "SPDX identifier. Mandatory: an undetectable licence means the record is not ingested at all (\u00a710.2)."
+        },
+        "keywords": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "maxLength": 40
+          },
+          "description": "The pressure valve for anything that is not a facet: uncontrolled, unguaranteed, not filterable (\u00a74)."
+        },
+        "inputs": {
+          "type": "object",
+          "description": "Declared parameters. Interpolation may reference only these, and a missing required input aborts a run rather than interpolating empty (\u00a75).",
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "type"
+            ],
+            "properties": {
+              "type": {
+                "enum": [
+                  "string",
+                  "number",
+                  "boolean"
+                ]
+              },
+              "required": {
+                "type": "boolean",
+                "default": false
+              },
+              "default": {},
+              "description": {
+                "type": "string",
+                "maxLength": 200
+              },
+              "secret": {
+                "type": "boolean",
+                "default": false,
+                "description": "The value is a credential and is redacted wherever the run is shown to a human - an approval request above all (RUNBOOK.md 13, NG3). An approval channel is somewhere a secret should never arrive."
+              }
+            }
+          }
+        },
+        "steps": {
+          "type": "array",
+          "description": "Permitted but unconstrained at P0, which is prose. P1 requires it and constrains every item (spec/v1/schema/p1.json). It is declared here so that each profile is a strict superset of the one below: a P1 document must also be a valid P0 document, or every facet, hub and search filter would need a second code path."
+        },
+        "source": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "url",
+            "fetched_at",
+            "upstream_state"
+          ],
+          "description": "Provenance. A record without it does not validate (\u00a710).",
+          "properties": {
+            "url": {
+              "type": "string",
+              "format": "uri"
+            },
+            "commit": {
+              "type": "string",
+              "pattern": "^[0-9a-f]{7,40}$"
+            },
+            "fetched_at": {
+              "type": "string",
+              "format": "date"
+            },
+            "upstream_state": {
+              "enum": [
+                "current",
+                "changed",
+                "gone"
+              ]
+            },
+            "upstream_hash": {
+              "type": "string",
+              "pattern": "^sha256:[0-9a-f]{64}$",
+              "description": "The hash of the upstream document as it was when this record was made. What a reindex compares against: without it, 'has upstream changed' can only be answered by re-deriving the record, and a derivation that differs for our own reasons would read as the source having moved. Never part of content_hash \u2014 noticing that a source moved is not a new version of this record."
+            },
+            "checked_at": {
+              "type": "string",
+              "format": "date",
+              "description": "When the upstream was last looked at, which is not when the record was made. A marker with no date is a claim about the present made at an unknown time."
+            }
+          }
+        },
+        "trust": {
+          "not": {},
+          "description": "Forbidden. Trust is computed from evidence plus a clock and is never asserted by a record (RUNBOOK.md 8). A document that declares its own trust is invalid, not merely ignored."
+        },
+        "attestations": {
+          "not": {},
+          "description": "Forbidden. Attestations are issued and verified, never self-declared (RUNBOOK.md 8). They reach a record through the catalog, not through its frontmatter."
+        },
+        "profile_verified": {
+          "not": {},
+          "description": "Forbidden. There is no self-certification of any kind. See RUNBOOK.md 19 on why there is no score."
+        },
+        "relations": {
+          "type": "array",
+          "description": "Edges to other records (\u00a722). A relation is authored: unlike an attestation, it is the author saying how this procedure stands to another, and only they can say it. Every reference must resolve to a record this catalog holds, or the record does not publish.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "kind",
+              "ref"
+            ],
+            "properties": {
+              "kind": {
+                "enum": [
+                  "requires",
+                  "rollback_of",
+                  "escalates_to",
+                  "part_of"
+                ],
+                "description": "requires: this cannot run until that one has. rollback_of: this undoes that one. escalates_to: when this hands off, it hands off to that one. part_of: this is a step of that larger procedure (\u00a718.6's decomposition)."
+              },
+              "ref": {
+                "type": "string",
+                "pattern": "^[a-z0-9][a-z0-9-]{0,38}/[a-z0-9][a-z0-9-]{0,63}(@[0-9]+\\.[0-9]+\\.[0-9]+)?$",
+                "description": "publisher/slug, optionally pinned with @semver. `requires` and `rollback_of` must pin, because they assert what another record does and that is only true of a version. `part_of` and `escalates_to` must not, because they are structural and a pinned structure rots."
+              },
+              "why": {
+                "type": "string",
+                "maxLength": 280,
+                "description": "One sentence for a reader. Optional, and the only free text in a relation."
+              },
+              "step": {
+                "type": "string",
+                "pattern": "^[a-z][a-z0-9_-]{0,31}$",
+                "description": "`part_of` only: the step of the parent this record expands (\u00a718.6). Without it a decomposition is a claim of membership with no place in the parent's procedure, and a reader cannot tell which of twelve steps this is the detail of."
+              }
+            }
+          }
+        },
+        "trust_evidence": {
+          "not": {},
+          "description": "Forbidden. The evidence for a trust level is what the catalog concluded while computing it (RUNBOOK.md 8, 18.5), so it arrives with the level and never from the document. Submit the record; the level and its evidence are added on the way out, and both are in schema/record.json."
+        },
+        "signature": {
+          "not": {},
+          "description": "Forbidden. A signature field in a served record is what checking the publisher's key concluded (RUNBOOK.md 8), not a claim the document makes about itself: a record that carried its own verdict would be asserting the one thing verification exists to decide. Sign the record with the publishing key instead."
+        }
+      },
+      "allOf": [
+        {
+          "description": "Non-English content must carry an English title and summary, or clustering splits one topic into language clusters (RUNBOOK.md 16). ajv strict mode requires each conditional branch to define the properties it names.",
+          "if": {
+            "properties": {
+              "lang": {
+                "type": "string",
+                "not": {
+                  "const": "en"
+                }
+              }
+            },
+            "required": [
+              "lang"
+            ]
+          },
+          "then": {
+            "properties": {
+              "title_en": {
+                "type": "string",
+                "maxLength": 200
+              },
+              "summary_en": {
+                "type": "string",
+                "maxLength": 1024
+              }
+            },
+            "required": [
+              "title_en",
+              "summary_en"
+            ]
+          }
+        }
+      ]
+    },
+    "body": {
+      "type": "string",
+      "description": "The markdown body of the SKILL.md this record came from, carried so it participates in content_hash. Changing the prose of a procedure is a change to the procedure."
+    }
+  }
+}