Tagged-PDF-Tutorial mit Connect

Tagged-PDF-Tutorial mit Connect

Konformitätsgrenze (lesen Sie dies zuerst). NextPDF gibt die getaggte Struktur, den Alternativtext und die Metadaten aus, die PDF/UA-2 erwartet. Das macht die Ausgabe dazu bestimmt, PDF/UA-2 (ISO 14289-2) zu entsprechen. Dadurch ist das Dokument nicht von sich aus „konform“. Ein unabhängiger Prüfer — veraPDF im strikten PDF/UA-2-Modus — entscheidet über die Konformität. Lesen Sie also jede Aussage „PASS“, „konform“ oder „kompatibel“ weiter unten als „das Dokument ist dazu bestimmt zu entsprechen; veraPDF bestimmt das Ergebnis“.

Auf einen Blick

In diesem Tutorial erstellen Sie ein Tagged PDF über die Connect-Transporte. Sie aktivieren den Tagged-Modus, legen einen Titel fest, fügen semantisch strukturiertes HTML hinzu und überprüfen anschließend das Ergebnis mit dem Standards-Check-Werkzeug und veraPDF. Die hier verwendeten Tagged-Modus- und Inhaltswerkzeuge gehören zum Core. Das Standards-Check-Werkzeug gehört zur Pro/Enterprise-Stufe. Es wird über class_exists() nur registriert, wenn nextpdf/premium zusammen mit dem Server installiert ist.

Installation

composer require nextpdf/server

Konzeptioneller Überblick

Eine logische Struktur in Verbindung mit einer Spezifikation in natürlicher Sprache macht Inhalte in Lesereihenfolge navigierbar (ISO 32000-2 §14.7). Eine Alternativbeschreibung für Nichttextinhalte wird im Eintrag /Alt gespeichert (ISO 32000-2 §14.8). Der Inhalt muss im Strukturbaum abgebildet sein, und ein Prüfer bestimmt die Konformität (PDF/UA-2 §8.2.4). Wenn Sie gut strukturiertes, semantisches HTML verfassen, erzeugt die Pipeline die korrekte Struktur für Sie. Dieses Tutorial baut darauf auf und nicht auf einer Struktur, die Sie von Hand erstellen.

API-Oberfläche

Werkzeugnamen werden über tools/list anhand der laufenden Registry verifiziert. Der maßgebliche Katalog ist /connect/tool-catalog/. Dieses Tutorial wiederholt keine Werkzeuganzahl.

Codebeispiel — Schnellstart

Hier ist der kürzeste Weg. Aktivieren Sie den Tagged-Modus mit einer Sprache, legen Sie einen Titel fest und fügen Sie anschließend Inhalt hinzu.

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

Aktivieren Sie den Tagged-Modus vor Ihrem ersten Inhaltsaufruf. Der Writer friert den Modus ein, wenn er die erste Seite ausgibt; ein späteres Einschalten wirkt daher nicht rückwirkend und taggt keinen bereits ausgegebenen Inhalt. Ein Dokumenttitel ist für PDF/UA-2 zwingend erforderlich, und der Tagged-Modus setzt die Viewer-Titel-Voreinstellung.

Codebeispiel — Produktion

Fügen Sie semantisches HTML hinzu. Die Pipeline bildet Überschriften, Listen, Tabellen (mit <th scope>), Links und Abbildungen (mit alt) auf die korrekten Strukturtypen ab:

