MinerU Intermediate JSON Format

MinerU Intermediate JSON Format (`middle.json`)#

middle.json is the central intermediate artifact produced by every MinerU backend (pipeline, VLM, hybrid, office). It bridges raw model inference results (model.json) and the final deliverables (Markdown, content_list.json, content_list_v2.json). All subsequent extraction steps read from it, and it is the primary file to inspect when debugging layout or parsing failures.

File naming: {doc_stem}_middle.json, written to {output_dir}/{doc_stem}/{backend_method}/.

⚠️ The VLM backend output changed significantly in version 2.5 and is not backward-compatible with the pipeline backend.

Top-Level Structure#

The file is a single JSON object initialized by init_middle_json():

Field	Type	Description
`pdf_info`	`list[dict]`	Per-page parsing results (one entry per page)
`_backend`	`string`	Backend used: `pipeline`, `vlm`, `hybrid`, or `office`
`_version_name`	`string`	MinerU version string

Per-Page Structure (`pdf_info` entries)#

Each element of pdf_info represents one page :

Field	Description
`page_idx`	0-based page index
`page_size`	`[width, height]` in document units
`preproc_blocks`	Raw blocks after PDF preprocessing, before paragraph segmentation
`para_blocks`	Primary content — blocks after layout segmentation; this is the field all downstream steps consume
`images`	Image block list
`tables`	Table block list
`interline_equations`	Interline formula block list
`discarded_blocks`	Blocks excluded from final output (e.g., headers, footers, page numbers)

Debugging tip: Gaps in para_blocks y-coordinates indicate blocks dropped by the layout model. Compare with the text layer via mineru.utils.pdf_text_tool.get_page_chars() to isolate whether the layout model or OCR is the culprit.

Block Hierarchy#

Blocks are organized in a two-level tree (pipeline backend) :

Level 1 block (image | table | chart)
└── Level 2 blocks
    └── Lines
        └── Spans

Level 1 Blocks#

Represent compound visual elements. Fields: type (table, image, or chart), bbox ([x0, y0, x1, y1]), and blocks (list of Level 2 blocks).

Level 2 Blocks#

Fields: type (see Block Type Classification below), bbox, and lines.

Lines and Spans#

Line fields: bbox, spans
Span fields: bbox, type (image, table, chart, text, inline_equation, interline_equation), and either content (text/LaTeX) or image_path

The VLM backend adds an angle field (0, 90, 180, 270) on blocks and lines to handle rotated content.

Block Type Classification#

All block type string constants are defined in BlockType in mineru/utils/enum_class.py.

Core Types (all backends)#

Type	Description
`text`	Plain text paragraph
`title`	Section heading
`image`, `table`, `chart`	Level 1 container blocks
`image_body`, `table_body`, `chart_body`	Visual content body
`image_caption`, `table_caption`, `chart_caption`	Associated captions
`image_footnote`, `table_footnote`, `chart_footnote`	Associated footnotes
`interline_equation` / `equation`	Display-mode formula
`list`	List container
`index`	Index entry
`discarded`	Explicitly excluded block

VLM Backend Extensions (added in v2.5)#

Type	Description
`code`, `code_body`, `code_caption`, `code_footnote`	Code block with sub-parts
`algorithm`	Algorithm block (treated as `code` subtype)
`ref_text`	Reference / citation entry
`phonetic`	Phonetic annotation
`header`, `footer`, `page_number`	Page furniture (goes to `discarded_blocks`)
`aside_text`, `page_footnote`	Margin/footnote content

PP-DocLayout v2 Extensions#

Type	Description
`abstract`	Document abstract
`doc_title`	Document title (top-level)
`paragraph_title`	Sub-paragraph heading
`vertical_text`	Rotated/vertical text
`header_image`, `footer_image`	Images in header/footer zones
`formula_number`	Equation number label

`NotExtractType` — Skipped in Extraction#

The NotExtractType enum lists block types that are not extracted into the final text output: text (raw), title, header, footer, page_number, page_footnote, ref_text, *_caption, *_footnote, code_caption, and phonetic. These are handled separately or suppressed.

Pipeline Role and Key Code References#

model.json → middle.json → content_list.json / content_list_v2.json / Markdown

Concern	Location
Struct initialization	`init_middle_json()`
Page data appended	`append_page_model_infos_to_middle_json()`
File written to disk	`_process_output()` in `mineru/cli/common.py` (when `f_dump_middle_json=True`)
Client-side finalization (Markdown regen)	`regenerate_client_side_outputs()` in `mineru/cli/client_side_output.py`
API response reading	`build_result_dict()` in `mineru/cli/fast_api.py`
Block/content type enums	`mineru/utils/enum_class.py`
Official field reference	Output File Format docs

content_list.json is a flat, simplified view of middle.json in reading order with layout metadata stripped. content_list_v2.json (added in v3.0) uses a richer type + content schema and is the preferred format for secondary development.