{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/vaquill-ai/json-schema/vaquill-ai-playbook-extraction-schema.json",
  "title": "PlaybookExtraction",
  "description": "What an extraction found, in the shape a playbook takes.\n\nA running extraction is a `200` with an EMPTY `positions` map and a truthful\nstatus, never a `404`: a 404 would be indistinguishable from an extraction\nthat never existed. Why one FAILED lives on the operation rather than here,\nso there is exactly one sanitizer for internal error text on this surface.",
  "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/PlaybookExtraction",
  "properties": {
    "id": {
      "type": "string",
      "title": "Id",
      "description": "Public identifier, `pex_` followed by 32 hex characters."
    },
    "status": {
      "$ref": "#/$defs/OperationStatus",
      "description": "Where the extraction got to, in the same five values an operation uses. `positions` is empty until it reads `succeeded`."
    },
    "contractType": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Contracttype",
      "description": "The contract type that was pinned or detected. Pass it to `playbooks.create` when you adopt these positions: a playbook's type decides which reviews resolve it."
    },
    "positions": {
      "additionalProperties": {
        "$ref": "#/$defs/PlaybookPosition"
      },
      "type": "object",
      "title": "Positions",
      "description": "The extracted positions, keyed by clause type. Review them, then send the map you want to keep to `playbooks.create`. Nothing here has been saved as a playbook."
    },
    "truncated": {
      "type": "boolean",
      "title": "Truncated",
      "description": "True when the contract exceeded the extractor's block ceiling and some clauses were not read. The positions returned are correct; they are not complete. Split the contract and extract the remainder separately.",
      "default": false
    },
    "sourceDocumentId": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Sourcedocumentid",
      "description": "`doc_` identifier of the document this was read from, when one was named. Null for an extraction from `contractText`, which keeps no file."
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "title": "Createdat",
      "description": "When the extraction was accepted (RFC 3339)."
    },
    "completedAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "title": "Completedat",
      "description": "When it reached a terminal status (RFC 3339)."
    }
  },
  "additionalProperties": false,
  "type": "object",
  "required": [
    "id",
    "status",
    "createdAt"
  ],
  "$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."
    },
    "OperationStatus": {
      "type": "string",
      "enum": [
        "queued",
        "running",
        "succeeded",
        "failed",
        "cancelled"
      ],
      "title": "OperationStatus",
      "description": "The public five. There is no sixth, and there are no synonyms.\n\nInternal vocabularies spell terminal success `completed`, `ready`,\n`extracted`, `succeeded` and `fresh`; terminal failure `failed` and `error`;\nqueued `pending`, `queued` and `draft`. All of that is collapsed here by\n`app.workspace_api.adapters.status_map`, which refuses to guess."
    },
    "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."
    }
  }
}