{
  "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.

" } }}">

Führen Sie anschließend den Standards-Check gegen PDF/UA-2 sowie veraPDF --flavour ua2 für die Ausgabe aus. Das Check-Ergebnis und das veraPDF-Urteil sind Bewertungen. Daran erkennen Sie, ob das Dokument dazu bestimmt ist, PDF/UA-2 zu entsprechen — veraPDF, nicht NextPDF, entscheidet über die Konformität.

Grenzfälle & Fallstricke

• Tagged-Modus nach Inhalt aktiviert. Alle Inhalte, die Sie hinzufügen, bevor Sie den Modus einschalten, bleiben ungetaggt, und der Check meldet einen Tagged-Content-Fehler. Aktivieren Sie den Modus unmittelbar, nachdem Sie das Dokument erstellt haben.
• Informatives Bild ohne alt. Der Check meldet einen Figure-Alternativtext-Fehler. Geben Sie einen Alternativtext an oder markieren Sie ein dekoratives Bild als Artefakt (/cookbook/connect/page-artifacts/).
• Überschriftenebene übersprungen. Das Überspringen einer Ebene (zum Beispiel H1 dann H3) ist ein Fehler in der Überschriftenreihenfolge. Steigen Sie jeweils höchstens um eine Ebene ab.
• <th> ohne scope. Eine Kopfzelle ohne zugehörige Datenzellen ist ein Tabellenstrukturfehler. Weisen Sie jedem <th> entweder scope="col" oder scope="row" zu.
• Fehlender Titel. Ein Dokument ohne Titel ist ein Metadatenfehler. Legen Sie den Titel fest, nachdem Sie den Tagged-Modus aktiviert haben.

Performance

Das Front-Matter-Budget ist eine Dokumentationsobergrenze. Das Tagging ist Teil des normalen Layout-Durchlaufs.

Sicherheitshinweise

Hier gilt nichts, was über die allgemeinen Hinweise zum Connect-Transport hinausgeht: Protokollieren Sie weder Dokumentinhalt noch HTML-Body auf einer Log-Ebene, die extern ausgegeben wird.

Konformität

PDF/UA-2-Zuordnung

Semantisches HTML wird auf die PDF/UA-2-Standardstrukturtypen abgebildet (H1–H6, P, L/LI/Lbl/LBody, Table/TR/TH/TD, Link, Figure/Caption, Aside). Die Zuordnung erfolgt automatisch. Ihr Teil dieses Vertrags ist es, semantisches HTML zu verfassen.

Tag → ISO 32000-2 §14.9 Querverweis

Aussage	Klausel	reference_id
Logische Struktur + Sprache → in Lesereihenfolge navigierbar	ISO 32000-2 §14.7
Alternativbeschreibung in /Alt gespeichert	ISO 32000-2 §14.8
Inhalt im Strukturbaum; ein Prüfer bestimmt die Konformität	PDF/UA-2 §8.2.4

WCAG-2.2-Zuordnung

Die Struktur unterstützt WCAG 2.2 SC 1.1.1, 1.3.1, 2.4.1 und 2.4.6 auf Inhaltsebene. Sie bleiben als Inhaltsautor für die Erstellungsentscheidungen auf WCAG-Ebene verantwortlich.

NextPDF erzeugt eine Ausgabe, die dazu bestimmt ist, PDF/UA-2 zu entsprechen. Es behauptet keine Konformität. veraPDF (oder ein anderer Prüfer) bestimmt die Konformität. Ein bestandener Check oder veraPDF-Lauf belegt, dass die Ausgabe dazu bestimmt ist, PDF/UA-2 zu entsprechen; er ist keine Zertifizierung durch NextPDF.

Kommerzieller Kontext

Die Tagged-Modus- und Inhaltswerkzeuge gehören zum Core. Das Standards-Check-Werkzeug gehört zur Pro/Enterprise-Stufe und registriert sich nur dann, wenn nextpdf/premium zusammen mit dem Server installiert ist.

Connect-Besonderheiten

Transportverfügbarkeit (MCP / REST / gRPC)

Sie rufen jedes Werkzeug in diesem Tutorial auf dieselbe Weise über MCP tools/call, den REST-Werkzeug-Endpunkt und den gRPC-Dienst auf. Alle laufen über den gemeinsamen Werkzeug-Executor.

HITL-Risikostufe

Das Aktivieren des Tagged-Modus und die Verwendung der Inhaltswerkzeuge liegen in der Vorsichtsstufe. Der Standards-Check ist schreibgeschützt. Der dateischreibende Ausgabepfad erfordert eine Freigabe, der base64-Modus jedoch nicht. Siehe /connect/hitl-risk-tiers/.

JSON-Envelope des Bestätigungs-Gates

Wenn der dateischreibende Ausgabepfad durch das Gate abgesichert ist, gibt das Gate einen Challenge-Envelope und ein Einmal-Token zurück. Das Token ist an den Werkzeugnamen, eine Nonce und eine 300-Sekunden-Lebensdauer (TTL) gebunden. Um fortzufahren, rufen Sie das Werkzeug erneut mit arguments._confirmation_token auf. Siehe /connect/hitl-risk-tiers/.

Siehe auch

• /cookbook/connect/conformance-mode/ — der Modusdiskriminator hinter dem Tagged-Modus.
• /cookbook/connect/aria-tagged-pdf/ — Zuordnung von Landmark-Rollen.
• /cookbook/connect/page-artifacts/ — dekorativen Inhalt aus dem Strukturbaum ausschließen.
• /connect/tool-catalog/ — Berechnung des Werkzeugsatzes pro Stufe.