PDF/UA-2 clause map

At a glance

This page maps NextPDF Core features to PDF/UA-2 (Portable Document Format/Universal Accessibility 2; ISO 14289-2) provisions. It states which provisions the library helps you satisfy and which provisions are explicitly out of scope. A conforming file depends on your content, the source markup, and validation with an external PDF/UA checker.

Install

composer require nextpdf/core

Conceptual overview

PDF/UA-2 (ISO 14289-2) defines requirements for accessible PDF files. These requirements build on the logical structure facilities of ISO 32000-2 §14.7 and the accessibility support entries of ISO 32000-2 §14.9. A conforming file identifies itself with the identification schema of ISO 14289-2 §5. It carries a structure tree whose root has a single Document element (ISO 14289-2 §8.2.5.2). It uses standard structure types so assistive technology can resolve every tag to a known role.

NextPDF supplies the authoring primitives for this model: structure-tree construction, standard role mapping, marked-content tagging from semantic HTML, and BCP-47 language attributes. NextPDF does not infer semantics that are absent from the source content. The primitives target the ISO 14289-2 §3.1 model in which assistive technology consumes the structure tree. Your input and an external validator determine whether a specific document meets every provision.

API surface

Provision area	NextPDF entry point
Tagged-PDF activation, mark-info, catalog language	Document::enableTaggedPdf(string $lang, ?ConformancePolicy)
Document-level natural language	Document::setLanguage(string $lang)
Structure tree and single Document root	StructureTree::createRoot(), StructureTree::addElement()
Standard structure type vocabulary	RoleMap::standard()
Per-element language, alternative and replacement text	StructureElement constructor attributes
BCP-47 strict validation	Bcp47Validator, ConformancePolicy::strictUa2()
Heuristic remediation (opt-in)	AccessibilityAutoFixerRegistry

Code sample — Quick start

<?php

declare(strict_types=1);

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->enableTaggedPdf(lang: 'en');
$doc->setTitle('PDF/UA-2 structure demonstration');
$doc->addPage();
$doc->writeHtml('<h1>Title</h1><p>Body.</p><ul><li>Item</li></ul>');
$doc->save(__DIR__ . '/output/ua2.pdf');

// Then validate with an external checker. NextPDF does not assert
// conformance on your behalf:
//   verapdf --flavour ua2 output/ua2.pdf

Code sample — Production

See the Accessibility module production example for the dependency-injected writer with strict BCP-47 validation, advisory logging, and error handling. The same wiring applies to a PDF/UA-2 authoring workflow. Add the post-generation external validation step. This step is mandatory for a conformance claim and is your responsibility.

Edge cases & gotchas

• A document that enables tagged PDF but attaches no structure descendants does not advertise the PDF/UA-2 identification block, by design (ISO 14289-2 §5). Validators reject an empty structure tree.
• Combining enablePdfA() and enableTaggedPdf() collapses the single-valued conformance discriminator to last-wins while keeping structural side effects additive. A CONFORMANCE_MODE_CLOBBERED warning makes this observable.
• ISO 14289-2 §7.2.2 permits a conforming document to additionally claim conformity with broader accessibility regulations. NextPDF emits only the PDF/UA-2 identification schema and does not emit other regulatory claim metadata.

Provision mapping

Provision area (ISO 14289-2 / ISO 32000-2)	NextPDF support	Notes
PDF/UA-2 identification schema (ISO 14289-2 §5)	Supports	Emitted only when the structure tree has descendants.
Single Document element under the structure tree root (ISO 14289-2 §8.2.5.2; ISO 32000-2 §14.7.2)	Supports	createRoot() enforces a single root Document.
Standard structure types and role map (ISO 32000-2 §14.7; Well-Tagged PDF §8.2.5.1)	Supports	RoleMap::standard() plus the PDF 2.0 namespace.
Marked-content sequences and parent tree (ISO 32000-2 §14.7.2)	Supports	Per-page identifiers, cross-page continuation.
Catalog and per-element natural language (ISO 32000-2 §14.9; ISO 14289-2 §8.4.4)	Supports	BCP-47; strict mode rejects malformed tags.
Alternative and replacement text carriers (ISO 32000-2 §14.9)	Supports the carrier; content is author-supplied	The library does not generate alternative text.
Logical reading order (ISO 32000-2 §14.7)	Supports source order; does not reorder	A corrected reading order is the author’s responsibility.
Table header association and scope	Out of scope beyond HTML markup	Not inferred; depends on source markup.
Tagged HTML <table> PDF/UA-2 conformance (ISO 32000-2 §14.8; ISO 32005:2023 Table 5)	Passes veraPDF ua2	Flat, colspan/rowspan, cross-page and nested tables emit Table/TR/TH/TD structure with /ColSpan and /RowSpan attributes; veraPDF --flavour ua2 reports zero failures.
Grouping elements <section>/<div>/<article>/<aside>/<blockquote> (ISO 32000-2 §14.8.4.2)	Passes veraPDF ua2	Emit grouping structure with no content item; loose inline content is wrapped in a synthesized P.
Table cell spanning /ColSpan /RowSpan (ISO 32000-2 Table 384, on TH/TD; ISO 14289-2 §8.2.5.26)	Supports	Spanning cells carry /ColSpan and /RowSpan so the table reads as regular. Header association (the Headers/Scope entries) is still author-supplied, per the row above.
Heading-level correctness and outline	Out of scope	The author must supply a correct heading hierarchy.
End-to-end PDF/UA-2 verification	Out of scope	No bundled checker; validate externally.

Performance

The structure-tree facilities add one linear serialisation pass over the element set. The HTML pipeline dominates the cost, not tag emission. The performance_budget cap applies to a typical multi-page semantic document.

Security notes

Language and accessibility-attribute values are escaped through PdfStringEscaper before they enter PDF object syntax. Strict-mode BCP-47 validation narrows the language-tag input surface at the API boundary. Treat author-supplied alternative text and titles as untrusted output.

Conformance

NextPDF emits structure consistent with the PDF/UA-2 structure-tree model defined in ISO 14289-2 and ISO 32000-2 §14.7. Validate with a PDF/UA checker, such as veraPDF. The bundled veraPDF UA-2 golden test runs when the veraPDF binary is present. Cited clauses are paraphrased, never quoted.

Known limitations

A PDF/UA-2 conformance claim requires author-supplied semantics (alternative text, correct heading hierarchy, table header association, intended reading order, decorative-content classification) and validation with an external checker. The library does not produce or verify any of these. The runtime emits a Degraded / ComplianceRisk advisory that directs you to validate externally for production sign-off. Conformance is a property of the final document and the authoring process.

See also

• Accessibility module reference
• Conformance profile checkers
• HTML rendering subsystem