{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/vaquill-ai/json-schema/vaquill-ai-page-matter-summary-schema.json",
  "title": "Page[MatterSummary]",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/vaquill-ai-matter-summary-api-openapi.yml#/components/schemas/Page_MatterSummary_",
  "properties": {
    "data": {
      "items": {
        "$ref": "#/$defs/MatterSummary"
      },
      "type": "array",
      "title": "Data",
      "description": "The rows in this window, in the collection's default order."
    },
    "pagination": {
      "$ref": "#/$defs/Pagination",
      "description": "Where this window sits in the full result set."
    }
  },
  "additionalProperties": false,
  "type": "object",
  "required": [
    "data",
    "pagination"
  ],
  "$defs": {
    "MatterSummary": {
      "properties": {
        "id": {
          "type": "string",
          "title": "Id",
          "description": "`sum_` identifier. The same id the operation's resource carries, and the only id this API publishes for a summary."
        },
        "matterId": {
          "type": "string",
          "title": "Matterid",
          "description": "The `mat_` matter this summary covers."
        },
        "status": {
          "$ref": "#/$defs/OperationStatus",
          "description": "The generation's status, in the same five values every operation uses."
        },
        "altitude": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Altitude",
          "description": "How much detail was synthesized. `executive` or `detailed`; read it as an open string, because the column carries no constraint. Null on the one row shape where it is genuinely unknown: `matter_summary_jobs` does not record the altitude, so a job whose summary row is gone has nothing to report and the commoner answer would be an invention."
        },
        "title": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Title",
          "description": "The title the synthesizer gave the matter. Null until it runs."
        },
        "matterType": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Mattertype",
          "description": "What the classifier decided the matter is."
        },
        "isStale": {
          "type": "boolean",
          "title": "Isstale",
          "description": "True when the matter's documents have changed since this summary was built. Computed per request, never stored. A summary can also refresh ITSELF: a document change schedules a debounced regeneration for an altitude that already has a completed summary, so `isStale` can flip between two polls with no call from you."
        },
        "docCount": {
          "type": "integer",
          "title": "Doccount",
          "description": "Documents in the matter right now."
        },
        "docCountUsed": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Doccountused",
          "description": "Documents this generation read."
        },
        "docCountExcluded": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Doccountexcluded",
          "description": "Documents this generation skipped."
        },
        "warnings": {
          "items": {
            "type": "string"
          },
          "type": "array",
          "title": "Warnings",
          "description": "What the pipeline wants you to know about this result, if anything."
        },
        "createdAt": {
          "type": "string",
          "format": "date-time",
          "title": "Createdat",
          "description": "When the generation was requested."
        },
        "completedAt": {
          "anyOf": [
            {
              "type": "string",
              "format": "date-time"
            },
            {
              "type": "null"
            }
          ],
          "title": "Completedat",
          "description": "When the summary finished, read from the summary itself rather than from the job, which records no completion time."
        },
        "sections": {
          "anyOf": [
            {
              "items": {
                "$ref": "#/$defs/MatterSummarySection"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "title": "Sections",
          "description": "The rendered narrative. Present only on the by-id read; the list omits it rather than sending an empty array, so `null` here means 'not included in this response' and `[]` means 'nothing was written'."
        }
      },
      "additionalProperties": false,
      "type": "object",
      "required": [
        "id",
        "matterId",
        "status",
        "isStale",
        "docCount",
        "createdAt"
      ],
      "title": "MatterSummary",
      "description": "One generation of a matter summary, and its content once it has one."
    },
    "MatterSummarySection": {
      "properties": {
        "id": {
          "type": "string",
          "title": "Id",
          "description": "Stable within this summary."
        },
        "title": {
          "type": "string",
          "title": "Title",
          "description": "The section heading."
        },
        "position": {
          "type": "integer",
          "title": "Position",
          "description": "Reading order within the summary."
        },
        "claims": {
          "items": {
            "$ref": "#/$defs/SummaryClaim"
          },
          "type": "array",
          "title": "Claims",
          "description": "The section's claims."
        }
      },
      "additionalProperties": false,
      "type": "object",
      "required": [
        "id",
        "title",
        "position"
      ],
      "title": "MatterSummarySection",
      "description": "One heading of the narrative."
    },
    "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."
    },
    "Pagination": {
      "properties": {
        "limit": {
          "type": "integer",
          "title": "Limit",
          "description": "The `limit` that was applied to this request."
        },
        "offset": {
          "type": "integer",
          "title": "Offset",
          "description": "The `offset` that was applied to this request."
        },
        "total": {
          "type": "integer",
          "title": "Total",
          "description": "Total rows matching the filter, not the number returned in `data`. Use it to size a job before running it."
        },
        "hasMore": {
          "type": "boolean",
          "title": "Hasmore",
          "description": "True when rows remain beyond this window. Derived from `offset + len(data) < total`, so a full final page correctly reports `false` rather than sending you after an empty page."
        }
      },
      "additionalProperties": false,
      "type": "object",
      "required": [
        "limit",
        "offset",
        "total",
        "hasMore"
      ],
      "title": "Pagination",
      "description": "Where the caller is, and whether there is more.\n\n`total` is the count of rows matching the filter, not the count returned,\nso a caller can size a job before running it."
    },
    "SummaryCitation": {
      "properties": {
        "label": {
          "type": "integer",
          "title": "Label",
          "description": "The bracketed marker this citation carries within its section, numbered from 1 per section. Two sections both start at [1]."
        },
        "documentId": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Documentid",
          "description": "The `doc_` document this passage came from."
        },
        "documentName": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Documentname",
          "description": "The document's filename when the summary was generated."
        },
        "quote": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Quote",
          "description": "The verbatim passage. Locate this string in the document's text to resolve the citation; there is no offset to trust."
        },
        "pageStart": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Pagestart",
          "description": "First page the quote appears on."
        },
        "pageEnd": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Pageend",
          "description": "Last page the quote appears on."
        },
        "sourceAvailable": {
          "type": "boolean",
          "title": "Sourceavailable",
          "description": "False when the cited document has since been removed from the workspace. The quote is a snapshot and stays accurate; there is simply nothing left to open."
        }
      },
      "additionalProperties": false,
      "type": "object",
      "required": [
        "label",
        "sourceAvailable"
      ],
      "title": "SummaryCitation",
      "description": "One passage behind a claim, snapshotted when the summary was generated."
    },
    "SummaryClaim": {
      "properties": {
        "id": {
          "type": "string",
          "title": "Id",
          "description": "Stable within this summary."
        },
        "text": {
          "type": "string",
          "title": "Text",
          "description": "The claim, as one sentence."
        },
        "position": {
          "type": "integer",
          "title": "Position",
          "description": "Reading order within the section."
        },
        "claimType": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Claimtype",
          "description": "What kind of assertion this is, for example `general` or `event`. Publisher-controlled and open: read it, do not switch on a closed list."
        },
        "eventDate": {
          "anyOf": [
            {
              "type": "string",
              "format": "date"
            },
            {
              "type": "null"
            }
          ],
          "title": "Eventdate",
          "description": "The date the claim is about, when it names one."
        },
        "confidence": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Confidence",
          "description": "0 to 1."
        },
        "citations": {
          "items": {
            "$ref": "#/$defs/SummaryCitation"
          },
          "type": "array",
          "title": "Citations",
          "description": "Every passage behind this claim."
        }
      },
      "additionalProperties": false,
      "type": "object",
      "required": [
        "id",
        "text",
        "position"
      ],
      "title": "SummaryClaim",
      "description": "One assertion inside a section, with the passages that support it."
    }
  }
}