Mapper les rôles de repère ARIA vers un PDF balisé via Connect

En bref

Soumets, via les transports Connect, du HTML qui utilise les éléments de sectionnement HTML5 et les rôles de repère ARIA. Le pipeline de contenu balisé les mappe vers les types de structure standard du PDF 2.0, afin que les technologies d’assistance puissent naviguer par repères plutôt que selon la position visuelle. La vérification d’accessibilité utilisée ici relève du niveau Pro : l’outil est détecté à l’aide d’une sonde class_exists() et ne s’enregistre que lorsque nextpdf/premium est installé aux côtés du serveur. La création de document et l’ingestion de HTML s’appuient sur les outils du cœur.

L’outil d’accessibilité rapporte ses constats au regard de PDF/UA-2 (ISO 14289-2). Un résultat positif de l’outil correspond à sa propre évaluation. Il s’agit d’une vérification d’accessibilité, pas d’une certification de conformité indépendante. La détermination de conformité revient à veraPDF ou à un autre vérificateur.

Installation

composer require nextpdf/server

Vérifie que l’outil d’accessibilité Pro est présent dans le déploiement actif au moyen d’un appel tools/list (voir /connect/tool-catalog/). S’il est absent, nextpdf/premium n’est pas installé sur ce déploiement ; l’étape de vérification de la recette ne peut donc pas s’exécuter.

Aperçu conceptuel

Les éléments de structure de regroupement organisent la structure logique d’un document en sections et en conteneurs similaires (ISO 32000-2 §14.8). Le pipeline HTML mappe ces éléments :

<aside> et role="complementary" → le type standard PDF 2.0 Aside
<article> / role="article" → Art
<nav> / role="navigation" → Sect

Un type de structure non standard n’est acceptable que lorsqu’il est mappé par rôle vers un type standard (PDF/UA-2 §8.2.5). Le pipeline émet directement le type standard, donc aucun mappage de rôle manuel n’est requis. Le contenu doit être reflété dans l’arbre de structure pour que les technologies d’assistance puissent y accéder (PDF/UA-2 §8.2.4).

Surface d’API

Les noms d’outils sont vérifiés auprès du registre actif via tools/list. Le catalogue de référence se trouve dans /connect/tool-catalog/. Cette recette utilise les outils du cœur pour la création de document et l’ingestion de HTML, ainsi que la vérification d’accessibilité Pro. Elle ne reprend pas un nombre d’outils figé.

Exemple de code — Démarrage rapide

Crée un document PDF 2.0 balisé, ajoute du HTML avec des rôles de repère, puis vérifie-le (MCP tools/call, en séquence) :

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

Configure l’émetteur de contenu balisé avant d’ajouter le moindre HTML. Crée le document avec une langue définie pour que l’émetteur soit actif dès le premier appel de contenu.

Exemple de code — Production

Ajoute le HTML de repères et exécute la vérification d’accessibilité, en traitant tout statut autre que réussi comme une situation normale à inspecter plutôt que comme une erreur de transport :

{
  "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 réponse de vérification renvoie l’arbre de structure qu’elle a observé ainsi qu’un récapitulatif des constats PDF/UA-2. <aside> et <div role="complementary"> sont tous deux ramenés au même type standard Aside.

Cas limites & pièges

Émission balisée inactive avant le contenu. Si le document n’a pas été créé avec une langue ou un mode balisé, le premier ajout de HTML produit du contenu non balisé, et la vérification signale un échec du balisage du contenu. Recrée le document avec la langue définie.
Rôle conflictuel sur un élément de sectionnement. <aside role="navigation"> produit un avertissement. Supprime le rôle conflictuel ou utilise un <div>.
Outil absent. Sans nextpdf/premium, l’outil d’accessibilité Pro n’est pas enregistré, et l’étape de vérification échoue avec une erreur indiquant un outil inconnu.

Performance

Le budget du front-matter est une limite documentée. Le mappage des repères fait partie de la passe normale de mise en page. Pour les documents typiques, il n’ajoute aucune phase distincte mesurable.

Notes de sécurité

Rien de spécifique au-delà des recommandations générales relatives au transport Connect : ne journalise pas le contenu du document ni le corps HTML à un niveau de journalisation exporté vers l’extérieur.

Conformité

Mappage PDF/UA-2

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

Renvoi Balise → ISO 32000-2 §14.9

Affirmation	Clause	reference_id
Les éléments de regroupement organisent la structure logique en sections	ISO 32000-2 §14.8
Les types non standard exigent un mappage par rôle vers un type standard	PDF/UA-2 §8.2.5
Le contenu doit être atteignable via l’arbre de structure	PDF/UA-2 §8.2.4

Mappage WCAG 2.2

La navigation par repères prend en charge les critères de succès WCAG 2.2 SC 1.3.1 (Info and Relationships) et SC 2.4.1 (Bypass Blocks) au niveau du contenu. Le format PDF porte la structure. L’auteur du contenu reste responsable des choix rédactionnels au niveau WCAG.

Un résultat positif de l’outil d’accessibilité constitue une vérification d’accessibilité, et non une certification de conformité. Un vérificateur indépendant (par exemple, veraPDF) établit la détermination de conformité PDF/UA-2.

Contexte commercial

L’outil de vérification d’accessibilité relève du niveau Pro et ne s’enregistre que lorsque nextpdf/premium est installé aux côtés du serveur.

Spécificités de Connect

Disponibilité des transports (MCP / REST / gRPC)

create_pdf, add_html et la vérification d’accessibilité sont invoqués de manière identique via MCP tools/call, le point de terminaison REST d’outil et le service gRPC, par l’intermédiaire de l’exécuteur d’outils partagé.

Niveau de risque HITL

La création de document et l’ingestion de HTML relèvent du niveau de prudence (exécution automatique, journalisée à des fins d’audit). La vérification d’accessibilité est en lecture seule. Aucun de ces outils n’est approval_required par défaut. Voir /connect/hitl-risk-tiers/.

Enveloppe JSON du portail de confirmation

Ces outils ne déclenchent pas le portail, sauf si une surcharge de configuration de l’opérateur élève l’un d’eux au niveau approval_required. Lorsqu’un outil passe par le portail, le contrat d’enveloppe de défi et de jeton à usage unique est celui documenté dans /connect/hitl-risk-tiers/.

Voir aussi

/cookbook/connect/figure-caption/ — structure Figure / Caption imbriquée.
/cookbook/connect/aria-noteref-pattern/ — rôles de référence de note de bas de page et de corps.
/connect/tool-catalog/ — calcul de l’ensemble d’outils par niveau.
/connect/hitl-risk-tiers/ — modèle de risque et portail.