Map ARIA landmark roles to tagged PDF over Connect

Map ARIA landmark roles to tagged PDF over Connect

At a glance

Submit HTML that uses HTML5 sectioning elements and Accessible Rich Internet Applications (ARIA) landmark roles over Connect. The tagged-content pipeline maps them to PDF 2.0 standard structure types, so assistive technology can navigate by landmark instead of visual position. The accessibility check used here is Pro-tier: the tool is discovered through a class_exists() probe and registers only when nextpdf/premium is installed alongside the server. Document creation and HTML ingestion use core tools.

The accessibility tool reports findings against PDF/UA-2 (ISO 14289-2). A passing result is the tool’s own assessment. It is an accessibility check, not an independent conformance certification. veraPDF or another checker determines conformance.

Install

composer require nextpdf/server

Confirm that the Pro accessibility tool is present on the running deployment with a tools/list call (see /connect/tool-catalog/). If it is absent, nextpdf/premium is not installed on this deployment, so this recipe’s verification step cannot run.

Conceptual overview

Grouping structure elements organize a document’s logical structure into sections and similar containers (ISO 32000-2 §14.8). The HTML pipeline maps these elements:

• <aside> and role="complementary" → the PDF 2.0 Aside standard type
• <article> / role="article" → Art
• <nav> / role="navigation" → Sect

A non-standard structure type is acceptable only when it is role-mapped to a standard type (PDF/UA-2 §8.2.5). The pipeline emits the standard type directly, so you do not need a manual role map. Content must be reflected in the structure tree for assistive technology to reach it (PDF/UA-2 §8.2.4).

API surface

Verify tool names against the running registry with tools/list. The catalog of record is /connect/tool-catalog/. This recipe uses the core document-creation and HTML-ingestion tools, plus the Pro accessibility check. It does not restate a fixed tool count.

Code sample — Quick start

Create a tagged PDF 2.0 document, add HTML with landmark roles, and check it by sequencing MCP tools/call requests:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "create_pdf",
    "arguments": { "page_size": "A4", "title": "ARIA Landmark Demo", "language": "en" }
  }
}

Wire the tagged-content emitter before you add any HTML. Create the document with a language set, so the emitter is active from the first content call.

Code sample — Production

Add the landmark HTML and run the accessibility check. Treat a non-success status as a normal result to inspect, not as a transport error:

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "add_html",
    "arguments": {
      "document_id": "<id from create_pdf>",
      "html": "<main><h1>Annual Report</h1><aside><h2>Aside</h2><p>Note.</p></aside><div role=\"complementary\"><h2>Related</h2><p>Links.</p></div><nav role=\"navigation\"><p>Skip nav</p></nav></main>"
    }
  }
}

The check response reports the structure tree it observed and a PDF/UA-2 finding summary. Both <aside> and <div role="complementary"> collapse to the same Aside standard type.

Edge cases & gotchas

• Tagged emission not active before content. If the document was not created with a language / tagged mode, the first HTML add produces untagged content, and the check reports a tagged-content failure. Recreate the document with the language set.
• Conflicting role on a sectioning element (<aside role="navigation">) produces a warning. Remove the conflicting role or use a <div>.
• Tool absent. Without nextpdf/premium, the Pro accessibility tool is not registered, and the verification step fails with an unknown-tool error.

Performance

The frontmatter budget is a documentation cap. Landmark mapping is part of the normal layout pass. It does not add a separate measurable phase for typical documents.

Security notes

No additional guidance applies beyond the general Connect transport rule: do not log document content or the HTML body at an externally shipped log level.

Conformance

PDF/UA-2 mapping

HTML	PDF 2.0 standard type
<aside>, role="complementary"	Aside
<article>, role="article"	Art
<nav>, role="navigation"	Sect

Tag → ISO 32000-2 §14.9 cross-ref

Claim	Clause	reference_id
Grouping elements organise logical structure into sections	ISO 32000-2 §14.8
Non-standard types require role-mapping to a standard type	PDF/UA-2 §8.2.5
Content must be reachable through the structure tree	PDF/UA-2 §8.2.4

WCAG 2.2 mapping

Landmark navigation supports WCAG 2.2 SC 1.3.1 (Info and Relationships) and SC 2.4.1 (Bypass Blocks) at the content level. The PDF format carries the structure. The content author remains responsible for WCAG-level authoring decisions.

A passing accessibility-tool result is an accessibility check, not a conformance certification. An independent checker (for example, veraPDF) determines PDF/UA-2 conformance.

Commercial context

The accessibility check tool is Pro-tier and registers only when nextpdf/premium is installed alongside the server.

Connect specifics

Transport availability (MCP / REST / gRPC)

Invoke create_pdf, add_html, and the accessibility check the same way over MCP tools/call, the REST tool endpoint, and the gRPC service through the shared tool executor.

HITL risk tier

Document creation and HTML ingestion are caution-level (auto-execute, audit-logged). The accessibility check is read-only. None of these tools is approval_required by default. See /connect/hitl-risk-tiers/.

Confirmation gate JSON envelope

These tools do not trigger the gate unless an operator configuration override raises one of them to approval_required. When gated, the challenge envelope and single-use token contract follow /connect/hitl-risk-tiers/.

See also

• /cookbook/connect/figure-caption/ — nested Figure / Caption structure.
• /cookbook/connect/aria-noteref-pattern/ — footnote reference and body roles.
• /connect/tool-catalog/ — per-tier tool set computation.
• /connect/hitl-risk-tiers/ — the risk model and the gate.