{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/tale-dev/main/json-schema/tale-dev-document-schema.json",
  "title": "Document",
  "x-generated": "2026-10-09",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/tale-dev-openapi.yml#/components/schemas/Document",
  "type": "object",
  "required": [
    "id",
    "title",
    "contentHash",
    "createdBy",
    "createdAt",
    "updatedAt"
  ],
  "properties": {
    "id": {
      "type": "string"
    },
    "title": {
      "type": "string"
    },
    "content": {
      "type": [
        "string",
        "null"
      ],
      "description": "Inline text; null for a file-backed document — read its bytes at `GET /api/v1/documents/{id}/content` — and in listings"
    },
    "fileId": {
      "type": [
        "string",
        "null"
      ],
      "description": "The blob reference"
    },
    "mimeType": {
      "type": [
        "string",
        "null"
      ]
    },
    "extension": {
      "type": [
        "string",
        "null"
      ]
    },
    "sourceProvider": {
      "type": [
        "string",
        "null"
      ]
    },
    "teamIds": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "The audience: the teams that may read the document, by id; empty = organization-wide. Owners and admins read every team library regardless."
    },
    "teamId": {
      "type": [
        "string",
        "null"
      ],
      "deprecated": true,
      "description": "The first team of `teamIds`, or null — the pre-1.17.0 single-team spelling; read `teamIds`"
    },
    "folderId": {
      "type": [
        "string",
        "null"
      ]
    },
    "metadata": {
      "type": [
        "object",
        "null"
      ],
      "additionalProperties": true
    },
    "contentHash": {
      "type": [
        "string",
        "null"
      ],
      "description": "SHA-256 (hex) of the stored bytes when the platform computed one — a knowledge entry’s content, a synced file; null otherwise. A column of its own, never a key in `metadata`"
    },
    "createdBy": {
      "type": "string"
    },
    "createdAt": {
      "type": "integer",
      "minimum": 0,
      "description": "Epoch milliseconds"
    },
    "updatedAt": {
      "type": "integer",
      "minimum": 0,
      "description": "Epoch milliseconds"
    },
    "indexing": {
      "type": "object",
      "required": [
        "status"
      ],
      "additionalProperties": false,
      "description": "Where a file-backed document stands in the search corpus — absent for a content-only document (never indexed) and for a blob the platform does not track. Poll it after a create or a `retry-indexing`.",
      "properties": {
        "status": {
          "type": "string",
          "enum": [
            "pending",
            "queued",
            "running",
            "completed",
            "failed",
            "unsupported",
            "skipped"
          ],
          "description": "`pending` — never queued; `skipped` — the file opts out of indexing; `unsupported` — TERMINAL: the platform cannot index these bytes and a retry reproduces the answer, `errorCode` says why (`unsupported_type`, `image_no_vision`, `empty`, `not_text`, `malformed`); `failed` — see `error` / `errorCode`: the job retries `embedding_upstream`, `indexer_error` and `index_rebuilding` by itself, `usage_limit` resumes by itself once the usage limit allows it, the rest wait for an admin (a provider account, the organization’s policy) and a `retry-indexing`; a `failed` with no `errorCode` is a failure the platform settled without classifying it, usually an indexing run that stopped before it finished (a lost job, a stopped worker) — request a `retry-indexing` rather than wait for one"
        },
        "indexedAt": {
          "type": "integer",
          "minimum": 0,
          "description": "Epoch ms of the last completed indexing"
        },
        "error": {
          "type": "string",
          "description": "A sentence for a person, present with `failed` and `unsupported`; never a storage-engine diagnostic — the raw cause stays in the platform log."
        },
        "errorCode": {
          "type": "string",
          "enum": [
            "unsupported_type",
            "image_no_vision",
            "empty",
            "not_text",
            "malformed",
            "secret_detected",
            "pii_blocked",
            "embedding_not_configured",
            "embedding_provider_refused",
            "embedding_upstream",
            "index_rebuilding",
            "index_repair_failed",
            "usage_limit",
            "indexer_error"
          ],
          "description": "The stable cause to branch on, present with `unsupported`, and with `failed` whenever the platform classified the cause — a `failed` without one was settled unclassified, usually after its indexing run stopped before it finished; request a `retry-indexing` for it. Terminal (`unsupported`): `unsupported_type` — no extractor for the type; `image_no_vision` — an image and no OCR lane; `empty` — no text to index; `not_text` — binary bytes behind a text extension, re-export as UTF-8; `malformed` — the bytes do not parse as the format the extension claims. Retried by the job (`failed`): `embedding_upstream` — the provider was unreachable, rate-limited or 5xx; `indexer_error` — a platform-side store fault; `index_rebuilding` — the search index is being rebuilt. Waits for a usage limit (`failed`): `usage_limit` — a limit that binds whoever the file is indexed for (its uploader, a synced drive’s owner, the organization for an emailed attachment) has too little room for its embeddings; indexing resumes by itself within the hour after the limit resets or is raised, after what it already embedded. Waits for an admin (`failed`): `embedding_not_configured`, `embedding_provider_refused` (the provider refused the account or credential, the model answers vectors of another width than the settings state, or the platform cannot use the embedding credential — none configured, deleted, disabled or unreadable), `index_repair_failed`, `secret_detected`, `pii_blocked`. Saving corrected embedding settings, or adding or repairing the credential the embedding model uses, re-queues every document that failed on the embedding model."
        }
      }
    }
  }
}