PDF/UA-2 (ISO 14289-2) specification mapping

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. It is not a conformance claim. 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. NextPDF does not run a conformance checker. 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 and explicit non-coverage

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.
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.
Conformance attestation or certification	Out of scope	Not provided by the library.

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. It does not assert that a given document conforms to PDF/UA-2. Validate with a PDF/UA checker, such as veraPDF; the library does not assert conformance on your behalf. The bundled veraPDF UA-2 golden test is skip-gated when the veraPDF binary is absent, so no conformance pass is claimed here. Cited clauses are paraphrased, never quoted; chunk hashes are recorded in docs/public/modules/core/_normative-evidence-a11y.md.

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, not of calling the API.