Layout model classifies grid-lined forms as Table instead of Form — Heron and Heron-101

[ixtrix]

Description

Both docling-layout-heron and docling-layout-heron-101 misclassify PDF forms with grid lines as Table instead of Form, even though both models have Form (label 15) and Key-Value Region (label 16) in their id2label config.

When the layout model classifies a form region as Table, TableFormer then attempts to reconstruct it as a data table, producing severely garbled output with content duplicated across 7-8 identical columns.

Reproduction

Input: Any PDF form with visible grid lines containing key-value pairs (e.g., an order form with fields like Customer, Date, Account Name, Address, etc. laid out in a bordered grid).

Docling version: 2.82.0
Layout models tested: docling-layout-heron, docling-layout-heron-101
Pipeline: StandardPdfPipeline with TableFormerMode.ACCURATE

from docling.document_converter import DocumentConverter
result = DocumentConverter().convert("order_form.pdf")
print(result.document.export_to_markdown())

Expected: The form region should be classified as Form or Key-Value Region, and the output should preserve key-value pairs:

Date: 16/03/2026
Account Name: Scope Furnishing Ltd
Local Address: Lowlands Industrial Estate, ...

Actual: The form is classified as Table, and TableFormer produces output like:

| Customer | Customer | Customer | Customer | Customer | Customer | Customer |
|---|---|---|---|---|---|---|
| Date 16/03/2026 | Date 16/03/2026 | Date 16/03/2026 | Date 16/03/2026 | ...

Every row's content is duplicated across all columns.

Analysis

• The Form label (15) and Key-Value Region label (16) exist in both Heron and Heron-101 config.json
• Neither model fires these labels on grid-lined forms — the grid lines cause the model to predict Table instead
• Disabling do_table_structure=False doesn't help — the region is still classified as Table and dumped into a single cell
• The embedded text layer is correct (all content is present), only the structural classification is wrong

Impact

Forms with grid lines are extremely common in business documents (order forms, application forms, invoices with header sections). This misclassification makes Docling unusable for these documents without manual intervention or VLM fallback.

Environment

• Docling 2.82.0
• GPU: NVIDIA Blackwell RTX PRO 6000
• OS: Ubuntu (Debian-based)
• Python 3.12

[dosubot]

Hi @ixtrix! I'm Dosu and I’m helping the docling team.

This is a well-documented issue that touches on a few interacting architectural constraints in Docling's layout pipeline. Here's what's happening under the hood:

Root cause — the postprocessor explicitly prefers Table over Key-Value Region: The LayoutPostprocessor has a cross-type conflict resolution rule that removes a KEY_VALUE_REGION cluster if it overlaps >90% with a TABLE cluster at similar confidence [1]. So even if the model does sometimes fire the Form or KV label, the postprocessor may silently discard it in favor of the Table prediction when grid lines are present.

Form/KV Region support is structurally incomplete: Even when Form or Key-Value Region labels survive postprocessing, they become bare ContainerElement wrappers with no structural enrichment — unlike Table, which gets full TableFormer cell/row/column reconstruction [2]. This gap is tracked in Discussion #301, which explicitly notes that "both classes are currently ignored in downstream processing" and calls for evaluating where form/KV detection causes confusion with table detections.

No runtime override available: The per-label confidence thresholds and the Table-over-KV conflict rule are hardcoded class constants in LayoutPostprocessor [3]. There's no PdfPipelineOptions knob to remap or override them. Interestingly, LayoutPredictor in docling-ibm-models does have a blacklist_classes parameter (with {"Form", "Key-Value Region"} mentioned as an example in comments) [4], but it's not surfaced through the public pipeline API.

Potential workarounds:

• VLM pipeline: The VlmPipeline may handle these forms better since it uses semantic understanding rather than geometric layout detection [5].
• Post-processing: Manually reclassify elements in the output DoclingDocument by inspecting their content structure, though this requires custom code.
• The annotation ambiguity between grid-lined forms and tables is also acknowledged in Issue #2142, where the boundary between Table and Key-Value Region for grid-lined content was flagged as unresolved.

In short — the model may actually predict Form/KV in some cases, but the postprocessor's overlap rule and the lack of downstream Form enrichment mean the pipeline effectively funnels grid-lined content into the Table path regardless.

To reply, just mention @dosu.

---

Docs are dead. Just use Dosu.