Tutoriel PDF balisé via Connect

Tutoriel PDF balisé via Connect

Limite de conformité (à lire en premier). NextPDF émet la structure balisée, le texte alternatif et les métadonnées attendus par PDF/UA-2. La sortie est donc censée se conformer à PDF/UA-2 (ISO 14289-2). Cela ne rend pas le document « conforme » à lui seul. Un vérificateur indépendant — veraPDF en mode strict PDF/UA-2 — statue sur la conformité. Lis donc chaque mention « PASS », « conforme » ou « compliant » ci-dessous comme « le document est censé se conformer ; c’est veraPDF qui détermine le résultat ».

En bref

Dans ce tutoriel, tu produis un PDF balisé via les transports Connect. Tu actives le mode balisé, définis un titre, ajoutes du HTML structuré sémantiquement, puis vérifies le résultat avec l’outil de contrôle de conformité et veraPDF. Les outils de mode balisé et de contenu utilisés ici font partie du cœur (core). L’outil de vérification de conformité aux standards relève de l’offre Pro/Enterprise. Il n’est enregistré via class_exists() que lorsque nextpdf/premium est installé avec le serveur.

Installation

composer require nextpdf/server

Vue d’ensemble conceptuelle

La structure logique, associée à une spécification en langage naturel, rend le contenu navigable dans l’ordre de lecture (ISO 32000-2 §14.7). Une description alternative pour le contenu non textuel est portée par l’entrée /Alt (ISO 32000-2 §14.8). Le contenu doit être reflété dans l’arbre de structure, et c’est un vérificateur qui détermine la conformité (PDF/UA-2 §8.2.4). Quand tu écris du HTML sémantique bien structuré, le pipeline produit la structure correcte à ta place. Ce tutoriel s’appuie sur ce mécanisme, plutôt que sur une structure que tu construirais à la main.

Surface de l’API

Les noms d’outils sont vérifiés par rapport au registre en cours d’exécution via tools/list. Le catalogue de référence se trouve dans /connect/tool-catalog/. Ce tutoriel ne répète pas le décompte des outils.

Exemple de code — Démarrage rapide

Voici le parcours le plus direct. Active le mode balisé avec une langue, définis un titre, puis ajoute du contenu.

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

Active le mode balisé avant ton premier appel de contenu. Le moteur d’écriture fige le mode lorsqu’il émet la première page : l’activer plus tard ne revient donc pas baliser un contenu déjà émis. Un titre de document est obligatoire pour PDF/UA-2, et le mode balisé définit la préférence d’affichage du titre dans le lecteur.

Exemple de code — Production

Ajoute du HTML sémantique. Le pipeline associe les titres, les listes, les tableaux (avec <th scope>), les liens et les figures (avec alt) aux types de structure corrects :

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

" } }}">

Lance ensuite le contrôle de conformité aux standards pour PDF/UA-2, puis exécute veraPDF --flavour ua2 sur la sortie. Le résultat du contrôle et le verdict de veraPDF sont des évaluations. C’est ainsi que tu sais si le document est censé se conformer — c’est veraPDF, et non NextPDF, qui statue sur la conformité.

Cas limites et pièges

• Mode balisé activé après le contenu. Tout contenu ajouté avant que tu n’actives le mode reste non balisé, et le contrôle signale un échec lié au contenu balisé. Active le mode immédiatement après avoir créé le document.
• Image informative sans alt. Le contrôle signale un échec de texte alternatif de figure. Fournis un texte alternatif, ou marque une image décorative comme artefact (/cookbook/connect/page-artifacts/).
• Niveau de titre sauté. Sauter un niveau (par exemple H1 puis H3) constitue un échec d’ordre des titres. Ne descends que d’un seul niveau à la fois, au maximum.
• <th> sans scope. Une cellule d’en-tête sans cellule de données associée constitue un échec de structure de tableau. Donne à chaque <th> soit scope="col", soit scope="row".
• Titre manquant. Un document sans titre constitue un échec de métadonnées. Définis le titre après avoir activé le mode balisé.

Performances

Le budget défini dans le front-matter est un plafond documentaire. Le balisage fait partie de la passe normale de mise en page.

Notes de sécurité

Aucun point spécifique ne s’applique ici au-delà des recommandations générales sur le transport Connect : ne journalise pas le contenu du document ni le corps HTML à un niveau de journalisation exposé en externe.

Conformité

Correspondance PDF/UA-2

Le HTML sémantique correspond aux types de structure standard de PDF/UA-2 (H1–H6, P, L/LI/Lbl/LBody, Table/TR/TH/TD, Link, Figure/Caption, Aside). La correspondance est automatique. Ta part du contrat consiste à écrire du HTML sémantique.

Renvoi balise → ISO 32000-2 §14.9

Affirmation	Clause	reference_id
Structure logique + langue → navigable dans l’ordre de lecture	ISO 32000-2 §14.7
Description alternative portée par /Alt	ISO 32000-2 §14.8
Contenu dans l’arbre de structure ; un vérificateur détermine la conformité	PDF/UA-2 §8.2.4

Correspondance WCAG 2.2

La structure prend en charge les critères de succès WCAG 2.2 1.1.1, 1.3.1, 2.4.1 et 2.4.6 au niveau du contenu. En tant qu’auteur du contenu, tu restes responsable des décisions de rédaction au niveau WCAG.

NextPDF produit une sortie censée se conformer à PDF/UA-2. Il n’affirme pas la conformité. C’est veraPDF (ou un autre vérificateur) qui statue sur la conformité. Un contrôle réussi ou une exécution de veraPDF concluante montre que la sortie est censée se conformer, et non qu’elle est certifiée par NextPDF.

Contexte commercial

Les outils de mode balisé et de contenu font partie du cœur (core). L’outil de vérification de conformité aux standards relève de l’offre Pro/Enterprise, et il n’est enregistré que lorsque nextpdf/premium est installé avec le serveur.

Spécificités de Connect

Disponibilité des transports (MCP / REST / gRPC)

Tu invoques chaque outil de ce tutoriel de la même manière via MCP tools/call, le point de terminaison d’outil REST et le service gRPC. Tous passent par l’exécuteur d’outils partagé.

Niveau de risque HITL

Activer le mode balisé et utiliser les outils de contenu relèvent du niveau « prudence ». Le contrôle de conformité aux standards est en lecture seule. Le chemin de sortie avec écriture de fichier nécessite une approbation, contrairement au mode base64. Voir /connect/hitl-risk-tiers/.

Enveloppe JSON du verrou de confirmation

Lorsque le chemin de sortie avec écriture de fichier est verrouillé, le verrou renvoie une enveloppe de défi et un jeton à usage unique. Le jeton est lié au nom de l’outil, à un nonce et à une durée de vie (TTL) de 300 secondes. Pour continuer, invoque à nouveau l’outil avec arguments._confirmation_token. Voir /connect/hitl-risk-tiers/.

Voir aussi

• /cookbook/connect/conformance-mode/ — le discriminateur de mode utilisé par le mode balisé.
• /cookbook/connect/aria-tagged-pdf/ — correspondance des rôles de repère.
• /cookbook/connect/page-artifacts/ — exclure le contenu décoratif de l’arbre de structure.
• /connect/tool-catalog/ — calcul de l’ensemble d’outils par niveau.