Comment comprendre et étendre le graphe JSON-LD de Yoast ?

Yoast SEO produit sur chaque page un bloc de données structurées qui surprend souvent au premier regard : au lieu d'un objet unique décrivant l'article, on trouve une liste de nœuds reliés entre eux, décrivant le site, la page, l'organisation, l'auteur, l'image et le fil d'Ariane. Ce graphe JSON-LD de Yoast n'est pas une complication gratuite, c'est une manière de décrire une page comme un ensemble d'entités liées plutôt que comme une fiche isolée, et c'est cette structure qui permet à un moteur de comprendre que l'auteur de cet article est la même personne que celle citée sur une autre page. Encore faut il savoir la lire pour pouvoir l'étendre sans tout casser, ce qui est exactement l'objet de ce qui suit : comprendre la mécanique, puis y ajouter ce dont le site a besoin.

Lire le graphe généré

La première étape consiste à afficher le bloc produit sur une page et à identifier ses composants. Le mécanisme est parfaitement cohérent d'un bout à l'autre du site, ce qui rend l'apprentissage rapide et transposable à tous les projets, et il complète les autres réglages de l'extension décrits dans notre article sur la manière de compléter la meta box de Yoast.

Une liste de nœuds, pas un objet unique

Le bloc contient un tableau de nœuds, chacun décrivant une entité, et ces nœuds se référencent mutuellement par un identifiant plutôt que de s'imbriquer. Cette forme évite de répéter la description de l'organisation dans chaque page et permet à un même nœud d'être référencé par plusieurs autres. Elle est plus difficile à lire pour un humain que l'imbrication, et beaucoup plus économique pour un site de plusieurs milliers de pages, chaque nœud n'étant décrit qu'une fois par page quel que soit le nombre de références qui pointent vers lui.

Les identifiants et leur rôle

Chaque nœud porte un identifiant construit à partir de l'adresse de la page suivie d'un fragment, ce qui garantit son unicité absolue à l'échelle du site entier. Ces identifiants sont le ciment du graphe : un nœud d'article y désigne son auteur, son image et la page dont il fait partie sans les redéfinir. Les modifier à la légère casse ces liens, et c'est la principale erreur commise par ceux qui tentent d'intervenir sur le balisage sans avoir compris le principe : le graphe reste valide au sens de la syntaxe, mais il ne décrit plus rien de cohérent.

Les pièces habituellement présentes

Un article génère typiquement six à huit nœuds : le site web, la page web, l'article lui même, l'organisation ou la personne qui édite le site, l'auteur, l'image principale et le fil d'Ariane. Une page de contact y ajoute un nœud d'informations de contact, une fiche produit un nœud de produit accompagné d'une offre, et une page de rubrique un nœud de collection. Cette composition varie selon les réglages, notamment selon que le site est déclaré comme représentant une organisation ou une personne, choix qui influence l'ensemble du graphe, se fait une fois pour toutes dans les réglages, et mérite d'être posé correctement dès l'installation.

L'entité principale de la page

Un nœud de page désigne toujours l'entité qui la résume, ce qui indique au moteur ce dont la page parle réellement. Sur un article, c'est l'article ; sur une fiche produit, c'est le produit. Cette désignation est ce qui permet de ne pas confondre la page et son sujet, distinction que beaucoup de balisages écrits à la main manquent complètement, en décrivant un produit sans jamais dire que la page en question porte sur ce produit, ce qui laisse le moteur deviner.

Ce que l'extension ne génère pas

Le graphe couvre le socle éditorial et laisse de côté tout ce qui relève d'un métier particulier : recettes, événements, offres d'emploi, questions fréquentes, cours, œuvres. Ces types se déclarent par des extensions dédiées ou par du code écrit pour le projet, et c'est précisément le sujet de l'extension du graphe traité dans la partie suivante. Une confusion fréquente consiste à ajouter ces balisages dans un second bloc indépendant, ce qui fonctionne mais prive le nouveau contenu de toute relation avec le reste du graphe, et donc de l'essentiel de son intérêt.

Pourquoi un graphe plutôt qu'un objet

Le choix de cette forme mérite d'être compris, car il explique la plupart des décisions qui suivent. Un balisage classique décrit une page comme un objet autonome, avec toutes ses propriétés imbriquées : l'article contient son auteur, qui contient sa description, qui contient son image. Chaque page redéclare alors l'ensemble, et rien n'indique au moteur que l'auteur de cet article est le même que celui d'un autre, ni que l'organisation citée ici est celle du site. Le graphe résout cela en donnant une identité stable à chaque entité, réutilisée partout où elle apparaît. C'est exactement le raisonnement suivi par les moteurs eux mêmes, qui construisent une représentation du monde en entités reliées plutôt qu'en documents isolés, et c'est ce qui rend le balisage utile au delà de la seule éligibilité aux affichages enrichis.

