Table Structure Recognition#

Table structure recognition is the pipeline stage that takes a cropped table image (identified by the layout model) and produces a structured grid of typed cells with optional bounding-box provenance. Docling supports three pluggable backends, all sharing a common BaseTableStructureModel interface and a common OTSL intermediate representation.

Model Backends#

The backend is selected by setting pipeline_options.table_structure_options to the corresponding options class 1. All three are enabled via PdfPipelineOptions(do_table_structure=True) 2.

TableFormer V1 — table_structure_model.py
Object-detection-based model from the docling-project/docling-models artifact repo (model_artifacts/tableformer). Controlled by 3:

• do_cell_matching: bool = True — match predictions back to PDF text cells.
• mode: TableFormerMode — ACCURATE (default) or FAST 4.

Download: docling models download --model tableformer 2.

TableFormer V2 — table_structure_model_v2.py
Improved transformer-based model. Uses OTSL token sequences decoded with _decode_otsl_sequence(). Cell matching uses an intersection_over_self > 0.3 threshold to bind PDF text cells to predicted cell bounding boxes 5. Key option 6:

• do_cell_matching: bool = True — note that setting this True can break output when PDF cells span multiple table columns.

Download: docling models download --model tableformerv2 2.

Granite Vision — table_structure_model_granite_vision.py
VLM-based backend using ibm-granite/granite-vision-4.1-4b . Sends a cropped table image to the model with the prompt <tables_otsl> and parses the OTSL string output . No separate cell-matching step — cell text comes directly from model output; bbox is always None on cells produced this way . Requires CUDA for practical performance; uses bfloat16 + optional flash_attention_2 .

OTSL: Open Table Structure Language#

OTSL is the shared intermediate representation for all three backends. It encodes table structure as a 2-D grid of typed tokens terminated by row separators 7:

Example sequence: <ched>Name<ched>Val<nl><fcel>Foo<fcel>42<nl> .

The OTSL parser handles three serialisation styles — closed <tag>text</tag>, open <tag>text<next> (ibm-granite output), and self-closing <tag/> — and optionally strips an outer <otsl>…</otsl> wrapper . The parsed output is a flat list[TableCell] plus num_rows/num_cols counts stored in Table.otsl_seq 8.

TableItem.export_to_otsl() in docling-core can re-serialize any parsed table back to OTSL, with an optional add_cell_location=True flag to embed bounding-box coordinates inline 7.

Cell Data Model#

Each cell is a TableCell 9 with:

• text — plain-text content
• bbox — optional page-level bounding box (absent for Granite Vision output)
• row_span / col_span and start_/end_row/col_offset_idx — grid span indices
• column_header, row_header, row_section — semantic role flags

RichTableCell extends this with a ref: RefItem pointer to a nested DocItem (e.g., an image or formatted text block). The 2-D grid is reconstructed by TableData.grid as a computed field 10.

Configuration Reference#

from docling.datamodel.pipeline_options import (
    PdfPipelineOptions,
    TableStructureOptions, # V1
    TableStructureV2Options, # V2
    GraniteVisionTableStructureOptions, # Granite Vision
    TableFormerMode,
)

opts = PdfPipelineOptions()
opts.do_table_structure = True

# V1 — accurate mode
opts.table_structure_options = TableStructureOptions(
    do_cell_matching=True,
    mode=TableFormerMode.ACCURATE,
)

# V2
opts.table_structure_options = TableStructureV2Options(do_cell_matching=True)

# Granite Vision (requires pip install docling[vlm])
opts.table_structure_options = GraniteVisionTableStructureOptions()

2

Key Source Files#