A RAG pipeline cannot retrieve a relationship that ingestion has already destroyed. Before changing embeddings, test whether each important PDF value still belongs to the correct row, header, unit, condition and document revision. Keep structured extraction as the evidence record; derive retrieval text from it only after an acceptance gate. If structure or provenance is unresolved, quarantine the affected evidence instead of inviting the language model to reconstruct it.
This is a parser-boundary decision, not another chunk-size comparison. A search result can contain the right part number and every number from a table while supporting the wrong answer. Fluent generation and a high similarity score do not prove that “12,5” remained nominal torque rather than maximum torque.
The contract is a relationship, not a bag of words
For a technical table, define an evidence unit as document identity and revision, table identity, row key, hierarchical column header, raw value, unit and applicable footnote. Add page references and available source coordinates separately. Preserve merged-cell spans and a distinction between empty cells, missing extraction and explicit “not applicable”. None should silently become zero or inherit a neighbouring value.
The DoclingDocument representation supports tables, hierarchy, provenance and layout information where available. Its body tree encodes reading order. These are useful building blocks, not an assurance that every table was recognised correctly. A table-level bounding box is not automatically a verified bounding box for each value. Mark the granularity you actually have.
Use a stable document hash alongside the business revision. The revision tells readers which manual applies; the hash identifies the exact bytes processed. Store parser configuration, package and model revisions, OCR languages and extraction time in an ingestion manifest. A changed parser or model creates a new candidate extraction, not permission to overwrite the approved evidence silently.
An executed fixture with a deliberately narrow scope
For this article, a two-page born-digital PDF was generated with ReportLab 5.0.1 and read with PyMuPDF 1.28.2. It contains a merged “Torque limits” header over “Nominal” and “Maximum”, a separate unit column, repeated continuation-page headings and a footnote. All identifiers and values are synthetic: they are not maintenance instructions.
The first page contains AX-104, nominal 12,5, maximum 18,0, unit N.m and the condition “Dry assembly only.” The second contains BX-208, nominal 8,0 and maximum 10,0 with the same unit and condition. A fixture-specific geometry adapter extracts words from known cell rectangles. Reviewed header, continuation and footnote mappings are supplied explicitly; the adapter does not infer them. That limitation is intentional: this test exercises the acceptance contract, not general-purpose table recognition.
Four expected numeric tuples passed. Six separate mutations—wrong unit, removed decimal separator, wrong header, missing footnote, wrong revision and missing bounding box—were each rejected. These are deterministic validator checks, not six observed parser failures or a measured accuracy rate. Docling conversion, OCR, model inference and tokenizer overflow were not executed in this fixture. Those require additional runs on your document families.
The actual flattened first-page extraction still contains all the words, but no explicit cell associations: “Torque limits Part Nominal Maximum Unit Note AX-104 12,5 18,0 N.m * * Dry assembly only.” Flattening did not lose a digit in this example; it discarded the explicit relationships that a consumer would otherwise have to infer.
| Representation | Value and context | Acceptance implication |
|---|---|---|
| Source table, page 1 | AX-104; Nominal under Torque limits; 12,5; N.m; dry assembly only | Reviewed expected relationship |
| Flattened text | Headers followed by AX-104 12,5 18,0 N.m | Words present; relationships implicit |
| Header-aware evidence | AX-104; Torque limits / Nominal = 12,5 N.m; dry assembly only; revision B; page 1 | Relationship explicit and traceable |
| Injected decimal mutation | Same tuple, but raw value 125 | Reject: original literal changed |
| Injected header mutation | Same value assigned to Torque limits / Maximum | Reject: value moved to a different meaning |
The source PDF, page renders, exact extracted tuples, mutation results and runnable script are retained with this article’s publication evidence. The PDF SHA-256 is 6fdccb50dee86538395cbe129e8a1e601be9fa379ba9faeb4225909ae4c2f79d. This fixture proves a small contract can detect deliberately introduced defects; it does not establish production extraction quality.
Keep structured evidence before serialising retrieval text
The Docling project documents PDF layout, table structure, OCR, local execution and lossless JSON export. Use the structured document export as the upstream record rather than making Markdown the only surviving representation. Keep the original PDF under the same access policy. Local processing does not remove document-handling, retention or model-download approval requirements.
Implement an adapter from the pinned extraction schema to your own evidence schema. Walk table cells with their row and column spans, resolve the complete header path, and join row identifiers, unit cells and footnote markers. Validate these joins against reviewed examples. When the parser supplies no usable cell coordinates, retain table/page provenance and mark cell-level evidence unavailable; apply the use case’s review policy instead of inventing coordinates.
A useful retrieval string from the fixture is: “Document fixture-A, revision B. Table T1. Part AX-104. Torque limits / Nominal: 12,5 N.m. Condition: dry assembly only.” Its sidecar holds the document hash, page 1, table T1, row 0, column 1 and the extracted value box. Those row/column indexes are adapter coordinates, not immutable source identities across parser upgrades.
The measured PyMuPDF word box for 12,5 was approximately (161.00, 157.10, 184.35, 173.59) in page coordinates with a top-left origin. Record origin, page dimensions, units and rotation when mapping any parser’s boxes to a viewer; do not assume another library uses the same convention. For rotated or scanned pages, test the actual overlay against the page image.
Treat retrieval serialization as a rebuildable view over accepted evidence. The citation resolver should locate the original page and relevant table or cell, not merely display a document title. Permission checks must apply to the evidence store, derived chunks and source-view endpoint alike. A technically correct cell from an unauthorised manual is still an unacceptable answer.
Make continuation and footnotes explicit
Repeated page headings are not additional data rows. Conversely, identical headings on adjacent pages do not prove the same table continues. Combine table identifiers, captions, compatible columns and reviewed continuation rules. Keep each contributing page’s provenance. If a row spans pages, record multiple source spans; never manufacture one bounding box across two pages.
Merged headers need paths, not one flattened label. “Nominal” under torque and “Nominal” under pressure are different fields. Preserve the group header and distinguish a genuinely merged unit cell from a blank unit cell. Footnotes can restrict a row, a column or the entire table. A star without its resolved condition is incomplete evidence, even when the numeric tuple looks plausible.
For decimal commas, retain the original literal and a separately normalised value with a declared locale policy. Do not globally remove punctuation: 12,5 becoming 125 changes the quantity. OCR confusions, minus signs, superscripts and unit prefixes deserve reviewed fixtures. A confidence score can prioritise review but cannot replace a check against the actual source.
Put an acceptance decision before the vector index
The following policy is a proposed engineering gate, not a Docling standard. Set its strictness with the document owner and the consequences of an incorrect answer. Quarantine the smallest independently usable evidence scope; a broken shared header may invalidate a whole table rather than one cell.
| Finding | Decision | Evidence required before release |
|---|---|---|
| Value, header, unit and condition match reviewed fixture | Accept for downstream evaluation | Source identity plus resolvable provenance |
| Ambiguous merged header or page continuation | Review; exclude affected tuples | Approved mapping with all contributing pages |
| Wrong decimal, sign, unit or row association | Block affected evidence | Corrected extraction and regression case |
| Footnote marker has no resolved condition | Review or block | Source-backed condition and its scope |
| Cell coordinates unavailable | Apply declared provenance policy | Page/table reference and explicit granularity limit |
| Row exceeds downstream token budget | Reserialise or quarantine | Required header, value and condition survive actual tokenisation |
Run exact tuple checks before retrieval and answer scoring. Compare expected and extracted tuple sets, including missing and unexpected records; an equality test on only the first matched row can hide omissions. Use raw-value equality for transcription and a separate reviewed comparison for numeric normalization. For safety-relevant technical values, do not allow a good average to compensate for one confirmed unit or applicability error.
A minimal validator checks that every expected key exists, the expected and actual record counts agree, and each tuple preserves part, header, raw value, unit, condition, page and revision. It then checks source-hash consistency and the required provenance granularity. The fixture’s six mutations verify these rejection paths. Production coverage must additionally test duplicate rows, merged cells, rotated pages, scans and revisions that legitimately change values.
Headers also consume the downstream token budget
The Docling chunking documentation describes HybridChunker’s repeated table headers. It also documents omit_header_on_overflow: when enabled, a header may be omitted for a row that fits alone but not with its header. That is a semantic trade-off, not merely an efficiency setting. Do not enable it without proving that your evidence remains interpretable.
Count with the deployed tokenizer after headers, identifiers and conditions have been added. If a row is too wide, split it into evidence units that each retain the relevant header path, row key, unit and restriction. Keep sibling links for questions requiring multiple cells. If no safe representation fits, route the query or document for review instead of truncating silently. Neither more overlap nor a larger embedding model repairs an already incorrect unit assignment.
Only after this boundary passes should you compare chunking strategies, diagnose exact-identifier retrieval, and run the broader RAG evaluation CI gate. Keep extraction correctness, evidence survival, retrieval recall and answer support as separate results.
Release checklist and operating trade-offs
Before release, verify original bytes and revision; freeze parser/model configuration; review representative source pages; assert cell/header/unit/condition tuples; inspect provenance overlays; check continuation rules; measure actual token survival; and rerun permission-aware retrieval and answer evaluation. Retain the prior approved extraction and index manifest for rollback.
Structured evidence costs storage, adapter maintenance and reviewer time. Repeating headers and conditions costs tokens. Conservative quarantine reduces immediate corpus coverage and needs an owner and resolution queue. A small born-digital fixture cannot represent poor scans or every supplier’s layout. Track acceptance, review and rejection counts by document family, plus backlog age and parser runtime; do not market these operational counts as answer accuracy.
If your team is deciding whether to replace its embedding model or its PDF parser, start with one manual family and a reviewed set of high-consequence table questions. I can help define the cell-evidence contract, build acceptance fixtures and trace the first boundary where meaning is lost. The useful deliverable is a reproducible ingestion decision—not a fluent demonstration over an unverified table.
