PrintedTableResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/kamai-io/json-schema/kamai-io-printed-table-response-schema.json",
  "title": "PrintedTableResponse",
  "x-generated": "2026-11-13",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/kamai-io-openapi.json#/components/schemas/PrintedTableResponse",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "ok",
        "not_found",
        "unavailable"
      ],
      "title": "Status",
      "description": "`ok`; `not_found`: no table has this id on this sheet now (see `reason`); `unavailable`: the tables could not be read just now, retry."
    },
    "table": {
      "anyOf": [
        {
          "$ref": "#/$defs/PrintedTable"
        },
        {
          "type": "null"
        }
      ],
      "description": "The table (when `ok`)."
    },
    "total_rows": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Total Rows",
      "description": "All the table's rows, across pages."
    },
    "next_cursor": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Next Cursor",
      "description": "Pass it as `cursor` for the next rows, with the same `format`; `null` on the last page."
    },
    "reason": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "re_extracted",
            "unknown"
          ]
        },
        {
          "type": "null"
        }
      ],
      "title": "Reason",
      "description": "Why `not_found`: `re_extracted`, the sheet was read again since this id was given (list the tables for the new id); `unknown`, no such table on this sheet."
    },
    "note": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Note",
      "description": "A plain-English explanation: why `not_found`/`unavailable`, or what `lossy` means."
    },
    "table_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Table Id",
      "description": "The id asked for (on `not_found` and `unavailable`)."
    }
  },
  "additionalProperties": true,
  "type": "object",
  "required": [
    "status"
  ],
  "$defs": {
    "PrintedTable": {
      "properties": {
        "id": {
          "type": "string",
          "title": "Id",
          "description": "`{blueprint_id}.{rev}.t{n}`: this table in this extraction of the sheet. Use it exactly as returned; never build or edit one (a malformed id is a 422). It changes whenever the sheet is extracted again."
        },
        "blueprint_id": {
          "type": "string",
          "title": "Blueprint Id",
          "description": "The sheet the table is printed on."
        },
        "title": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Title",
          "description": "The table's title as printed, or `null`."
        },
        "source": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Source",
          "description": "How the table was read: `pdf-text-layer` (the PDF's own text) or `ocr` (a scanned or image table); `unknown` otherwise."
        },
        "bbox": {
          "anyOf": [
            {
              "items": {
                "type": "number"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "title": "Bbox",
          "description": "Where the table sits, [x0, y0, x1, y1] in fractions (0..1) of the page; `null` when unknown."
        },
        "complete": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "title": "Complete",
          "description": "`false` when the sheet's table reading did not finish, so tables (or the emptiness of an `empty` sheet) may be incomplete."
        },
        "coverage": {
          "anyOf": [
            {
              "$ref": "#/$defs/TableCoverage"
            },
            {
              "type": "null"
            }
          ],
          "description": "How many grid cells were filled; a text-layer table can miss cells. `null` when not measured."
        },
        "degraded": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "title": "Degraded",
          "description": "`true` when the high-resolution re-read did not land, so the text is the coarser first reading."
        },
        "lossy": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "title": "Lossy",
          "description": "`true` when the sheet was extracted before the structured form existed: rows are rebuilt from the markdown, line breaks inside cells are flattened, short rows are padded, and there are no cell boxes."
        },
        "n_rows": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "N Rows",
          "description": "Data rows, header not counted."
        },
        "n_cols": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "N Cols",
          "description": "Columns."
        },
        "chars": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Chars",
          "description": "Size of the table's markdown in characters, a guide to its length."
        },
        "header": {
          "anyOf": [
            {
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "title": "Header",
          "description": "Column headings as printed (`format=rows`)."
        },
        "rows": {
          "anyOf": [
            {
              "items": {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "title": "Rows",
          "description": "This page of rows, each as wide as `header`; line breaks inside cells are kept unless `lossy` (`format=rows`)."
        },
        "header_boxes": {
          "anyOf": [
            {
              "items": {
                "anyOf": [
                  {
                    "items": {
                      "type": "number"
                    },
                    "type": "array"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "title": "Header Boxes",
          "description": "Each heading's box in page fractions, or `null` (always `null` when `lossy`)."
        },
        "cell_boxes": {
          "anyOf": [
            {
              "items": {
                "items": {
                  "anyOf": [
                    {
                      "items": {
                        "type": "number"
                      },
                      "type": "array"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "type": "array"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "title": "Cell Boxes",
          "description": "Each cell's box in page fractions, parallel to `rows`, or `null` (always `null` when `lossy`)."
        },
        "markdown": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Markdown",
          "description": "This page of rows as one markdown table, header repeated on every page (`format=markdown`)."
        }
      },
      "additionalProperties": true,
      "type": "object",
      "required": [
        "id",
        "blueprint_id"
      ],
      "title": "PrintedTable",
      "description": "One table. `format=rows` gives `header`, `rows` and the boxes; `format=markdown` gives `markdown`."
    },
    "TableCoverage": {
      "properties": {
        "cells_present": {
          "type": "integer",
          "title": "Cells Present",
          "description": "Cells the extraction filled."
        },
        "cells_total": {
          "type": "integer",
          "title": "Cells Total",
          "description": "Cells in the table's grid."
        }
      },
      "additionalProperties": true,
      "type": "object",
      "required": [
        "cells_present",
        "cells_total"
      ],
      "title": "TableCoverage"
    }
  }
}