`dump_tags`

Inspect the PDF structure tree and reading order

Usage

pdftl <input> dump_tags [reading_order|tree|issues] [json] [annotate] [streams=false] [<page_spec>...] [output <output>]

Details

The dump_tags operation inspects the PDF structure tree (the logical document model used by screen readers and accessibility validators) and reports it in one of three modes.

Modes

reading_order (default)

Walk the structure tree in logical reading order. For each leaf node that carries a Marked Content ID (MCID), show the corresponding marked-content block from the normalized page content stream, along with its 1-based line numbers within that stream. This is the primary tool for verifying that auto-tagging (e.g. from the tag operation) has produced the right structure and that the reading order matches visual intent.

Output format:

[H1] page=1  stream_lines=11-15
  /H1 << /MCID 2 >> BDC
  0 -40 Td
  /F1 18 Tf
  (Section One) Tj
  EMC

Container nodes (with no direct MCID) are shown as headers with their depth, page number, custom role (if mapped or unmapped), and child count.

Standard tags with no role mapping are displayed in their standard format:

[Document]  (4 children)
  [P] page=1  stream_lines=3-6
    ...

For custom tags mapped to standard types or unmapped tags, they are annotated with their role attributes (e.g. role=text-unit or role=Speaker):

[P] page=3 role=text-unit (2 children)
  [Span] page=3 role=Speaker

tree

Dump the raw structure tree as YAML (default) or JSON. Each node contains: tag, role (if a custom tag is present), page, mcid, alt, actual_text, title, lang, and children.

If a custom tag maps to a standard tag via /RoleMap, the node’s tag contains the mapped standard tag and its role holds the original custom name. If a custom tag is unmapped, tag defaults to "unknown" and role holds the custom name.

This is the foundation for tooling that needs to read or transform the structure tree programmatically. Output is compatible with update_bookmarks conventions for the title field.

issues

Walk the tree and report structural accessibility problems:

Figures without /Alt text (checks standard and mapped Figures)
Empty heading elements (no text in leaf MCIDs)
Heading level skips (H1 → H3 with no H2, checked across standard and mapped headings)
MCIDs referenced in the tree but not found in any page stream
Orphaned marked content (in stream but not referenced by any tree node)
Missing /MarkInfo or /StructTreeRoot on the document root
/Lang attribute missing from root or individual elements

Page specification

Standard page specs restrict which pages are included in the output (e.g. 1, 2-4, 1 3-5). Default is all pages. This applies to the reading_order and issues modes; tree always dumps the full tree but annotates which pages are within scope.

Options

json — use JSON instead of YAML for tree mode output
annotate — in reading_order mode, append % operator comments to each stream line (same as dump_streams annotate); useful for understanding what each operator does
streams=false — in reading_order mode, suppress the stream content and show only the structural metadata (tag, page, line range)

Relationship to other operations

Operation	Purpose
`dump_streams`	Raw/normalized stream content; no structure
`dump_tags`	Structure tree + stream correlation
`dump_bookmarks`	Outline (visible TOC); separate from tags
`tag`	Auto-tag a PDF using opendataloader-pdf

Notes

The stream lines shown in reading_order mode are from the normalized stream (one operator per line), exactly as dump_streams and replace see them. Line numbers are per-page and reset to 1 at each new page.

If a page has multiple content streams (a PDF array /Contents), they are concatenated before normalization, matching replace behavior.

Form XObjects that carry MCIDs are fully correlated. When stream decompression is enabled, the matching operator lines inside the Form XObject stream are parsed, located, and displayed inline in their logical reading order sequence.

Examples

Reading-order view: structure + stream lines for all pages

pdftl in.pdf dump_tags

Reading-order view for pages 1-3, saved to file

pdftl in.pdf dump_tags reading_order 1-3 output tags.txt

Reading-order view with PDF operator annotations on each stream line

pdftl in.pdf dump_tags reading_order annotate

Reading-order view without stream content (structure metadata only)

pdftl in.pdf dump_tags reading_order streams=false

Dump structure tree as YAML

pdftl in.pdf dump_tags tree output tags.yaml

Dump structure tree as JSON

pdftl in.pdf dump_tags tree json output tags.json

Report structural accessibility problems

pdftl in.pdf dump_tags issues

Tags: info, accessibility, structure, tags, tagging

Source: pdftl.operations.dump_tags

Read online: https://pdftl.readthedocs.io/en/latest/operations/dump_tags.html

Type: Operation

dump_tags