Skip to content
NextPDF

PDF/UA-2 conformance: the tagged structure NextPDF emits for ISO 14289-2

At a glance

Section titled “At a glance”

Boundary statement. NextPDF emits the tagged structure that supports accessible authoring; it does not assert PDF/UA-2 conformance — a checker determines that.

PDF/UA-2 is ISO 14289-2:2024, the accessibility profile layered on tagged Portable Document Format (PDF) 2.0. NextPDF Core emits the structure tree, marked content, catalog and structure language, and the pdfuaid marker through Document::enableTaggedPdf(). The library creates the accessible structure; a PDF/UA checker, such as verapdf --flavour ua2, decides conformance. ISO 14289-2 §8.1 defines conformity as file-format requirements that a document must satisfy, as assessed by a checker, not as a claim the producer declares.

Install

Section titled “Install”
Terminal window
composer require nextpdf/core:^3

PDF/UA-2 tagging is a Core capability (security.tagged_pdf). You do not need a Premium package to emit the tagged structure itself.

Conceptual overview

Section titled “Conceptual overview”

Document::enableTaggedPdf(string $lang = 'en', ?ConformancePolicy $policy = null) sets ConformanceMode::PdfUa2 and wires TaggedContentEmitter. The mode is the single source of truth for whether the document is spec-tagged; the writer then meets the structural obligations that ISO 14289-2 imposes:

  • Real content is tagged — §8.2.2: every piece of real, non-artifact content is included in the logical structure, and artifacts are marked as artifacts. This is built on the ISO 32000-2 §14.7 tagged-PDF structure (StructTreeRoot, structure elements, MCIDs).
  • Natural language is declared — §8.4.4: the document and language shifts carry a Lang. With ConformancePolicy::strictUa2(), a malformed BCP 47 tag is rejected at the API boundary, fail-fast, rather than dropped silently at write time.
  • Figures carry alternatives — §8.5.1: every Figure structure element has an alternative description.
  • Tables associate headers and data — §8.2.5.26: table header/data cell association is expressed structurally.

NextPDF emits these structures. It does not run the §8.1 conformity assessment; that is the checker’s role, and the standard reserves it there.

API surface

Section titled “API surface”
MethodEffect
enableTaggedPdf(string $lang = 'en', ?ConformancePolicy $policy = null): staticSets ConformanceMode::PdfUa2, wires TaggedContentEmitter, validates $lang per policy. Throws InvalidConfigException when the policy mandates Lang validation and $lang is invalid.
beginTag()/endTag()Manual structure for non-HTML content; container types become grouping elements, leaf types get MCIDs.
ConformanceMode::requiresPdfUa2PageTabs(): boolTrue for PdfUa2 — drives /Tabs /S page enforcement.

Code sample — Quick start

Section titled “Code sample — Quick start”
<?php


declare(strict_types=1);


require_once __DIR__ . '/vendor/autoload.php';


use NextPDF\Core\Document;
use NextPDF\Conformance\ConformancePolicy;


$out = getenv('NEXTPDF_COOKBOOK_OUTPUT') ?: __DIR__ . '/accessible.pdf';


$doc = Document::createStandalone();
$doc->enableTaggedPdf('en', ConformancePolicy::strictUa2()); // fail-fast Lang
$doc->setTitle('Accessible report 2026');
$doc->writeHtml('<h1>Quarterly report</h1><p>Body text.</p>'
    . '<img src="chart.png" alt="Revenue rose 12% quarter on quarter">');
$doc->save($out);


echo "Wrote {$out} — validate: verapdf --flavour ua2 {$out}\n";

Code sample — Production

Section titled “Code sample — Production”

The production gate runs verapdf --flavour ua2 out.pdf and fails the build when the checker reports violations. The integration test tests/Integration/Accessibility/VeraPdfUa2GoldenTest.php asserts the HTML→tagged-PDF golden fixture passes veraPDF UA-2 (skipped when veraPDF is absent). The checker verdict is the gate, and the emitter output is its input.

Edge cases & gotchas

Section titled “Edge cases & gotchas”
  • Enable first. enableTaggedPdf() after writeHtml() does not retroactively tag already-written content.
  • Strict language. Pass ConformancePolicy::strictUa2() to reject a malformed BCP 47 tag at the API boundary instead of failing only at post-hoc veraPDF validation.
  • Idempotent re-enable. Calling it twice updates the language without rebuilding a populated structure tree.
  • Empty tagged document. An empty tagged document does not advertise PDF/UA-2 (EmptyTaggedPdfDoesNotAdvertisePdfUa2Test): the marker is not emitted for a document with no real content, so the file does not over-claim.

Performance

Section titled “Performance”

Structure-tree emission is proportional to the element count. The budget is wall ≤ 1500 ms and peak ≤ 64 MB for a typical report.

Security notes

Section titled “Security notes”

Accessibility tagging is structural, not a security control. By design, it exposes the document’s logical structure to assistive technology. The tag tree has no confidentiality dimension.

PDF/UA-2 mapping

Section titled “PDF/UA-2 mapping”
PDF/UA-2 obligationISO 14289-2 clauseNextPDF emission
Real content tagged in logical structure§8.2.2TaggedContentEmitter + StructureTree
Document/structure language declared§8.4.4catalog /Lang, validated via Bcp47Validator
Figure alternative description§8.5.1alt → /Alt on the Figure element
Table header/data association§8.2.5.26TR/TH/TD structure from HTML tables

Tag → ISO 32000-2 §14.9 cross-ref

Section titled “Tag → ISO 32000-2 §14.9 cross-ref”

PDF/UA-2 layers on the ISO 32000-2 tagged-PDF model. The structure elements NextPDF emits resolve against ISO 32000-2 §14.7 logical structure (StructTreeRoot, structure elements, MCIDs) — chunk — and the standard structure namespace defined for PDF 2.0. The role map ties HTML elements (h1, p, table) to standard structure types so a UA-2 checker can recognize them.

WCAG 2.2 mapping

Section titled “WCAG 2.2 mapping”

The tagged structure is the technical substrate for Web Content Accessibility Guidelines (WCAG) 2.2 success criteria — 1.1.1 (non-text alternatives, via §8.5.1 Figure /Alt), 1.3.1 (info and relationships, via the structure tree), and 1.3.2 (meaningful sequence, via reading order). Emitting the structure is necessary but not sufficient for WCAG conformance; an accessibility audit, not the library, makes that determination.

FIPS-mode behavior

Section titled “FIPS-mode behavior”

PDF/UA-2 emission performs no cryptography. Federal Information Processing Standards (FIPS) mode has no effect on the tagged-structure path.

Conformance

Section titled “Conformance”
ClaimSpecClausereference_id
The PDF/UA version is identified by the pdfuaid schema namespace (Table 1).ISO 14289-2§5
Conformity with PDF/UA-2 imposes file-format requirements a document must satisfy (a checker assesses conformity; the producer does not declare it).ISO 14289-2§8.1
Real content shall be tagged in the logical structure.ISO 14289-2§8.2.2
The document’s natural language shall be declared.ISO 14289-2§8.4.4
Figure elements require an alternative description.ISO 14289-2§8.5.1
Table structure must associate header and data cells.ISO 14289-2§8.2.5.26
The accessible structure is built on the ISO 32000-2 tagged-PDF logical structure.ISO 32000-2§14.7.2

Citations are clause-id and reference_id pointers into the verification corpus. No standards text is reproduced.

See also

Section titled “See also”