Document Layout and Reading Order#

This article covers three closely related failure modes in Docling's standard PDF pipeline: (1) form-like pages being misclassified as FORM or KEY_VALUE_REGION regions by the layout model, (2) silent reading-order corruption in mixed-content documents, and (3) how the reading-order model internally handles ContainerElement instances for FORM and KEY_VALUE_REGION clusters.

FORM and KEY_VALUE_REGION as "Wrapper" Types#

The layout model can predict two container labels for form-like regions: DocItemLabel.FORM and DocItemLabel.KEY_VALUE_REGION. The LayoutPostprocessor treats these — along with TABLE and DOCUMENT_INDEX — as wrapper types 1.

During _process_special_clusters(), any regular cluster whose bounding box is ≥80% contained within a wrapper cluster is captured as a child of that wrapper and removed from the top-level cluster list 2. For FORM and KEY_VALUE_REGION (but not TABLE or PICTURE), the wrapper's bounding box is then re-fit to the tight union of its children's boxes 3.

The confidence threshold for both labels is 0.45 — slightly lower than the 0.5 threshold used for TABLE, TEXT, and most others 4.

Cross-type overlap resolution#

_handle_cross_type_overlaps() implements an important guard: if a KEY_VALUE_REGION (or other wrapper) overlaps a TABLE cluster by >90% and its confidence advantage is <0.1, the wrapper is silently removed in favor of the TABLE 5. This prevents duplicate coverage but means a region predicted as both a table and a key-value zone will always be surfaced as a TABLE — a common source of unexpected TABLE output on form pages.

Misclassification consequences#

When a form page is classified as FORM (instead of a collection of text/table clusters), the layout postprocessor bundles all child content under the container, and the reading-order model processes it as a ContainerElement rather than individual readable items. The result is fragmented, non-semantic markdown output — spatial label→value bindings are destroyed silently, with no pipeline-level degradation signal 6.

The same silent-corruption pattern applies when a form page is classified as a single TABLE cluster: OCR'd text items are written to DoclingDocument.texts[] with valid prov.bbox but are never attached to body.children, making them invisible to the markdown serializer 7.

Reading-Order Processing of Container Elements#

The ReadingOrderModel.__call__() runs four sub-steps: predict_reading_order, predict_to_captions, predict_to_footnotes, and predict_merges 8.

In _readingorder_elements_to_docling_doc(), the dispatch is type-based 9:

• TextElement → add_text, add_heading, add_list_item, or add_code
• Table → add_table (with a 1×1 rich-cell fallback if the table has children but no predicted structure)
• FigureElement → add_picture, then _add_child_elements for captions
• ContainerElement (FORM / KEY_VALUE_REGION) → add_group with GroupLabel.FORM_AREA or GroupLabel.KEY_VALUE_AREA, then _add_child_elements to populate children 10

_add_child_elements() iterates element.cluster.children and adds each child as add_list_item, add_heading, or add_text depending on its label 11. Children labeled PAGE_HEADER/PAGE_FOOTER receive ContentLayer.FURNITURE; all others receive ContentLayer.BODY 12.

Key implication: FORM and KEY_VALUE_REGION regions do produce body-reachable items — but via the group's children rather than as top-level body elements. Tools traversing only body.children directly may miss them; the full document tree must be walked.

Reading-Order Corruption in Mixed-Content Documents#

Reading-order errors in documents mixing handwritten + machine-printed text, or documents with rotation skew, are classified as silent semantic corruption: every word has a valid prov.bbox and high OCR confidence, but the word sequence is wrong 13. These failures are hard to detect because:

• All content is present in texts[]
• No confidence scores are degraded
• A correctness check on individual tokens passes; only the ordering is wrong

The ReadingOrderPredictor (from docling-ibm-models) sorts elements by spatial position. When handwritten and machine-printed segments are processed by different sub-models and merged, or when rotational skew perturbs y-coordinates, the merge step may reorder segments that were continuation parts of the same sentence. There is no per-line reading-order confidence emitted by the current pipeline to surface this 13.

Debug Visualization#

The layout debug visualizer splits clusters into two panels specifically to expose form/KV classification:

• Left panel: all clusters except FORM, KEY_VALUE_REGION, and PICTURE
• Right panel: only those three types

This side-by-side output (saved as PNG at the configured debug_output_path) is the primary tool for inspecting misclassification of form-like regions. See draw_clusters_and_cells_side_by_side() 14.

Workarounds#

The VLM pipeline bypasses the classical layout/reading-order stack entirely and is the officially recommended path for documents with heavy form content 6.

Key Source References#