@runbooks/schema 0.1.0

package/spec/v1/schema/run-report-envelope.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://runbooks.directory/spec/v1/schema/run-report-envelope.json",
+  "title": "Run report, CloudEvents envelope",
+  "description": "The event binding for a run report (RUNBOOK.md 14). A runner already emitting lineage events adds one mapping rather than a new pipeline, which is the whole reason the format is event-shaped. The envelope carries no field the report itself excludes: in particular `source` is a URI naming a kind of producer, not an installation, and `time` is not required - a precise emission time reintroduces exactly the movement log that bucketing the duration was meant to avoid.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["specversion", "type", "source", "id", "datacontenttype", "data"],
+  "properties": {
+    "specversion": { "const": "1.0" },
+    "type": { "const": "directory.runbooks.run-report.v1" },
+    "source": {
+      "type": "string",
+      "pattern": "^urn:runbooks:(cli|hook|proxy|other)$",
+      "description": "What kind of thing produced this, from a closed set. A free-form source is a hostname waiting to happen."
+    },
+    "id": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
+      "description": "A per-event UUID for deduplication. Not a sender identity, and not stable across runs: correlating two reports to one reporter is the thing this format refuses to enable."
+    },
+    "datacontenttype": { "const": "application/json" },
+    "data": { "$ref": "https://runbooks.directory/spec/v1/schema/run-report.json" }
+  }
+}

package/spec/v1/schema/run-report.json

@@ -0,0 +1,121 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://runbooks.directory/spec/v1/schema/run-report.json",
+  "title": "Run report v1",
+  "description": "What a supervised run leaves behind (RUNBOOK.md 14). An optional extension of the specification: the catalog depends on receiving none. Every field here is either justified as actionable or excluded as a deanonymization risk, and the exclusions are the point - the pressure to add 'just an error message field' is constant, and each such field is a secret leak waiting to happen. Nothing in this schema accepts free text: that is enforced by enum, pattern or format on every string, not by a promise to redact before publishing.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "report_schema",
+    "schema_version",
+    "runbook",
+    "version",
+    "content_hash",
+    "profile",
+    "outcome",
+    "executor_kind",
+    "runtime_profile",
+    "deviation_count",
+    "duration_bucket",
+    "env_class",
+    "reported_at"
+  ],
+  "properties": {
+    "report_schema": {
+      "const": "runbook-run-report/v1"
+    },
+    "schema_version": {
+      "enum": ["v1"],
+      "description": "The runbook format the report is about. Without it, reports are incomparable across format versions."
+    },
+    "runbook": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9-]{0,31}/[a-z0-9][a-z0-9-]{0,63}$",
+      "description": "publisher/slug. A name, not a description: the pattern is what keeps it from becoming a place to write a sentence."
+    },
+    "version": {
+      "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}$",
+      "description": "What actually ran, not just the version id. A report tied only to a version lives until the first update drift. A hash the catalog has never seen is still valid here: a reporter cannot be required to have run an indexed version, and refusing those reports would silently exclude exactly the runs worth hearing about."
+    },
+    "profile": {
+      "enum": ["P0", "P1"]
+    },
+    "outcome": {
+      "enum": ["success", "failed", "aborted", "partial"]
+    },
+    "failed_step_id": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9_]{0,31}$",
+      "description": "Where exactly it broke. '5 successes, 3 failures' produces no action; '3 failures at s4' does."
+    },
+    "failure_class": {
+      "enum": [
+        "precondition_unmet",
+        "tool_missing",
+        "permission_denied",
+        "expectation_mismatch",
+        "timeout",
+        "human_abort",
+        "upstream_changed"
+      ],
+      "description": "Closed on purpose. An open class would be a free-text field with extra steps."
+    },
+    "executor_kind": {
+      "enum": ["human", "agent-assisted", "autonomous"],
+      "description": "Without it you cannot say whether the procedure is fit for an agent, which is half the point of the catalog."
+    },
+    "runtime_profile": {
+      "enum": ["R0", "R1", "R2"],
+      "description": "A failure under an advisory client and a failure under a supervised one are different facts; aggregating them together destroys both."
+    },
+    "deviation_count": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "How many times the supervisor blocked something the runbook did not authorize. A procedure that constantly provokes deviations is one whose graph does not match reality, and no other field surfaces that."
+    },
+    "duration_bucket": {
+      "enum": ["<1m", "1-5m", "5-30m", ">30m"],
+      "description": "Bucketed, never exact. Second-level precision combined with submission time and a rare runbook deanonymizes a small organization."
+    },
+    "env_class": {
+      "enum": ["local", "ci", "staging", "prod"],
+      "description": "A closed enum and nothing finer. No cloud, no region, no cluster version: that is already an infrastructure fingerprint."
+    },
+    "reported_at": {
+      "type": "string",
+      "format": "date",
+      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$",
+      "description": "A date, not a timestamp, enforced by the pattern rather than by convention. A timestamp is a movement log of one organization's incidents."
+    }
+  },
+  "allOf": [
+    {
+      "description": "A success has nothing to attribute a failure to. Carrying a failed step anyway would put a step id into the aggregate for runs that did not fail there.",
+      "if": {
+        "properties": { "outcome": { "const": "success" } },
+        "required": ["outcome"]
+      },
+      "then": {
+        "properties": {
+          "failed_step_id": { "not": {} },
+          "failure_class": { "not": {} }
+        }
+      }
+    },
+    {
+      "description": "A failure that names no class is a report nobody can act on: the aggregate would say only that something went wrong somewhere.",
+      "if": {
+        "properties": { "outcome": { "const": "failed" } },
+        "required": ["outcome"]
+      },
+      "then": {
+        "required": ["failure_class"]
+      }
+    }
+  ]
+}