Mappare i ruoli landmark ARIA in un PDF taggato tramite Connect

In sintesi

Inviare HTML che usa elementi di sezionamento HTML5 e ruoli landmark ARIA tramite i trasporti Connect. La pipeline dei contenuti taggati li mappa sui tipi di struttura standard di PDF 2.0, consentendo alla tecnologia assistiva di navigare per landmark anziché in base alla posizione visiva. Il controllo di accessibilità usato qui è di livello Pro: lo strumento viene individuato tramite una probe class_exists() e viene registrato solo quando nextpdf/premium è installato insieme al server. La creazione del documento e l’ingestione di HTML usano gli strumenti core.

Lo strumento di accessibilità segnala i rilievi rispetto a PDF/UA-2 (ISO 14289-2). Un esito di superamento rappresenta la valutazione propria dello strumento. Si tratta di un controllo di accessibilità, non di una certificazione di conformità indipendente. La determinazione di conformità spetta a veraPDF o a un altro checker.

Installazione

composer require nextpdf/server

Confermare che lo strumento di accessibilità Pro sia presente nel deployment in esecuzione con una chiamata tools/list (vedere /connect/tool-catalog/). Se è assente, nextpdf/premium non è installato in questo deployment, quindi il passo di verifica della ricetta non può essere eseguito.

Panoramica concettuale

Gli elementi di struttura di raggruppamento organizzano la struttura logica di un documento in sezioni e contenitori analoghi (ISO 32000-2 §14.8). La pipeline HTML mappa questi elementi:

<aside> e role="complementary" → il tipo standard PDF 2.0 Aside
<article> / role="article" → Art
<nav> / role="navigation" → Sect

Un tipo di struttura non standard è accettabile solo quando è mappato per ruolo su un tipo standard (PDF/UA-2 §8.2.5). La pipeline emette direttamente il tipo standard, quindi non è necessaria alcuna mappa dei ruoli manuale. Il contenuto deve essere riflesso nell’albero della struttura affinché la tecnologia assistiva possa raggiungerlo (PDF/UA-2 §8.2.4).

Superficie API

I nomi degli strumenti vengono verificati rispetto al registry in esecuzione tramite tools/list. Il catalogo di riferimento è /connect/tool-catalog/. Questa ricetta usa gli strumenti core per la creazione del documento e l’ingestione di HTML, insieme al controllo di accessibilità Pro. Non ripete un conteggio fisso degli strumenti.

Esempio di codice — Avvio rapido

Creare un documento PDF 2.0 taggato, aggiungere HTML con ruoli landmark e verificarlo (MCP tools/call, in sequenza):

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "create_pdf",
    "arguments": { "page_size": "A4", "title": "ARIA Landmark Demo", "language": "en" }
  }
}

Collegare l’emettitore di contenuti taggati prima di aggiungere qualsiasi HTML. Creare il documento con una lingua impostata, in modo che l’emettitore sia attivo fin dalla prima chiamata di contenuto.

Esempio di codice — Produzione

Aggiungere l’HTML con i landmark ed eseguire il controllo di accessibilità, trattando uno stato non riuscito come un esito normale da ispezionare anziché come un errore di trasporto:

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "add_html",
    "arguments": {
      "document_id": "<id from create_pdf>",
      "html": "<main><h1>Annual Report</h1><aside><h2>Aside</h2><p>Note.</p></aside><div role=\"complementary\"><h2>Related</h2><p>Links.</p></div><nav role=\"navigation\"><p>Skip nav</p></nav></main>"
    }
  }
}

La risposta del controllo riporta l’albero della struttura osservato e un riepilogo dei rilievi PDF/UA-2. Sia <aside> sia <div role="complementary"> vengono ricondotti allo stesso tipo standard Aside.

Casi limite e insidie

Emissione taggata non attiva prima del contenuto. Se il documento non è stato creato con una lingua / modalità taggata, la prima aggiunta di HTML produce contenuto non taggato e il controllo segnala un errore sui contenuti taggati. Ricreare il documento con la lingua impostata.
Ruolo in conflitto su un elemento di sezionamento (<aside role="navigation">) produce un avviso. Eliminare il ruolo in conflitto oppure usare un <div>.
Strumento assente. Senza nextpdf/premium, lo strumento di accessibilità Pro non viene registrato e il passo di verifica fallisce con un errore di strumento sconosciuto.

Prestazioni

Il budget del front-matter è un limite documentale. La mappatura dei landmark fa parte del normale passaggio di layout. Non aggiunge una fase separata e misurabile per i documenti tipici.

Note di sicurezza

Non applicabile oltre alle indicazioni generali sul trasporto Connect: non registrare il contenuto del documento né il corpo HTML a un livello di log esposto all’esterno.

Conformità

Mappatura PDF/UA-2

HTML	Tipo standard PDF 2.0
`<aside>`, `role="complementary"`	`Aside`
`<article>`, `role="article"`	`Art`
`<nav>`, `role="navigation"`	`Sect`

Riferimento incrociato Tag → ISO 32000-2 §14.9

Affermazione	Clausola	reference_id
Gli elementi di raggruppamento organizzano la struttura logica in sezioni	ISO 32000-2 §14.8
I tipi non standard richiedono la mappatura per ruolo su un tipo standard	PDF/UA-2 §8.2.5
Il contenuto deve essere raggiungibile attraverso l’albero della struttura	PDF/UA-2 §8.2.4

Mappatura WCAG 2.2

La navigazione per landmark supporta WCAG 2.2 SC 1.3.1 (Info and Relationships) e SC 2.4.1 (Bypass Blocks) a livello di contenuto. Il formato PDF trasporta la struttura. L’autore del contenuto resta responsabile delle decisioni di authoring a livello WCAG.

Un esito di superamento dello strumento di accessibilità costituisce un controllo di accessibilità, non una certificazione di conformità. La determinazione di conformità PDF/UA-2 spetta a un checker indipendente (per esempio, veraPDF).

Contesto commerciale

Lo strumento di controllo di accessibilità è di livello Pro e si registra solo quando nextpdf/premium è installato insieme al server.

Dettagli specifici di Connect

Disponibilità dei trasporti (MCP / REST / gRPC)

create_pdf, add_html e il controllo di accessibilità vengono invocati allo stesso modo tramite MCP tools/call, l’endpoint dello strumento REST e il servizio gRPC, attraverso l’esecutore di strumenti condiviso.

Livello di rischio HITL

La creazione del documento e l’ingestione di HTML sono di livello caution (esecuzione automatica, registrate nell’audit log). Il controllo di accessibilità è di sola lettura. Nessuno di questi strumenti è approval_required per impostazione predefinita. Vedere /connect/hitl-risk-tiers/.

Envelope JSON del gate di conferma

Questi strumenti non attivano il gate a meno che un override della configurazione dell’operatore non porti uno di essi a approval_required. Quando il gate viene applicato, il contratto dell’envelope di sfida e del token monouso è quello documentato in /connect/hitl-risk-tiers/.

Vedere anche

/cookbook/connect/figure-caption/ — struttura Figure / Caption annidata.
/cookbook/connect/aria-noteref-pattern/ — riferimento a nota a piè di pagina e ruoli del corpo.
/connect/tool-catalog/ — calcolo dell’insieme degli strumenti per livello.
/connect/hitl-risk-tiers/ — il modello di rischio e il gate.