Conformità PDF/UA-2: struttura con tag generata da NextPDF per ISO 14289-2

In breve

Dichiarazione di confine. NextPDF genera la struttura con tag che supporta la creazione di contenuti accessibili; non dichiara la conformità PDF/UA-2: è un checker a determinarla.

PDF/UA-2 corrisponde a ISO 14289-2:2024, il profilo di accessibilità sovrapposto al PDF 2.0 con tag. NextPDF Core genera l’albero della struttura, il contenuto contrassegnato, la lingua di catalog/structure e il marcatore pdfuaid tramite Document::enableTaggedPdf(). La libreria produce la struttura accessibile; la conformità viene stabilita da un checker PDF/UA (ad esempio verapdf --flavour ua2). Il §8.1 di ISO 14289-2 inquadra la conformità come un insieme di requisiti del formato di file che un documento deve soddisfare, valutati da un checker e non dichiarati dal produttore.

Installazione

composer require nextpdf/core:^3

Il tagging PDF/UA-2 è una funzionalità di Core (security.tagged_pdf). Per la struttura con tag in sé non è richiesto alcun pacchetto Premium.

Panoramica concettuale

Document::enableTaggedPdf(string $lang = 'en', ?ConformancePolicy $policy = null) imposta ConformanceMode::PdfUa2 e collega TaggedContentEmitter. La modalità è l’unica fonte di verità per stabilire se un documento è dotato di tag conformi alla specifica; il writer soddisfa così gli obblighi strutturali imposti da ISO 14289-2:

• Il contenuto reale è dotato di tag — §8.2.2: ogni elemento di contenuto reale (non artefatto) è incluso nella struttura logica; gli artefatti sono contrassegnati come tali. Questo si fonda sulla struttura PDF con tag del §14.7 di ISO 32000-2 (StructTreeRoot, elementi di struttura, MCID).
• La lingua naturale è dichiarata — §8.4.4: il documento e i cambi di lingua riportano un Lang. Con ConformancePolicy::strictUa2(), un tag BCP-47 non valido viene rifiutato al confine dell’API (fail-fast), invece di essere scartato silenziosamente in fase di scrittura.
• Le figure riportano alternative — §8.5.1: ogni elemento di struttura Figure ha una descrizione alternativa.
• Le tabelle associano intestazioni e dati — §8.2.5.26: l’associazione tra celle header/data della tabella è espressa a livello strutturale.

NextPDF genera questi elementi. Non esegue la valutazione di conformità del §8.1: è compito del checker, al quale lo standard la riserva.

Superficie dell’API

Metodo	Effetto
enableTaggedPdf(string $lang = 'en', ?ConformancePolicy $policy = null): static	Imposta ConformanceMode::PdfUa2, collega TaggedContentEmitter, convalida $lang in base alla policy. Genera InvalidConfigException quando la policy impone la convalida di Lang e $lang non è valido.
beginTag()/endTag()	Struttura manuale per contenuti non HTML; i tipi container diventano elementi di raggruppamento, ai tipi foglia vengono assegnati gli MCID.
ConformanceMode::requiresPdfUa2PageTabs(): bool	True per PdfUa2: determina l’applicazione di /Tabs /S a livello della pagina.

Esempio di codice — Avvio rapido

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

Esempio di codice — Produzione

Il gate di produzione esegue verapdf --flavour ua2 out.pdf e fa fallire la build in caso di violazioni segnalate. Il test di integrazione tests/Integration/Accessibility/VeraPdfUa2GoldenTest.php verifica che il fixture golden HTML→PDF con tag superi veraPDF UA-2 (viene ignorato quando veraPDF è assente). Il verdetto del checker è il gate; l’output dell’emitter ne è l’input.

Casi limite e insidie