Étendre proprement

L'extension passe par des filtres prévus par l'extension elle même, ce qui évite d'avoir à réécrire ou à dupliquer le balisage. La démarche suit les mêmes principes que les autres personnalisations, tel que nous l'expliquons à propos des snippets ajoutés au fichier functions.php.

Ajouter un nœud au graphe

Un filtre permet de recevoir le tableau complet des nœuds juste avant sa sortie, d'y ajouter les siens et de retourner le tout. Le nœud ajouté doit porter son propre identifiant, construit sur le même modèle, et référencer les nœuds existants dont il dépend plutôt que de les redéfinir. C'est ce rattachement qui distingue une extension propre d'un ajout parallèle : un nœud d'événement doit désigner l'organisation existante comme organisateur, pas en créer une seconde qui entrerait en concurrence avec elle.

Modifier un nœud existant

Plutôt que de retirer un nœud pour le remplacer, il vaut mieux le retrouver dans le tableau par son type et modifier les propriétés concernées. Cette approche survit aux mises à jour de l'extension, qui ajoutent régulièrement des propriétés aux nœuds existants pour suivre l'évolution du vocabulaire, alors qu'un remplacement complet fige la version du jour et perd les évolutions. C'est aussi ce qui permet de corriger un point précis, un nom d'organisation mal orthographié par exemple, sans assumer la maintenance de tout le nœud.

Retirer ce qui n'a pas lieu d'être

Certains nœuds n'ont pas de sens sur certains gabarits, un fil d'Ariane sur la page d'accueil, qui n'a aucun parcours à décrire, en est l'exemple le plus courant. Ils se retirent en filtrant le tableau sur le gabarit concerné, ce qui est nettement préférable à une désactivation globale de la pièce quand le besoin est limité à quelques pages. Il faut simplement vérifier qu'aucun autre nœud ne référence celui qu'on retire, sous peine de laisser des références vers un identifiant inexistant, ce qui est plus dommageable que le nœud qu'on voulait retirer.

Utiliser les pièces plutôt que réécrire

L'extension expose ses générateurs de nœuds sous forme de pièces réutilisables, que l'on peut activer ou désactiver individuellement, et dont on peut s'inspirer pour écrire les siennes. Écrire une pièce plutôt qu'un filtre écrit à la va vite donne un code plus lisible, testable isolément et réutilisable d'un projet à l'autre sans adaptation. C'est l'approche à privilégier dès que l'ajout dépasse deux ou trois propriétés, et la seule tenable si plusieurs types métier doivent cohabiter.

Décrire ce qui est réellement affiché

La règle qui prime sur toutes les autres, et que la documentation des moteurs rappelle systématiquement, est que le balisage doit correspondre au contenu visible de la page, accessible au visiteur sans interaction particulière. Ajouter une note agrégée sans afficher d'avis, déclarer un prix différent de celui affiché, décrire des questions fréquentes absentes de la page constituent des manquements caractérisés, pouvant entraîner une pénalité manuelle qui retire les affichages enrichis à l'ensemble du site. Cette règle limite naturellement ce qu'il est utile d'ajouter, et elle est un excellent filtre à l'enthousiasme de ceux qui veulent tout baliser.

Le cas des questions fréquentes

Le balisage des questions fréquentes illustre bien les limites de l'exercice. Longtemps très recherché parce qu'il produisait un affichage enrichi occupant beaucoup de place dans les résultats, il a vu son usage fortement restreint par Google, qui ne l'affiche plus que pour un nombre limité de sites reconnus dans leur domaine. Le balisage reste valide et n'est pas pénalisant, il ne produit simplement plus l'effet visuel attendu. Cette évolution est instructive : un balisage se justifie parce qu'il décrit correctement la page, pas parce qu'il produisait un affichage particulier à un moment donné. Les sites qui avaient ajouté des blocs de questions artificielles au bas de chaque page uniquement pour obtenir cet affichage se retrouvent aujourd'hui avec un contenu inutile, alors que ceux dont les questions répondaient à un vrai besoin des visiteurs n'ont rien perdu.

Les erreurs les plus fréquentes

Les problèmes rencontrés sur ce sujet se répartissent en un petit nombre de cas, tous détectables en quelques minutes à condition de savoir quoi regarder. Aucun ne demande de compétence particulière, seulement la lecture attentive du code source d'une page.

Le balisage en double

