Conformidad con PDF/UA-2: estructura etiquetada que NextPDF emite para ISO 14289-2

De un vistazo

Declaración de límites. NextPDF emite la estructura etiquetada que sustenta la creación accesible; no declara conformidad con PDF/UA-2: eso lo determina un verificador.

PDF/UA-2 es ISO 14289-2:2024, el perfil de accesibilidad superpuesto al PDF 2.0 etiquetado. NextPDF Core emite el árbol de estructura, el contenido marcado, el idioma del catálogo/estructura y el marcador pdfuaid mediante Document::enableTaggedPdf(). La biblioteca genera la estructura accesible; un verificador de PDF/UA (por ejemplo, verapdf --flavour ua2) decide la conformidad. El §8.1 de ISO 14289-2 plantea la conformidad como un conjunto de requisitos de formato de archivo que un documento debe satisfacer, evaluados por un verificador, no como algo que declare el productor.

Instalación

composer require nextpdf/core:^3

El etiquetado PDF/UA-2 forma parte de Core (security.tagged_pdf). No se necesita ningún paquete Premium para la estructura etiquetada en sí.

Panorama conceptual

Document::enableTaggedPdf(string $lang = 'en', ?ConformancePolicy $policy = null) establece ConformanceMode::PdfUa2 y conecta TaggedContentEmitter. El modo es la fuente única de verdad sobre si un documento está etiquetado según la especificación; a partir de ahí, el escritor satisface las obligaciones estructurales que impone ISO 14289-2:

• El contenido real se etiqueta — §8.2.2: todo fragmento de contenido real (no artefacto) se incluye en la estructura lógica; los artefactos se marcan como tales. Esto se construye sobre la estructura de PDF etiquetado del §14.7 de ISO 32000-2 (StructTreeRoot, elementos de estructura, MCID).
• El idioma natural se declara — §8.4.4: el documento y los cambios de idioma llevan un Lang. Con ConformancePolicy::strictUa2(), una etiqueta BCP-47 mal formada se rechaza en el límite de la API (fail-fast), en lugar de descartarse en silencio al escribir.
• Las figuras llevan alternativas — §8.5.1: cada elemento de estructura Figure incluye una descripción alternativa.
• Las tablas asocian encabezados y datos — §8.2.5.26: la asociación de celdas de header/data de la tabla se expresa estructuralmente.

NextPDF emite todos esos elementos. No ejecuta la evaluación de conformidad del §8.1: ese es el papel del verificador, y la norma lo reserva para él.

Superficie de la API

Método	Efecto
enableTaggedPdf(string $lang = 'en', ?ConformancePolicy $policy = null): static	Establece ConformanceMode::PdfUa2, conecta TaggedContentEmitter, valida $lang según la política. Lanza InvalidConfigException cuando la política exige la validación de Lang y $lang no es válido.
beginTag()/endTag()	Estructura manual para contenido que no es HTML; los tipos de contenedor se convierten en elementos de agrupación y los tipos hoja reciben MCID.
ConformanceMode::requiresPdfUa2PageTabs(): bool	Devuelve verdadero para PdfUa2 — hace que se aplique /Tabs /S en la página.

Ejemplo de código — Inicio rápido

<?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";

Ejemplo de código — Producción

La compuerta de producción ejecuta verapdf --flavour ua2 out.pdf y hace fallar la compilación ante las infracciones reportadas. La prueba de integración tests/Integration/Accessibility/VeraPdfUa2GoldenTest.php verifica que el fixture golden de HTML→PDF etiquetado supere veraPDF UA-2 (se omite cuando veraPDF está ausente). El veredicto del verificador actúa como compuerta; la salida del emisor es su entrada.

Casos límite y trampas

