Skip to content

Lint a playbook

Canonical tool: occam_playbook_lint

Statically validate a playbook/genome JSON against the 1.x schema — no network, pure and deterministic.

When to use

  • Before a live occam_playbook_save — catch schema errors without paying for the verify fetch.
  • Vetting a community/site genome before trusting it.

Parameters

Parameter Type Default Required Description
playbook_json string — yes The playbook/genome JSON to validate (a JSON object)

Returns

A lint report (this tool has no ok:false failure envelope — malformed input is itself reported as errors):

  • grade — ready | usable | broken
  • agentReady — whether an agent can use the recipe as-is
  • errors, warnings, infos — counts
  • issues[] — {severity, field, code, message}

Severity meaning: errors break the shared save/lint schema gate (missing schema_version / id / hosts / extract.contentSelectors or content_selectors, forbidden secret keys); warnings degrade quality (bad backend, non-bare host, unrouted knowledge_schema class); infos are nudges.

agentReady: true means save would accept the document before live verify — not that dry-run verify.score will pass.

Example

Call:

{ "playbook_json": "{\"id\":\"spa.example\",\"hosts\":[\"spa.example\"]}" }

Trimmed response:

{
  "grade": "broken",
  "agentReady": false,
  "errors": 2,
  "warnings": 0,
  "issues": [
    { "severity": "error", "field": "schema_version", "code": "missing", "message": "schema_version is required" },
    { "severity": "error", "field": "extract.contentSelectors", "code": "missing", "message": "at least one content selector is required" }
  ]
}