Le cas le plus courant vient du thème, qui produit son propre balisage sans savoir qu'une extension s'en charge déjà, ou d'une seconde extension de référencement laissée active après un changement d'outil. La page déclare alors deux organisations, deux fils d'Ariane, deux articles, et le moteur choisit ou renonce. Le diagnostic est immédiat en comptant les blocs de données structurées présents dans le code source servi par le serveur : il ne doit y en avoir qu'un, celui du graphe, éventuellement complété par des nœuds ajoutés à l'intérieur. Beaucoup de thèmes commerciaux proposent une option pour désactiver leur propre balisage, précisément parce que ce conflit est connu de leurs auteurs.

Les identifiants cassés

Un nœud ajouté sans identifiant, ou avec un identifiant qui ne suit pas la convention, ne peut être référencé par aucun autre et flotte dans le graphe. Les outils de test le valident souvent malgré tout, puisqu'il est syntaxiquement correct, mais il perd tout l'intérêt de la structure et se retrouve traité comme un balisage isolé de plus. Le symptôme est discret : rien ne signale l'anomalie, et l'on croit avoir enrichi le graphe alors qu'on a simplement ajouté un objet à côté. La convention est simple et se déduit en observant les nœuds existants sur n'importe quelle page du site, ce qui prend deux minutes et évite d'avoir à chercher dans la documentation.

L'organisation mal déclarée

Les réglages de représentation du site, organisation ou personne, alimentent plusieurs nœuds à la fois. Une déclaration approximative, un nom qui ne correspond pas à la raison sociale, un logo absent ou d'un format non accepté, dégrade l'ensemble sans produire la moindre erreur dans les outils de test, ce qui explique que le problème passe inaperçu pendant des années. Ces réglages méritent donc une relecture attentive au moins une fois, d'autant qu'ils ne sont renseignés qu'une fois, souvent dans les premières minutes de l'installation, et jamais revus ensuite.

Les données incohérentes avec la page

Le cas le plus risqué est celui d'un balisage juste techniquement et faux sur le fond : un prix issu d'une source différente de celle affichée, une disponibilité calculée autrement, une date de publication qui ne correspond pas. Ces écarts se produisent silencieusement quand plusieurs extensions alimentent les mêmes informations, et ils ne se détectent qu'en comparant le balisage au rendu, ce qu'aucun outil automatique ne fait à votre place, faute de pouvoir juger de la cohérence entre deux sources.

Contrôler et suivre

Le balisage est un élément fragile, invisible pour l'équipe éditoriale, et qui disparaît sans bruit lors d'un changement de thème ou d'extension. Il mérite la même surveillance que l'image de partage, dont nous avons traité dans notre article sur la manière de forcer une image de partage par article avec Yoast SEO.

Tester sur un gabarit de chaque type

Le contrôle porte sur un échantillon représentatif plutôt que sur l'ensemble du site : accueil, page de rubrique, article, fiche produit, page de contact, page légale. Un gabarit correct l'est pour toutes les pages qui l'utilisent, ce qui rend inutile de tester au delà. Les outils de test proposés par les moteurs signalent les erreurs et les avertissements, et il faut soigneusement distinguer les deux niveaux : une erreur empêche l'éligibilité aux affichages enrichis, un avertissement signale une propriété recommandée mais facultative, qu'il n'est pas toujours pertinent de renseigner. Chercher à faire disparaître tous les avertissements conduit souvent à inventer des données, ce qui est bien pire que de laisser une propriété facultative vide.

Surveiller les rapports de la Search Console

Les rapports dédiés aux résultats enrichis indiquent le nombre d'éléments valides par type, le détail des erreurs et des avertissements, et conservent un historique de plusieurs mois. C'est le seul endroit qui reflète ce que le moteur a réellement compris et retenu, par opposition aux outils de test qui analysent une page à la demande. Une chute brutale du nombre d'éléments valides signale presque toujours une modification technique récente, et il faut alors chercher du côté des dernières mises à jour plutôt que du contenu.

Automatiser une vérification minimale

Un contrôle hebdomadaire sur une dizaine d'adresses, vérifiant la présence d'un bloc unique et de quelques nœuds attendus, tient en une trentaine de lignes et détecte immédiatement une disparition ou une duplication. C'est particulièrement utile après les mises à jour d'extensions, qui sont le principal facteur de régression sur ce sujet, devant les changements de thème.

Documenter les extensions apportées

Tout ajout au graphe doit être consigné quelque part : quel nœud, pour quel besoin, dans quel fichier, et à quelle date. Sans cette note, un balisage personnalisé devient rapidement une boîte noire que plus personne n'ose modifier, et qui finit par contredire le contenu du site sans que personne ne comprenne d'où il vient. Cette documentation est d'autant plus importante que le code concerné est court, souvent logé dans une extension propre au site, et parfaitement invisible depuis l'interface d'administration.