Verificare l'accessibilità strutturale

In sintesi

Eseguire un’analisi dell’accessibilità strutturale con NextPDF Connect. Lo strumento è check_accessibility, riverificato rispetto al tool provider Pro, che registra new CheckAccessibilityTool() sotto il nome di protocollo check_accessibility. La descrizione stessa dello strumento ne delimita l’ambito: analizza l’accessibilità strutturale di un PDF — intestazioni, tabelle, immagini e indicatori dell’ordine di lettura. Evidenzia indicatori e suggerimenti di correzione. Non certifica la conformità PDF/UA o WCAG. Quel verdetto spetta a un checker di conformità — per esempio veraPDF o uno strumento di test PDF/UA — non a questo strumento. check_accessibility è uno strumento di livello Pro. NextPDF lo rileva con class_exists() all’avvio e lo registra solo quando il pacchetto Pro è installato.

Installazione

composer require nextpdf/server
composer require nextpdf/pro

Associare un transport. Verificare la presenza dello strumento con diagnostic.capabilities.

Panoramica concettuale

La struttura accessibile si fonda su due elementi: un albero di struttura logica composto da elementi di struttura (ISO 32000-2 §14.7) e una lingua del documento dichiarata, impostata tramite la voce Lang del catalogo (ISO 32000-2 §14.9; PDF/UA-2 §8.4.4). check_accessibility esamina questi indicatori strutturali e restituisce un report con gli esiti, ciascuno associato a una severità e a indicazioni di correzione. Qualsiasi punteggio numerico o pass/fail nel report è un riepilogo di indicatori, non una certificazione — va letto come segnale di triage.

Superficie API

Strumento	Livello	Ruolo	Livello di rischio
`create_pdf`, `add_text`	Core	Costruire il contenuto da esaminare	Caution / Caution
`check_accessibility`	Pro	Analisi dell’accessibilità strutturale	Safe
`output_pdf`	Core	Eseguire il rendering e restituire il PDF	Approval Required / Review (base64)

I nomi degli strumenti corrispondono ai nomi di protocollo del registry. Il catalogo degli strumenti è il catalogo di riferimento. Gli strumenti disponibili dipendono dal livello installato.

Esempio di codice — Quick start

create_pdf → aggiungere contenuto con add_text.
check_accessibility con il document_id.
Leggere gli esiti: severità, indicatore, pagina interessata e suggerimento di correzione.
Facoltativamente, usare output_pdf (base64) per la revisione manuale insieme al report.

Esempio di codice — Production

Trattare il report come input di triage, non come un verdetto. Associare ogni esito a una correzione concreta: abilitare l’output con tag, impostare la lingua del documento, aggiungere una struttura di intestazioni. Per un gate di conformità, eseguire un checker esterno e considerare autorevole il suo verdetto — non il punteggio di questo strumento. Eseguire il controllo prima di output_pdf con destroy: true, altrimenti lo strumento non può vedere il documento.

Casi limite e insidie

Nessun contenuto. Un documento vuoto produce un esito che segnala l’assenza di contenuto, non una certificazione.
Documento di grandi dimensioni. L’analisi è limitata da un timeout; suddividere gli input di grandi dimensioni o analizzarli per intervalli.
Sessione distrutta. Eseguire il controllo prima che l’output distrugga la sessione.
Sorgente cifrata. Fornire la password.
Pro assente. Con il solo Core, check_accessibility non è registrato.

Prestazioni

Il timeout del budget delimita l’analisi. Il profilo è semantic: il report è l’output di un’analisi strutturale, quindi un confronto corretto si basa sugli esiti, non sull’output in byte.

Note di sicurezza

Il report descrive la struttura, non i segreti del contenuto. Il documento in analisi può comunque essere sensibile, quindi va mantenuto entro il proprio perimetro di fiducia. Il percorso di analisi non scrive dati sul filesystem.

Conformità

Dichiarazione	Specifica	Clausola
La struttura logica è un albero di elementi di struttura.	ISO 32000-2	§14.7
La lingua del documento è dichiarata tramite la voce `Lang`.	ISO 32000-2	§14.9
La lingua naturale deve essere specificata per la creazione accessibile.	PDF/UA-2	§8.4.4

check_accessibility riporta indicatori strutturali che supportano la creazione accessibile. Non attesta la conformità PDF/UA o WCAG — il verdetto spetta a un checker indipendente.

Contesto commerciale

check_accessibility è uno strumento di livello Pro, registrato solo quando il pacchetto Pro risulta risolto all’avvio del server.

Mappatura PDF/UA-2

Gli indicatori strutturali esaminati dallo strumento sono allineati alle esigenze di creazione PDF/UA-2: un albero di struttura con tag (ISO 32000-2 §14.7) e una lingua del documento dichiarata (PDF/UA-2 §8.4.4). Lo strumento riporta se questi indicatori sono presenti o assenti. La conformità PDF/UA-2 è determinata da un checker PDF/UA, non dal report dello strumento.

Riferimento incrociato Tag → ISO 32000-2 §14

Gli esiti relativi a intestazioni e tabelle corrispondono a elementi di struttura logica nell’albero di struttura ISO 32000-2 §14.7. L’esito relativo alla lingua corrisponde alla voce Lang §14.9. Lo strumento evidenzia se questi punti di ancoraggio strutturali sono presenti. Non convalida ogni regola sui tag di §14 — questo è compito di un checker.

Mappatura WCAG 2.2

Gli esiti relativi a contrasto e ordine di lettura si riferiscono ai criteri di successo WCAG, per esempio contrasto e sequenza significativa. Lo strumento riporta i valori degli indicatori, come un rapporto di contrasto misurato. Un’affermazione di conformità WCAG richiede una valutazione WCAG completa, che questo strumento non esegue né attesta.

Disponibilità dei transport

Transport	Disponibile	Note
MCP (stdio)	Sì (Pro)	Il report è un risultato dello strumento.
REST	Sì (Pro)	Il report è il corpo della risposta.
gRPC	Sì (Pro)	Unary; report nel messaggio di risposta.

Livello di rischio HITL

check_accessibility è Safe (analisi in sola lettura) e non applica mai gate. output_pdf su file è Approval Required, mentre la modalità base64 è Review (livelli di rischio HITL).

Envelope JSON del gate di conferma

L’analisi non applica mai gate:

{ "allowed": true }