{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/vaquill-ai/json-schema/vaquill-ai-document-schema.json",
  "title": "Document",
  "description": "One file in a matter, and how far its ingestion got.\n\n`status` is the FIVE-value public vocabulary, not the four-label\n`document_status` Postgres enum. A document's status is the status of the\njob that ingested it, and publishing `completed` here beside `succeeded` on\nthe operation that produced it would make a customer map two spellings of\none event. `adapters/status_map` does the translation and refuses anything\nit has not been told about, so a new enum label fails loudly in CI rather\nthan leaking a sixth value.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/vaquill-ai-documents-api-openapi.yml#/components/schemas/Document",
  "properties": {
    "id": {
      "type": "string",
      "title": "Id",
      "description": "Public identifier, `doc_` followed by 32 hex characters."
    },
    "matterId": {
      "type": "string",
      "title": "Matterid",
      "description": "`mat_` identifier of the matter this document lives in."
    },
    "folderId": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Folderid",
      "description": "`fld_` identifier of the folder it is filed under. Absent when unfiled."
    },
    "filename": {
      "type": "string",
      "title": "Filename",
      "description": "Original filename as uploaded, including its extension."
    },
    "contentType": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Contenttype",
      "description": "IANA media type detected at upload, for example `application/pdf`."
    },
    "fileSize": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Filesize",
      "description": "Size of the stored original in bytes."
    },
    "pageCount": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Pagecount",
      "description": "Pages the pipeline read. Absent or zero until ingestion has read the file. This is the number to size a review or matrix run against."
    },
    "chunkCount": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Chunkcount",
      "description": "How many retrieval chunks the document was split into. Absent until ingestion finishes."
    },
    "sourceType": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Sourcetype",
      "description": "How the document entered the workspace. `api` for everything created through this surface; rows made in the web app carry `upload`, `email`, `workflow` or `chat_artifact`. Published as a plain string, so do not branch on it without a fallback."
    },
    "status": {
      "$ref": "#/$defs/OperationStatus",
      "description": "Ingestion status, using the same five public values as an operation. Retrieval, drafting and review can only see the document once this is `succeeded`."
    },
    "isEncrypted": {
      "type": "boolean",
      "title": "Isencrypted",
      "description": "Whether the stored original is encrypted at rest with a per-document key. This is why downloads stream bytes rather than handing back a storage URL.",
      "default": false
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "title": "Createdat",
      "description": "When the document row was created (RFC 3339)."
    },
    "updatedAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "title": "Updatedat",
      "description": "When the document was last modified (RFC 3339)."
    },
    "processedAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "title": "Processedat",
      "description": "When ingestion finished (RFC 3339). Absent while the document is still processing."
    }
  },
  "additionalProperties": false,
  "type": "object",
  "required": [
    "id",
    "matterId",
    "filename",
    "status",
    "createdAt"
  ],
  "$defs": {
    "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."
    }
  }
}