Conformidade PDF/UA-2: a estrutura marcada emitida pelo NextPDF para a ISO 14289-2

Visão geral

Declaração de limite. O NextPDF emite a estrutura marcada que dá suporte à criação de conteúdo acessível; ele não declara conformidade PDF/UA-2 — essa determinação cabe a um verificador.

O PDF/UA-2 é a ISO 14289-2:2024, o perfil de acessibilidade aplicado ao Portable Document Format (PDF) 2.0 marcado. O NextPDF Core emite a árvore de estrutura, o conteúdo marcado, o catálogo e o idioma da estrutura, além do marcador pdfuaid, por meio de Document::enableTaggedPdf(). A biblioteca cria a estrutura acessível; um verificador PDF/UA, como verapdf --flavour ua2, decide a conformidade. A ISO 14289-2 §8.1 define a conformidade como requisitos de formato de arquivo que um documento deve satisfazer e que são avaliados por um verificador, não como uma declaração feita pelo produtor.

Instalação

composer require nextpdf/core:^3

A marcação PDF/UA-2 é um recurso do Core (security.tagged_pdf). Você não precisa de um pacote Premium para emitir a estrutura marcada em si.

Visão conceitual

Document::enableTaggedPdf(string $lang = 'en', ?ConformancePolicy $policy = null) define ConformanceMode::PdfUa2 e conecta o TaggedContentEmitter. O modo é a única fonte de verdade para determinar se o documento está marcado conforme a especificação; em seguida, o escritor cumpre as obrigações estruturais impostas pela ISO 14289-2:

• O conteúdo real é marcado — §8.2.2: todo conteúdo real que não seja artefato é incluído na estrutura lógica, e os artefatos são marcados como tal. Isso é construído sobre a estrutura de PDF marcado da ISO 32000-2 §14.7 (StructTreeRoot, elementos de estrutura, MCIDs).
• O idioma natural é declarado — §8.4.4: o documento e as mudanças de idioma declaram um Lang. Com ConformancePolicy::strictUa2(), uma tag BCP-47 malformada é rejeitada na fronteira da API, fazendo a chamada falhar imediatamente, em vez de ser descartada silenciosamente no momento da escrita.
• As figuras carregam alternativas — §8.5.1: todo elemento de estrutura Figure tem uma descrição alternativa.
• As tabelas associam cabeçalhos e dados — §8.2.5.26: a associação entre células header/data da tabela é expressa estruturalmente.

O NextPDF emite essas estruturas. Ele não executa a avaliação de conformidade da §8.1; essa função cabe ao verificador, e a norma a reserva a ele.

Superfície da API

Método	Efeito
enableTaggedPdf(string $lang = 'en', ?ConformancePolicy $policy = null): static	Define ConformanceMode::PdfUa2, conecta o TaggedContentEmitter e valida $lang conforme a política. Lança InvalidConfigException quando a política exige validação de Lang e $lang é inválido.
beginTag()/endTag()	Estrutura manual para conteúdo não HTML; tipos de contêiner tornam-se elementos de agrupamento, e tipos folha recebem MCIDs.
ConformanceMode::requiresPdfUa2PageTabs(): bool	Retorna verdadeiro para PdfUa2 — aciona a aplicação de /Tabs /S nas páginas.

Exemplo de código — Início 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";

Exemplo de código — Produção

O gate de produção executa verapdf --flavour ua2 out.pdf e faz a build falhar quando o verificador relata violações. O teste de integração tests/Integration/Accessibility/VeraPdfUa2GoldenTest.php confirma que a fixture golden de HTML→PDF marcado passa no veraPDF UA-2 (ignorado quando o veraPDF está ausente). O veredito do verificador é o gate, e a saída do emissor serve como entrada para ele.

Casos extremos e pegadinhas

