ADR-001: Canonical JSON as Pipeline Interface

Status: Accepted

Date: 2026-06-30

Context

Different OCR engines produce different output formats. Docling outputs a document model with regions and reading order. Qwen Vision outputs text with bounding boxes. Each engine structures data differently.

Without a common format, every downstream stage (classification, metadata extraction, chunking, indexing) would need to handle every engine's output format. Adding a new OCR engine would require changes throughout the pipeline.

Decision

All OCR output is normalized to a single canonical JSON format. Downstream stages consume only canonical JSON. Engine-specific code is confined to adapters that convert engine output to canonical format.

Consequences

• Positive: Adding an OCR engine requires only a new adapter. Downstream stages are unaffected.
• Positive: The canonical format serves as documentation — it defines exactly what data flows through the pipeline.
• Positive: Canonical JSON files are the audit trail. Every processing decision is recorded in the document.
• Negative: Schema evolution requires updating all adapters. Mitigated by treating the canonical format as stable and versioned.
• Negative: Some engine-specific data may be lost in normalization. Mitigated by including a raw_engine_output reference for debugging.