{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/vaquill-ai/json-schema/vaquill-ai-playbook-schema.json",
  "title": "Playbook",
  "description": "One organization playbook, with every position it holds.\n\nPositions are returned in full rather than summarized. A playbook is the\ninput to a review, so a caller that cannot read the positions cannot tell\nwhat its reviews are being measured against, and a separate positions\nendpoint would make the common case two calls.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/vaquill-ai-playbooks-api-openapi.yml#/components/schemas/Playbook",
  "properties": {
    "id": {
      "type": "string",
      "title": "Id",
      "description": "Public identifier, `pbk_` followed by 32 hex characters."
    },
    "name": {
      "type": "string",
      "title": "Name",
      "description": "The playbook's display name."
    },
    "description": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Description",
      "description": "Free-text description of what this playbook covers."
    },
    "contractType": {
      "type": "string",
      "title": "Contracttype",
      "description": "Which contract type this playbook governs. Fixed at creation: changing it would silently redirect which reviews resolve it."
    },
    "positions": {
      "additionalProperties": {
        "$ref": "#/$defs/PlaybookPosition"
      },
      "type": "object",
      "title": "Positions",
      "description": "Every negotiating position the playbook holds, keyed by clause-type slug. Returned in full, because a caller that cannot read the positions cannot tell what its reviews are measured against."
    },
    "isDefault": {
      "type": "boolean",
      "title": "Isdefault",
      "description": "True when reviews of this contract type resolve to this playbook if none is named. Read-only here: exactly one default per contract type is enforced by the database, and this API cannot set it.",
      "default": false
    },
    "sourceFilename": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Sourcefilename",
      "description": "Filename of the exemplar this playbook was extracted from, when it was imported rather than authored by hand."
    },
    "createdAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "title": "Createdat",
      "description": "When the playbook was created (RFC 3339)."
    },
    "updatedAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "title": "Updatedat",
      "description": "When the playbook was last modified (RFC 3339)."
    }
  },
  "additionalProperties": false,
  "type": "object",
  "required": [
    "id",
    "name",
    "contractType"
  ],
  "$defs": {
    "EscalationCondition": {
      "properties": {
        "attribute": {
          "type": "string",
          "enum": [
            "clause_severity",
            "counterparty_paper",
            "contract_value",
            "governing_law"
          ],
          "title": "Attribute",
          "description": "What to test. `clause_severity` is the review's own finding and needs no input; the other three come from the review request's `paperSide` and `dealContext`. A rule naming one you did not supply simply does not fire."
        },
        "operator": {
          "type": "string",
          "enum": [
            "eq",
            "neq",
            "gt",
            "gte",
            "lt",
            "lte",
            "in"
          ],
          "title": "Operator",
          "description": "How to compare `attribute` against `value`. Use `in` with a comma-separated `value`.",
          "default": "eq"
        },
        "value": {
          "type": "string",
          "maxLength": 200,
          "title": "Value",
          "description": "What to compare against, always a string and parsed per attribute: `red`, `true`, `1000000`, `CA,NY`."
        },
        "escalateTo": {
          "type": "string",
          "enum": [
            "manager",
            "partner",
            "gc"
          ],
          "title": "Escalateto",
          "description": "The sign-off level this rule raises the clause to when it fires.",
          "default": "partner"
        },
        "note": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 280
            },
            {
              "type": "null"
            }
          ],
          "title": "Note",
          "description": "Short explanation of why this escalation exists, shown to whoever reviews the finding."
        }
      },
      "additionalProperties": false,
      "type": "object",
      "required": [
        "attribute",
        "value"
      ],
      "title": "EscalationCondition",
      "description": "A rule that RAISES a clause's required sign-off when it holds.\n\nThis is what lets a playbook say \"partner normally, but GC if the deal is\nover a million, or if it is on their paper\". The value stays a string across\nevery attribute so the stored shape is uniform; it is parsed per attribute\nwhen the rule is evaluated."
    },
    "PlaybookPosition": {
      "properties": {
        "standardPosition": {
          "type": "string",
          "maxLength": 8000,
          "title": "Standardposition",
          "description": "The position the organization opens with on this clause type. Required: a position with no standard is not a position."
        },
        "acceptableRange": {
          "type": "string",
          "maxLength": 4000,
          "title": "Acceptablerange",
          "description": "Free-text summary of the acceptable zone. Complements `fallbackLadder` rather than duplicating it: this is the summary, the ladder is the ordered retreat."
        },
        "escalationTriggers": {
          "items": {
            "type": "string"
          },
          "type": "array",
          "maxItems": 50,
          "title": "Escalationtriggers",
          "description": "Free-text conditions that should raise a human's attention. Descriptive only; the machine-evaluated rules are `escalationConditions`."
        },
        "fallbackLadder": {
          "items": {
            "type": "string"
          },
          "type": "array",
          "maxItems": 10,
          "title": "Fallbackladder",
          "description": "Ordered concrete retreat positions, BEST acceptable first. The reviewer steps down this ladder when the standard position is rejected."
        },
        "dealBreaker": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 4000
            },
            {
              "type": "null"
            }
          ],
          "title": "Dealbreaker",
          "description": "The walk-away floor. A term at or below this is forced to red regardless of what the model reads. Absent means there is no hard floor, which is not the same as a floor of nothing."
        },
        "priority": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "must_have",
                "should_have",
                "nice_to_have"
              ]
            },
            {
              "type": "null"
            }
          ],
          "title": "Priority",
          "description": "How much this clause matters relative to the others in the playbook."
        },
        "approvalLevel": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "none",
                "manager",
                "partner",
                "gc"
              ]
            },
            {
              "type": "null"
            }
          ],
          "title": "Approvallevel",
          "description": "The sign-off a deviation from this position needs. Feeds a review's `approvalGate`, which is REPORTED and never enforced."
        },
        "escalationConditions": {
          "items": {
            "$ref": "#/$defs/EscalationCondition"
          },
          "type": "array",
          "maxItems": 20,
          "title": "Escalationconditions",
          "description": "Machine-evaluated rules that raise the required sign-off when they hold."
        },
        "rationale": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 2000
            },
            {
              "type": "null"
            }
          ],
          "title": "Rationale",
          "description": "Why the organization takes this position. Carried into review findings so a reviewer can see the reasoning."
        },
        "riskWeight": {
          "anyOf": [
            {
              "type": "integer",
              "maximum": 5.0,
              "minimum": 0.0
            },
            {
              "type": "null"
            }
          ],
          "title": "Riskweight",
          "description": "0 to 5, multiplied by severity to weight the compliance score. Absent falls through to the clause-type default rather than to zero."
        },
        "enabled": {
          "type": "boolean",
          "title": "Enabled",
          "description": "False keeps the position on the playbook but excludes it from review and drafting. This is how an alternative is parked without being deleted.",
          "default": true
        }
      },
      "additionalProperties": false,
      "type": "object",
      "required": [
        "standardPosition",
        "acceptableRange"
      ],
      "title": "PlaybookPosition",
      "description": "The organization's negotiating position on one clause type.\n\nBoth a request and a response shape, which is a deliberate exception to the\n\"read models are looser than write models\" rule the resources follow. A\nposition is authored by the customer rather than produced by a model, so\nthere is no dirty-legacy-value problem to be loose about, and one shape means\na caller can read a playbook, edit one field and write it straight back."
    }
  }
}