• Habilite primeiro. Chamar enableTaggedPdf() depois de writeHtml() não marca retroativamente o conteúdo já escrito.
• Idioma estrito. Passe ConformancePolicy::strictUa2() para rejeitar uma tag BCP-47 malformada na fronteira da API, em vez de deixar a falha aparecer apenas na validação posterior do veraPDF.
• Reativação idempotente. Chamá-lo duas vezes atualiza o idioma sem reconstruir uma árvore de estrutura já preenchida.
• Documento marcado vazio. Um documento marcado vazio não anuncia PDF/UA-2 (EmptyTaggedPdfDoesNotAdvertisePdfUa2Test): o marcador não é emitido para um documento sem conteúdo real, de modo que o arquivo não declara mais do que deveria.

Desempenho

A emissão da árvore de estrutura cresce proporcionalmente ao número de elementos. O orçamento para um relatório típico é de tempo de parede ≤ 1500 ms e pico ≤ 64 MB.

Notas de segurança

A marcação de acessibilidade é estrutural; não é um controle de segurança. Por projeto, ela expõe a estrutura lógica do documento à tecnologia assistiva. A árvore de tags não oferece uma camada de confidencialidade.

Mapeamento PDF/UA-2

Obrigação PDF/UA-2	Cláusula da ISO 14289-2	Emissão do NextPDF
Conteúdo real marcado na estrutura lógica	§8.2.2	TaggedContentEmitter + StructureTree
Idioma do documento/estrutura declarado	§8.4.4	catálogo /Lang, validado via Bcp47Validator
Descrição alternativa da figura	§8.5.1	alt → /Alt no elemento Figure
Associação header/data da tabela	§8.2.5.26	Estrutura TR/TH/TD a partir de tabelas HTML

Tag → referência cruzada com ISO 32000-2 §14.9

O PDF/UA-2 se sobrepõe ao modelo de PDF marcado da ISO 32000-2. Os elementos de estrutura que o NextPDF emite são resolvidos com base na estrutura lógica da ISO 32000-2 §14.7 (StructTreeRoot, elementos de estrutura, MCIDs) — chunk — e no namespace de estrutura padrão definido para o PDF 2.0. O mapa de funções vincula os elementos HTML (h1, p, table) aos tipos de estrutura padrão, para que um verificador UA-2 possa reconhecê-los.

Mapeamento WCAG 2.2

A estrutura marcada é a base técnica para os critérios de sucesso das Web Content Accessibility Guidelines (WCAG) 2.2 — 1.1.1 (alternativas não textuais, via Figure /Alt da §8.5.1), 1.3.1 (informações e relações, por meio da árvore de estrutura) e 1.3.2 (sequência com significado, por meio da ordem de leitura). Emitir a estrutura é necessário, mas não suficiente, para a conformidade com o WCAG; essa determinação cabe a uma auditoria de acessibilidade, não à biblioteca.

Comportamento no modo FIPS

A emissão PDF/UA-2 não executa nenhuma criptografia. O modo Federal Information Processing Standards (FIPS) não afeta o caminho da estrutura marcada.

Conformidade

Declaração	Especificação	Cláusula	reference_id
A versão do PDF/UA é identificada pelo namespace de schema pdfuaid (Tabela 1).	ISO 14289-2	§5
A conformidade com o PDF/UA-2 impõe requisitos de formato de arquivo que um documento deve satisfazer (um verificador avalia a conformidade; o produtor não a declara).	ISO 14289-2	§8.1
O conteúdo real deve ser marcado na estrutura lógica.	ISO 14289-2	§8.2.2
O idioma natural do documento deve ser declarado.	ISO 14289-2	§8.4.4
Os elementos Figure exigem uma descrição alternativa.	ISO 14289-2	§8.5.1
A estrutura da tabela deve associar as células de cabeçalho e de dados.	ISO 14289-2	§8.2.5.26
A estrutura acessível é construída sobre a estrutura lógica de PDF marcado da ISO 32000-2.	ISO 32000-2	§14.7.2

As citações são ponteiros de clause-id e reference_id para o corpus de verificação. Nenhum texto normativo é reproduzido.

Veja também

• Página inicial de conformidade
• Linha de base do PDF 2.0
• Módulo de acessibilidade
• Receita de PDF/UA-2 acessível a partir de HTML