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.
The file to send
Open result.document for one text-based PDF. schemaVersion is docir.v1. The first block id is b000001. pages[0].blockIds is the reading order.
Block types are heading, paragraph, list, table, formula, code, image, and unknown. pageIndex is 0-based. metadata.route for this PDF is container. A measured PDF box uses unit pt. A block with no measured box omits bbox. result.manifest.parserVersion is cloudflare-docparse.0.2.0, the worker version. The document parserVersion on this container path is cloudflare-docparse-container.0.2.0. Confirm pages[0].blockIds[0] is b000001 before a chunker assumes a different id scheme.
- result.markdown is the projection. result.document is the record.
- result.manifest.decision.route should match metadata.route.
- On the container path the document parserVersion is cloudflare-docparse-container.0.2.0.
export DOCPARSE_URL="https://docparse.genedai.me"
export DOCPARSE_API_KEY="your_key"
curl -fsS -X POST \
"$DOCPARSE_URL/v1/parse?wait=true" \
-H "Authorization: Bearer $DOCPARSE_API_KEY" \
-F "file=@document.pdf" \
-F "mode=both" \
-o result.json
jq -r '.result.markdown' result.json
jq '.result.document.schemaVersion, .result.document.pages[0].blockIds' result.json
jq '.result.manifest.decision.route, .result.manifest.parserVersion' result.json
Frequently asked questions
Questions this guide answers
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.