Tagged PDF tutorial over Connect

Tagged PDF tutorial over Connect

Conformance boundary (read this first). NextPDF emits the tagged structure, alternate text, and metadata expected by PDF/UA-2. That makes the output intended to conform to PDF/UA-2 (ISO 14289-2). It does not make the document “conformant” by itself. An independent checker, veraPDF in strict PDF/UA-2 mode, decides conformance. Read every “PASS”, “conformant”, or “compliant” statement below as “the document is intended to conform; veraPDF determines the outcome”.

At a glance

In this tutorial, you create a tagged Portable Document Format (PDF) file over the Connect transports. You enable the tagged mode, set a title, add semantic HTML, and verify the result with the standards-check tool and veraPDF. The tagged-mode and content tools used here are core. The standards-check verification tool is Pro/Enterprise-tier. It registers through class_exists() only when nextpdf/premium is installed alongside the server.

Install

composer require nextpdf/server

Conceptual overview

Logical structure plus a natural-language specification makes content navigable in reading order (ISO 32000-2 §14.7). The /Alt entry holds an alternate description for non-text content (ISO 32000-2 §14.8). Content must be reflected in the structure tree, and a checker determines conformance (PDF/UA-2 §8.2.4). When you write well-structured semantic HTML, the pipeline produces the correct structure for you. This tutorial relies on that flow instead of asking you to build structure by hand.

API surface

Tool names are verified against the running registry through tools/list. The catalog of record is /connect/tool-catalog/. This tutorial does not repeat a tool count.

Code sample — Quick start

Here is the shortest path. Enable the tagged mode with a language, set a title, and then add content.

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "enable_tagged_pdf",
    "arguments": { "document_id": "<id>", "language": "en" }
  }
}

Enable the tagged mode before your first content call. The writer freezes the mode when it emits the first page. If you switch it on later, NextPDF does not go back and tag content that is already emitted. A document title is mandatory for PDF/UA-2, and the tagged mode sets the viewer-title preference.

Code sample — Production

Add semantic HTML. The pipeline maps headings, lists, tables with <th scope>, links, and figures with alt to the correct structure types:

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "add_html",
    "arguments": {
      "document_id": "<id>",
      "html": "<h1>Annual Report</h1><h2>Summary</h2><p>Revenue grew.</p><table><caption>Revenue</caption><thead><tr><th scope=\"col\">Region</th><th scope=\"col\">Q1</th></tr></thead><tbody><tr><th scope=\"row\">EMEA</th><td>120</td></tr></tbody></table><figure><img src=\"chart.png\" alt=\"Revenue by region bar chart\" /><figcaption>Figure 1.</figcaption></figure>"
    }
  }
}

RevenueRegionQ1EMEA120

Figure 1.

" } }}">

Then run the standards check against PDF/UA-2, and run veraPDF --flavour ua2 on the output. The check result and the veraPDF verdict are assessments. They tell you whether the document is intended to conform. veraPDF, not NextPDF, decides conformance.

Edge cases & gotchas

• Tagged mode enabled after content. Any content you add before you switch the mode on is untagged. The check reports a tagged-content failure. Enable the mode immediately after you create the document.
• Informational image without alt. The check reports a figure-alternate-text failure. Supply alt text, or mark a decorative image as an artifact (/cookbook/connect/page-artifacts/).
• Heading level skipped. Skipping a level, for example H1 then H3, is a heading-order failure. Descend by at most one level at a time.
• <th> without scope. A header cell with no associated data cells is a table-structure failure. Give every <th> either scope="col" or scope="row".
• Missing title. A document with no title is a metadata failure. Set the title after you enable the tagged mode.

Performance

The front-matter budget is a documentation cap. Tagging is part of the normal layout pass.

Security notes

Nothing applies here beyond the general Connect transport guidance: do not log document content or the HTML body at a log level that ships externally.

Conformance

PDF/UA-2 mapping

Semantic HTML maps to the PDF/UA-2 standard structure types (H1–H6, P, L/LI/Lbl/LBody, Table/TR/TH/TD, Link, Figure/Caption, Aside). The mapping is automatic. Your part of the contract is to write semantic HTML.

Tag → ISO 32000-2 §14.9 cross-ref

Claim	Clause	reference_id
Logical structure + language → navigable in reading order	ISO 32000-2 §14.7
Alternate description held in /Alt	ISO 32000-2 §14.8
Content in the structure tree; a checker determines conformance	PDF/UA-2 §8.2.4

WCAG 2.2 mapping

The structure supports WCAG 2.2 SC 1.1.1, 1.3.1, 2.4.1, and 2.4.6 at the content level. As the content author, you remain responsible for the WCAG-level authoring decisions.

NextPDF produces output intended to conform to PDF/UA-2. It does not assert conformance. veraPDF, or another checker, makes the conformance determination. A passing check or veraPDF run is evidence that the output is intended to conform, not a certification by NextPDF.

Commercial context

The tagged-mode and content tools are core. The standards-check verification tool is Pro/Enterprise-tier, and it registers only when nextpdf/premium is installed alongside the server.

Connect specifics

Transport availability (MCP / REST / gRPC)

You invoke every tool in this tutorial the same way over MCP tools/call, the REST tool endpoint, and the gRPC service. They all run through the shared tool executor.

HITL risk tier

Enabling the tagged mode and using the content tools are caution-level. The standards check is read-only. The file-writing output path is approval-required, though the base64 mode is not. See /connect/hitl-risk-tiers/.

Confirmation gate JSON envelope

When the file-writing output path is gated, the gate returns a challenge envelope and a single-use token. The token is bound to the tool name, a nonce, and a 300-second time-to-live (TTL). To proceed, re-invoke the tool with arguments._confirmation_token. See /connect/hitl-risk-tiers/.

See also

• /cookbook/connect/conformance-mode/ — the mode discriminator behind the tagged mode.
• /cookbook/connect/aria-tagged-pdf/ — landmark role mapping.
• /cookbook/connect/page-artifacts/ — exclude decorative content from the structure tree.
• /connect/tool-catalog/ — per-tier tool set computation.