• Habilitar primero. Ejecutar enableTaggedPdf() después de writeHtml() no etiqueta retroactivamente el contenido ya escrito.
• Idioma estricto. Pasar ConformancePolicy::strictUa2() permite rechazar una etiqueta BCP-47 mal formada en el límite de la API, en lugar de fallar solo en la validación posterior con veraPDF.
• Rehabilitación idempotente. Invocarlo dos veces actualiza el idioma sin reconstruir un árbol de estructura ya poblado.
• Documento etiquetado vacío. Un documento etiquetado vacío no anuncia PDF/UA-2 (EmptyTaggedPdfDoesNotAdvertisePdfUa2Test): el marcador no se emite para un documento sin contenido real, de modo que el archivo no declara más de lo que corresponde.

Rendimiento

La emisión del árbol de estructura es proporcional al número de elementos. Tiene un presupuesto de tiempo de pared ≤ 1500 ms y un pico ≤ 64 MB para un informe típico.

Notas de seguridad

El etiquetado de accesibilidad es estructural, no un control de seguridad. Expone la estructura lógica del documento a las tecnologías de asistencia por diseño: el árbol de etiquetas no aporta confidencialidad.

Asignación de PDF/UA-2

Obligación de PDF/UA-2	Cláusula de ISO 14289-2	Emisión de NextPDF
Contenido real etiquetado en la estructura lógica	§8.2.2	TaggedContentEmitter + StructureTree
Idioma del documento o de la estructura declarado	§8.4.4	catálogo /Lang, validado mediante Bcp47Validator
Descripción alternativa para la figura	§8.5.1	alt → /Alt en el elemento Figure
Asociación de header/data de la tabla	§8.2.5.26	Estructura TR/TH/TD a partir de tablas HTML

Referencia cruzada de etiqueta → §14.9 de ISO 32000-2

PDF/UA-2 se superpone al modelo de PDF etiquetado de ISO 32000-2. Los elementos de estructura que NextPDF emite se resuelven frente a la estructura lógica del §14.7 de ISO 32000-2 (StructTreeRoot, elementos de estructura, MCID) —chunk— y frente al espacio de nombres de estructura estándar definido para PDF 2.0. El mapa de roles relaciona los elementos HTML (h1, p, table) con los tipos de estructura estándar para que un verificador UA-2 los reconozca.

Asignación de WCAG 2.2

La estructura etiquetada es el sustrato técnico de los criterios de éxito de WCAG 2.2 — 1.1.1 (alternativas no textuales, mediante la /Alt de la Figure del §8.5.1), 1.3.1 (información y relaciones, mediante el árbol de estructura) y 1.3.2 (secuencia significativa, mediante el orden de lectura). Emitir la estructura es necesario, pero no suficiente, para la conformidad con WCAG; quien hace esa determinación es una auditoría de accesibilidad, no la biblioteca.

Comportamiento en modo FIPS

La emisión de PDF/UA-2 no realiza ninguna criptografía. El modo FIPS no afecta la ruta de la estructura etiquetada.

Conformidad

Afirmación	Especificación	Cláusula	reference_id
La versión de PDF/UA se identifica mediante el espacio de nombres de esquema pdfuaid (Tabla 1).	ISO 14289-2	§5
La conformidad con PDF/UA-2 impone requisitos de formato de archivo que un documento debe satisfacer (un verificador evalúa la conformidad; el productor no la declara).	ISO 14289-2	§8.1
El contenido real debe etiquetarse en la estructura lógica.	ISO 14289-2	§8.2.2
El idioma natural del documento debe declararse.	ISO 14289-2	§8.4.4
Los elementos Figure requieren una descripción alternativa.	ISO 14289-2	§8.5.1
La estructura de la tabla debe asociar las celdas de encabezado y de datos.	ISO 14289-2	§8.2.5.26
La estructura accesible se construye sobre la estructura lógica de PDF etiquetado de ISO 32000-2.	ISO 32000-2	§14.7.2

Las citas son punteros de clause-id + reference_id hacia el corpus de verificación. No se reproduce texto de las normas.

Véase también

• Página de inicio de conformidad
• Base de PDF 2.0
• Módulo de accesibilidad
• Recipe: PDF/UA-2 accesible a partir de HTML