Implémentation moderne de JSON-LD en 2025 : vers un SEO plus propre et maintenable

En SEO technique, les fondamentaux sont souvent bien maîtrisés. Mais dès qu'on parle de données structurées, c'est une autre histoire. Beaucoup de projets web les intègrent à la hâte, souvent via des copier-coller non maintenus, sans validation, ni réelle logique de centralisation.

Publié il y a 3 mois

Par Jérôme Musialak

Pourtant, les données structurées en JSON-LD sont devenues indispensables pour la visibilité des contenus dans les résultats enrichis de Google. Encore faut-il les implémenter correctement.

Dans cet article, on vous propose une approche moderne, maintenable et typée de JSON-LD, pour des intégrations SEO robustes, particulièrement adaptées aux environnements JavaScript et TypeScript.

JSON-LD, à quoi ça sert ?

Le JSON-LD (JavaScript Object Notation for Linked Data) est un format recommandé par Google pour intégrer des données structurées dans une page HTML. Ces données aident les moteurs de recherche à mieux comprendre le contenu d'une page, en ajoutant un contexte sémantique : est-ce un article ? une recette ? une fiche produit ?

Contrairement aux anciens formats (microdonnées, RDFa), JSON-LD est séparé du HTML : on l'insère généralement dans une balise <script type="application/ld+json">. Cela présente plusieurs avantages :

Il n'interfère pas avec le balisage HTML
Il est plus lisible et plus facilement généré dynamiquement
Il est plus facile à maintenir dans un projet JavaScript/TypeScript.

Exemples :

Article, NewsArticle, BlogPosting : pour les contenus éditoriaux
Product, Offer, Review : pour l'e-commerce
Event, Organization, BreadcrumbList, etc.

L'objectif n'est pas uniquement d'augmenter la visibilité SEO, mais aussi de préparer un web plus sémantique et interopérable.

Les erreurs fréquentes (et encore trop courantes)

Même en 2025, beaucoup d'implémentations JSON-LD souffrent de problèmes qui peuvent freiner l'indexation ou l'affichage des rich snippets :

Multiplication des <script> dispersés : Chaque type de schéma est parfois injecté dans un script séparé, à différents endroits du DOM. Cela complique la lecture, la validation, et peut créer des conflits.
Duplication d'informations : On retrouve souvent les mêmes schémas injectés plusieurs fois, parfois avec des valeurs différentes. Cela brouille le signal envoyé à Google.
Données incomplètes ou mal typées : Un NewsArticle sans headline, ou une Organization avec une url invalide, ce sont des cas fréquents qui nuisent à l'efficacité du balisage.
Structure mal formée : Des erreurs de syntaxe JSON, des virgules oubliées, ou des noms de propriétés incorrects ("@context" au lieu de "context", par exemple) sont faciles à commettre... surtout sans typage.

schema-dts : typage et auto-complétion pour des schémas fiables

Pour répondre à ces enjeux de fiabilité et de maintenabilité, la bibliothèque schema-dts développée par Google est un véritable allié.
C'est un jeu de types TypeScript générés à partir de la spécification Schema.org. Il permet :

Un typage fort de vos objets JSON-LD
Une auto-complétion dans votre IDE (VS Code, WebStorm...)
La réduction des erreurs de nommage ou de structure
De générer des schémas valides et propres

Exemple :

import { NewsArticle } from "schema-dts";

const articleSchema: NewsArticle = {
  "@type": "NewsArticle",
  headline: "Implémenter JSON-LD proprement en 2025",
  datePublished: "2025-08-04T07:00:00.000Z",
  author: {
    "@type": "Person",
    name: "Jean Neymar"
  }
};

Grâce au typage, si vous oubliez une propriété requise (headline ou datePublished), TypeScript vous le signale immédiatement.

Centraliser les schémas avec @graph

Une des bonnes pratiques modernes est de centraliser tous les schémas dans un seul script, via la propriété @graph. Cela :

Réduit la complexité du DOM
Facilite la validation (tout est dans un seul objet)
Clarifie les relations entre entités

Voici une implémentation typique dans un <script type="application/ld+json">, centralisée via @graph, pour un blog avec article, fil d'ariane et organisation :

{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Organization",
      "name": "Exemple Blog",
      "url": "https://exemple.com",
      "logo": {
        "@type": "ImageObject",
        "url": "https://exemple.com/logo.png"
      }
    },
    {
      "@type": "BreadcrumbList",
      "itemListElement": [
        {
          "@type": "ListItem",
          "position": 1,
          "name": "Accueil",
          "item": "https://exemple.com"
        },
        {
          "@type": "ListItem",
          "position": 2,
          "name": "Blog",
          "item": "https://exemple.com/blog"
        },
        {
          "@type": "ListItem",
          "position": 3,
          "name": "Article JSON-LD"
        }
      ]
    },
    {
      "@type": "NewsArticle",
      "headline": "Implémentation moderne des données structurées en JSON-LD",
      "datePublished": "2025-08-04T07:00:00.000Z",
      "author": {
        "@type": "Person",
        "name": "Jean Neymar"
      },
      "publisher": {
        "@type": "Organization",
        "name": "Exemple Blog",
        "logo": {
          "@type": "ImageObject",
          "url": "https://exemple.com/logo.png"
        }
      },
      "mainEntityOfPage": "https://exemple.com/blog/json-ld-2025"
    }
  ]
}

Bonnes pratiques à adopter en 2025

Centralisez vos schémas : Utilisez @graph pour regrouper tous vos objets. Évitez les multiples scripts dispersés dans le DOM.
Validez systématiquement : Utilisez les outils Google (Rich Results Test, Search Console) ou l'outil de test de Schema.org pour vérifier la validité et l'éligibilité aux résultats enrichis.
Typage + validation automatique : Utilisez schema-dts ou des outils comme zod pour coupler typage et validation de structure.
Ne dupliquez pas les informations : Chaque entité (ex. : Organization) ne doit apparaître qu'une seule fois dans la page, avec des données cohérentes.
Soignez la lisibilité : Gardez vos fichiers de schéma bien organisés, idéalement dans un répertoire dédié (lib/schema.ts par exemple).
Évitez les surcharges inutiles : Inutile d'injecter tous les types disponibles. Privilégiez les plus utiles pour l'indexation : Article, Product, BreadcrumbList, FAQPage...

Un SEO propre commence par un JSON-LD bien pensé

Mettre en place des données structurées en JSON-LD, ce n'est pas juste cocher une case SEO. C'est structurer l'information pour un web plus compréhensible, maintenable et interopérable.

Avec une approche typée (schema-dts), centralisée (@graph), et validée, on passe d'un bricolage incertain à une architecture claire, robuste et durable. Et en bonus, vos intégrations seront plus faciles à faire évoluer dans le temps.

Un JSON-LD propre, c'est un SEO plus serein, une indexation plus efficace, et un code plus digne de confiance.