{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/vaquill-ai/json-schema/vaquill-ai-matrix-schema.json",
  "title": "Matrix",
  "description": "The grid header plus its axes. Cells are a separate, paged read.\n\nRows and columns are inlined because they are bounded and because a cell is\nunreadable without them: a cell names a row id and a column id and nothing\nelse, so a client that could not resolve those would have to page the whole\ngrid to interpret one answer.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/vaquill-ai-matrices-api-openapi.yml#/components/schemas/Matrix",
  "properties": {
    "id": {
      "type": "string",
      "title": "Id",
      "description": "Public identifier, `mtx_` followed by 32 hex characters."
    },
    "matterId": {
      "type": "string",
      "title": "Matterid",
      "description": "`mat_` identifier of the matter this matrix belongs to."
    },
    "title": {
      "type": "string",
      "title": "Title",
      "description": "Display title for the matrix."
    },
    "description": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Description",
      "description": "Free-text description of what the matrix is for."
    },
    "status": {
      "$ref": "#/$defs/OperationStatus",
      "description": "Matrix status, using the same five public values as an operation."
    },
    "columns": {
      "items": {
        "$ref": "#/$defs/MatrixColumn"
      },
      "type": "array",
      "title": "Columns",
      "description": "Every column, inlined. A cell names only ids, so these are what make one readable."
    },
    "rows": {
      "items": {
        "$ref": "#/$defs/MatrixRow"
      },
      "type": "array",
      "title": "Rows",
      "description": "Every row, inlined, one per document."
    },
    "cellCount": {
      "type": "integer",
      "title": "Cellcount",
      "description": "Total cells in the grid, which is rows times columns.",
      "default": 0
    },
    "pendingCellCount": {
      "type": "integer",
      "title": "Pendingcellcount",
      "description": "Cells that have not produced an answer yet. Zero means extraction is complete.",
      "default": 0
    },
    "errorCellCount": {
      "type": "integer",
      "title": "Errorcellcount",
      "description": "Cells whose extraction failed. These are distinct from cells that succeeded with a null answer.",
      "default": 0
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "title": "Createdat",
      "description": "When the matrix was created (RFC 3339)."
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "title": "Updatedat",
      "description": "When the matrix was last updated (RFC 3339)."
    }
  },
  "additionalProperties": false,
  "type": "object",
  "required": [
    "id",
    "matterId",
    "title",
    "status",
    "createdAt",
    "updatedAt"
  ],
  "$defs": {
    "MatrixColumn": {
      "properties": {
        "id": {
          "type": "string",
          "title": "Id",
          "description": "Public identifier for the column, `col_` followed by 32 hex characters. Cells reference it as `columnId`."
        },
        "label": {
          "type": "string",
          "title": "Label",
          "description": "Column heading."
        },
        "question": {
          "type": "string",
          "title": "Question",
          "description": "The question asked of every document in this column."
        },
        "columnType": {
          "type": "string",
          "title": "Columntype",
          "description": "What shape of answer this column asks for. Published as a plain string, since production predates this API."
        },
        "options": {
          "anyOf": [
            {
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "title": "Options",
          "description": "Allowed answers for a select column."
        },
        "instructions": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Instructions",
          "description": "Extra extractor guidance scoped to this column."
        },
        "dependsOnColumnId": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Dependsoncolumnid",
          "description": "`col_` identifier of the column this one is conditional on, or null when it always runs."
        },
        "gateExpression": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Gateexpression",
          "description": "The condition on the upstream answer that has to hold for this column to run. Null means it always runs when its dependency has answered."
        },
        "injectUpstream": {
          "type": "boolean",
          "title": "Injectupstream",
          "description": "Whether the upstream column's answer is prepended to this column's prompt.",
          "default": false
        },
        "position": {
          "type": "integer",
          "title": "Position",
          "description": "Left-to-right position of the column in the grid. Ascending, and not necessarily contiguous: deleting a column leaves a gap rather than renumbering."
        }
      },
      "additionalProperties": false,
      "type": "object",
      "required": [
        "id",
        "label",
        "question",
        "columnType",
        "position"
      ],
      "title": "MatrixColumn",
      "description": "One column of the grid, as stored."
    },
    "MatrixRow": {
      "properties": {
        "id": {
          "type": "string",
          "title": "Id",
          "description": "Public identifier for the row, `row_` followed by 32 hex characters. Cells reference it as `rowId`."
        },
        "documentId": {
          "type": "string",
          "title": "Documentid",
          "description": "`doc_` identifier of the document this row represents."
        },
        "filename": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Filename",
          "description": "Filename of that document, joined in for display."
        },
        "position": {
          "type": "integer",
          "title": "Position",
          "description": "Top-to-bottom position of the row in the grid. Ascending, and not necessarily contiguous: deleting a row leaves a gap rather than renumbering."
        }
      },
      "additionalProperties": false,
      "type": "object",
      "required": [
        "id",
        "documentId",
        "position"
      ],
      "title": "MatrixRow",
      "description": "One document in the grid."
    },
    "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."
    }
  }
}