Tutorial sui PDF taggati con Connect

Tutorial sui PDF taggati con Connect

Limite di conformità (leggere prima questo). NextPDF emette la struttura taggata, il testo alternativo e i metadati previsti da PDF/UA-2. Questo rende l’output destinato a essere conforme a PDF/UA-2 (ISO 14289-2). Tuttavia non rende di per sé il documento «conforme». Un verificatore indipendente — veraPDF in modalità PDF/UA-2 rigorosa — stabilisce la conformità. Pertanto interpretare ogni affermazione «PASS», «conforme» o «conforme alle norme» qui sotto come «il documento è destinato a essere conforme; è veraPDF a determinare l’esito».

In sintesi

In questo tutorial si crea un PDF taggato tramite i trasporti Connect. Si abilita la modalità taggata, si imposta un titolo, si aggiunge HTML strutturato semanticamente e poi si verifica il risultato con lo strumento di controllo degli standard e con veraPDF. Gli strumenti della modalità taggata e dei contenuti usati qui fanno parte del core. Lo strumento di verifica per il controllo degli standard è di livello Pro/Enterprise. Viene registrato tramite class_exists() solo quando nextpdf/premium è installato insieme al server.

Installazione

composer require nextpdf/server

Panoramica concettuale

La struttura logica, insieme a una specifica in linguaggio naturale, rende i contenuti navigabili nell’ordine di lettura (ISO 32000-2 §14.7). Una descrizione alternativa per i contenuti non testuali è conservata nella voce /Alt (ISO 32000-2 §14.8). Il contenuto deve essere riflesso nell’albero della struttura, e un verificatore determina la conformità (PDF/UA-2 §8.2.4). Quando si scrive HTML semantico ben strutturato, il flusso di elaborazione produce automaticamente la struttura corretta. Questo tutorial si basa su questa capacità, anziché su una struttura costruita a mano.

Superficie API

I nomi degli strumenti sono verificati rispetto al registro in esecuzione tramite tools/list. Il catalogo di riferimento è /connect/tool-catalog/. Questo tutorial non ripete il conteggio degli strumenti.

Esempio di codice — Avvio rapido

Ecco il percorso più breve. Abilitare la modalità taggata con una lingua, impostare un titolo, quindi aggiungere i contenuti.

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "enable_tagged_pdf",
    "arguments": { "document_id": "<id>", "language": "en" }
  }
}

Abilitare la modalità taggata prima della prima chiamata di contenuto. Il writer congela la modalità quando emette la prima pagina, perciò abilitarla in seguito non retroagisce per taggare i contenuti già emessi. Un titolo del documento è obbligatorio per PDF/UA-2, e la modalità taggata imposta la preferenza di visualizzazione del titolo.

Esempio di codice — Produzione

Aggiungere HTML semantico. Il flusso di elaborazione mappa intestazioni, elenchi, tabelle (con <th scope>), collegamenti e figure (con alt) ai tipi di struttura corretti:

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "add_html",
    "arguments": {
      "document_id": "<id>",
      "html": "<h1>Annual Report</h1><h2>Summary</h2><p>Revenue grew.</p><table><caption>Revenue</caption><thead><tr><th scope=\"col\">Region</th><th scope=\"col\">Q1</th></tr></thead><tbody><tr><th scope=\"row\">EMEA</th><td>120</td></tr></tbody></table><figure><img src=\"chart.png\" alt=\"Revenue by region bar chart\" /><figcaption>Figure 1.</figcaption></figure>"
    }
  }
}

RevenueRegionQ1EMEA120

Figure 1.

" } }}">

Eseguire poi il controllo degli standard rispetto a PDF/UA-2 ed eseguire veraPDF --flavour ua2 sull’output. Il risultato del controllo e il verdetto di veraPDF sono valutazioni. Servono a sapere se il documento è destinato a essere conforme — è veraPDF, non NextPDF, a stabilire la conformità.

Casi limite e insidie

