Why not pass through native parser output
Every parser has its own names, nesting, coordinate systems, confidence fields, and failure conventions. Passing native payloads directly forces chunkers, indexers, and interfaces to support every engine. Changing a route can become a breaking application change.
Normalize the stable concepts the product needs and retain route-specific evidence in metadata. A versioned schema makes additions and migrations deliberate.
Core entities
The source records identity and media metadata. Pages define document order and reference ordered block IDs. Blocks carry a stable ID, type, page index, text or Markdown, and optional normalized bounding box. Assets represent extracted visual resources. Metadata records creation time, parser version, route, and warnings.
Separate order from storage order. A block array can be indexed for lookup while each page’s block list declares reading sequence.
- Source: name, type, size, and content identity.
- Page: index, dimensions when available, and ordered blocks.
- Block: type, content, page, geometry, and relationships.
- Metadata: schema, parser, route, warnings, and timestamps.
Design for partial evidence
Not every route can provide trustworthy geometry or confidence. Optional fields should be absent or accompanied by clear warnings rather than filled with invented defaults. Consumers must branch on evidence availability, not infer it from a successful status alone.
Unknown block types should be forward-compatible where possible. Required semantic changes need a new schema version.
Keep projections reproducible
Markdown, chunks, search records, and extracted fields are projections of the normalized document. Record the code or schema version that produced each projection. This permits selective regeneration without reparsing when the underlying DocIR is retained and authorized.
Validate the document before publishing success, and preserve the job and manifest link so every projection can be traced to source and processing policy.
Frequently asked questions
Questions teams ask before building
What does IR mean in DocIR?
IR means intermediate representation: a normalized document model between format-specific parsing and downstream product projections.
Should coordinates use pixels?
Normalized coordinates are portable across render sizes, while original dimensions can be retained for exact mapping. Be explicit about the coordinate system.
How should schema evolution work?
Add compatible optional fields within a version when safe; create a new schema version for required or semantic changes and provide explicit migration logic.