• Abilitare per primo. enableTaggedPdf() dopo writeHtml() non applica retroattivamente i tag al contenuto già scritto.
• Lingua in modalità strict. Passare ConformancePolicy::strictUa2() per rifiutare un tag BCP-47 non valido al confine dell’API, invece di farlo fallire solo nella successiva convalida veraPDF.
• Riabilitazione idempotente. Chiamarlo due volte aggiorna la lingua senza ricostruire un albero della struttura già popolato.
• Documento con tag vuoto. Un documento con tag vuoto non dichiara PDF/UA-2 (EmptyTaggedPdfDoesNotAdvertisePdfUa2Test): il marcatore non viene generato per un documento privo di contenuto reale, così il file non rivendica più di quanto offra.

Prestazioni

La generazione dell’albero della struttura è proporzionale al numero di elementi. Budget previsto: wall ≤ 1500 ms, picco ≤ 64 MB per un report tipico.

Note sulla sicurezza

Il tagging di accessibilità è strutturale, non un controllo di sicurezza. Espone per progettazione la struttura logica del documento alle tecnologie assistive: l’albero dei tag non ha alcuna funzione di riservatezza.

Mappatura PDF/UA-2

Obbligo PDF/UA-2	Clausola ISO 14289-2	Generazione NextPDF
Contenuto reale dotato di tag nella struttura logica	§8.2.2	TaggedContentEmitter + StructureTree
Lingua di documento/struttura dichiarata	§8.4.4	catalog /Lang, convalidato tramite Bcp47Validator
Descrizione alternativa per la figura	§8.5.1	alt → /Alt sull’elemento Figure
Associazione header/data della tabella	§8.2.5.26	Struttura TR/TH/TD dalle tabelle HTML

Riferimento incrociato tag → ISO 32000-2 §14.9

PDF/UA-2 si sovrappone al modello di PDF con tag di ISO 32000-2. Gli elementi di struttura che NextPDF genera vengono risolti rispetto alla struttura logica del §14.7 di ISO 32000-2 (StructTreeRoot, elementi di struttura, MCID) — chunk — e rispetto allo spazio dei nomi di struttura standard definito per PDF 2.0. La role map collega gli elementi HTML (h1, p, table) ai tipi di struttura standard, in modo che un checker UA-2 li riconosca.

Mappatura WCAG 2.2

La struttura con tag è il substrato tecnico per i criteri di successo WCAG 2.2: 1.1.1 (alternative non testuali, tramite §8.5.1 Figure /Alt), 1.3.1 (informazioni e relazioni, tramite l’albero della struttura) e 1.3.2 (sequenza significativa, tramite l’ordine di lettura). Generare la struttura è necessario ma non sufficiente per la conformità WCAG; a stabilirla è un audit di accessibilità, non la libreria.

Comportamento in modalità FIPS

La generazione PDF/UA-2 non esegue alcuna operazione crittografica. La modalità FIPS non ha alcun effetto sul percorso della struttura con tag.

Conformità

Asserzione	Specifica	Clausola	reference_id
La versione PDF/UA è identificata dallo spazio dei nomi dello schema pdfuaid (Tabella 1).	ISO 14289-2	§5
La conformità a PDF/UA-2 impone requisiti del formato di file che un documento deve soddisfare (è un checker a valutare la conformità; il produttore non la dichiara).	ISO 14289-2	§8.1
Il contenuto reale deve essere dotato di tag nella struttura logica.	ISO 14289-2	§8.2.2
La lingua naturale del documento deve essere dichiarata.	ISO 14289-2	§8.4.4
Gli elementi Figure richiedono una descrizione alternativa.	ISO 14289-2	§8.5.1
La struttura della tabella deve associare le celle di intestazione e di dati.	ISO 14289-2	§8.2.5.26
La struttura accessibile si fonda sulla struttura logica del PDF con tag di ISO 32000-2.	ISO 32000-2	§14.7.2

Le citazioni sono puntatori clause-id + reference_id nel corpus di verifica. Non viene riprodotto alcun testo degli standard.

Vedere anche

• Pagina iniziale sulla conformità
• Baseline PDF 2.0
• Modulo di accessibilità
• Ricetta per un PDF/UA-2 accessibile da HTML