• Modalità taggata abilitata dopo i contenuti. Qualsiasi contenuto aggiunto prima di abilitare la modalità non è taggato, e il controllo segnala un errore relativo al contenuto taggato. Abilitare la modalità subito dopo aver creato il documento.
• Immagine informativa senza alt. Il controllo segnala un errore di testo alternativo della figura. Fornire un testo alternativo, oppure contrassegnare un’immagine decorativa come artefatto (/cookbook/connect/page-artifacts/).
• Livello di intestazione saltato. Saltare un livello (per esempio H1 poi H3) è un errore di ordine delle intestazioni. Scendere al massimo di un livello alla volta.
• <th> senza scope. Una cella di intestazione senza celle di dati associate è un errore di struttura della tabella. Assegnare a ogni <th> uno tra scope="col" e scope="row".
• Titolo mancante. Un documento senza titolo è un errore di metadati. Impostare il titolo dopo aver abilitato la modalità taggata.

Prestazioni

Il budget del front-matter è un limite documentale. La taggatura fa parte del normale passaggio di layout.

Note sulla sicurezza

Qui non si applica nulla oltre alle indicazioni generali sui trasporti Connect: non scrivere il contenuto del documento o il corpo HTML in un livello di log esportato all’esterno.

Conformità

Mappatura PDF/UA-2

L’HTML semantico viene mappato sui tipi di struttura standard di PDF/UA-2 (H1–H6, P, L/LI/Lbl/LBody, Table/TR/TH/TD, Link, Figure/Caption, Aside). La mappatura è automatica. La parte del contratto a carico di chi crea il contenuto consiste nello scrivere HTML semantico.

Tag → riferimento incrociato ISO 32000-2 §14.9

Affermazione	Clausola	reference_id
Struttura logica + lingua → navigabile nell’ordine di lettura	ISO 32000-2 §14.7
Descrizione alternativa conservata in /Alt	ISO 32000-2 §14.8
Contenuto nell’albero della struttura; un verificatore determina la conformità	PDF/UA-2 §8.2.4

Mappatura WCAG 2.2

La struttura supporta i criteri di successo WCAG 2.2 1.1.1, 1.3.1, 2.4.1 e 2.4.6 a livello di contenuto. Chi crea i contenuti resta responsabile delle decisioni redazionali a livello WCAG.

NextPDF produce un output destinato a essere conforme a PDF/UA-2. Non afferma la conformità. È veraPDF (o un altro verificatore) a determinare la conformità. Un controllo superato o un’esecuzione di veraPDF prova che l’output è destinato a essere conforme, non che NextPDF lo certifichi.

Contesto commerciale

Gli strumenti della modalità taggata e dei contenuti fanno parte del core. Lo strumento di verifica per il controllo degli standard è di livello Pro/Enterprise e viene registrato solo quando nextpdf/premium è installato insieme al server.

Specificità di Connect

Disponibilità dei trasporti (MCP / REST / gRPC)

Ogni strumento di questo tutorial si invoca allo stesso modo con MCP tools/call, l’endpoint dello strumento REST e il servizio gRPC. Tutti passano attraverso l’esecutore di strumenti condiviso.

Livello di rischio HITL

Abilitare la modalità taggata e usare gli strumenti dei contenuti sono operazioni di livello cautela. Il controllo degli standard è di sola lettura. Il percorso di output che scrive su file richiede approvazione, mentre la modalità base64 no. Vedere /connect/hitl-risk-tiers/.

Envelope JSON del gate di conferma

Quando il percorso di output che scrive su file è protetto da gate, il gate restituisce un envelope di challenge e un token monouso. Il token è vincolato al nome dello strumento, a un nonce e a un time-to-live (TTL) di 300 secondi. Per procedere, invocare di nuovo lo strumento con arguments._confirmation_token. Vedere /connect/hitl-risk-tiers/.

Vedere anche

• /cookbook/connect/conformance-mode/ — il discriminatore di modalità su cui si basa la modalità taggata.
• /cookbook/connect/aria-tagged-pdf/ — mappatura dei ruoli landmark.
• /cookbook/connect/page-artifacts/ — escludere i contenuti decorativi dall’albero della struttura.
• /connect/tool-catalog/ — calcolo dell’insieme di strumenti per livello.