unschema-graph, moteur typé de graphes Schema.org

Contexte

Les données structurées Schema.org permettent de décrire les entités et les relations d’une page dans un format lisible par les moteurs de recherche et d’autres systèmes capables d’exploiter du JSON-LD.

En pratique, leur mise en place devient vite difficile à maintenir dès qu’un site dépasse quelques blocs isolés : les entités se répètent, les références entre objets deviennent fragiles, les erreurs de structure sont faciles à introduire et les données dynamiques nécessitent une validation plus solide qu’un simple typage TypeScript.

unschema-graph est né de ce constat.

Le projet est conçu et développé par Johan Ledoux comme un projet open source personnel. Rootage soutient sa mise en avant et son développement dans le cadre de ses initiatives open source, tout en laissant la conception et la maintenance technique du projet à son auteur.

Problème

Écrire du JSON-LD à la main fonctionne sur des cas simples, mais devient rapidement difficile à fiabiliser à l’échelle d’un site ou d’une application.

Plusieurs problèmes reviennent régulièrement :

• les erreurs de propriétés ou de structure peuvent passer inaperçues jusqu’au rendu final ;
• les entités Schema.org sont souvent réparties dans plusieurs blocs indépendants, ce qui complique leur réutilisation et leurs relations ;
• les références @id et les graphes deviennent fastidieux à maintenir manuellement ;
• un typage TypeScript seul ne valide pas les données dynamiques provenant d’un CMS, d’une API ou d’un contenu utilisateur ;
• une sérialisation JSON naïve dans une balise <script> peut introduire des risques de sortie de contexte HTML.

L’objectif d’unschema-graph est donc de proposer une couche suffisamment structurée pour rendre ces usages plus sûrs et prévisibles, sans transformer Schema.org en abstraction opaque.

Ce qui a été fait

unschema-graph a été construit comme un ensemble de packages complémentaires autour d’un moteur commun.

Le projet comprend aujourd’hui :

• @unschema-graph/core, le moteur indépendant de tout framework ;
• @unschema-graph/astro, une intégration native pour Astro ;
• @unschema-graph/svelte, une intégration dédiée à Svelte 5 et SvelteKit.

Le cœur du projet fournit 51 builders Schema.org typés et validés à l’exécution avec Zod.

Les entités peuvent être composées directement entre elles ou reliées grâce à des références @id. Le moteur parcourt ensuite les relations, remonte les entités partagées et construit automatiquement un @graph unifié.

Le projet comprend également :

• une sérialisation JSON-LD conçue pour éviter les sorties de balise <script> ;
• la résolution des identifiants relatifs à partir d’une URL canonique ;
• la fusion déterministe d’entités partageant le même @id ;
• un composant Astro ne nécessitant aucun JavaScript côté client ;
• une intégration Svelte 5 utilisant la réactivité native du framework ;
• un inspecteur dans l’Astro Dev Toolbar ;
• une CLI d’audit capable d’analyser les fichiers HTML générés avant déploiement ;
• une documentation complète construite avec Astro Starlight.

Résultat et impact

Le projet a atteint la version 0.10.0, qui fige la surface d’API prévue avant la préparation de la version 1.0.

unschema-graph propose désormais une base cohérente pour produire et auditer des graphes Schema.org dans plusieurs environnements JavaScript, sans imposer de runtime client supplémentaire dans Astro.

À ce stade, le projet fournit notamment :

• 51 builders Schema.org couvrant les principaux cas d’usage web ;
• une validation runtime avec Zod en complément du typage TypeScript ;
• un moteur de graphe capable de dédupliquer et relier les entités ;
• des packages dédiés à Astro, Svelte 5 et aux usages framework-agnostic ;
• une CLI d’audit utilisable dans une chaîne CI/CD ;
• une documentation technique et des recettes d’intégration ;
• une distribution open source sous licence MIT.

Le projet reste volontairement centré sur un périmètre précis : rendre la production de JSON-LD structurée, contrôlable et agréable à maintenir pour les développeurs.

Choix techniques

Un cœur TypeScript indépendant des frameworks

La logique principale vit dans @unschema-graph/core.

Ce découpage permet de conserver un moteur indépendant d’Astro ou de Svelte et de faire des intégrations framework de simples couches d’adaptation.

Le projet s’appuie notamment sur :

• TypeScript pour le typage statique et l’expérience développeur ;
• Zod pour la validation runtime ;
• Schema.org 30.1 comme base de vocabulaire ciblée ;
• des APIs dédiées pour construire, relier, valider et sérialiser les entités.

Cette séparation évite de lier le modèle de données à un composant ou à un framework particulier.

Un moteur de graphe plutôt qu’une collection de blocs JSON-LD

L’un des choix structurants du projet est de traiter les données Schema.org comme un graphe d’entités reliées entre elles.

Une organisation, un site, un auteur ou un article peuvent ainsi être définis une seule fois puis référencés ailleurs.

Le moteur :

• parcourt les relations entre entités ;
• remonte les nœuds partagés dans un @graph unique ;
• résout les fragments #id à partir de l’URL de base ;
• fusionne les entités partageant une même identité ;
• produit un résultat déterministe avant sérialisation.

Cette logique réduit les duplications et rend les relations entre objets plus explicites dans le code.

Validation et sécurité au moment du build

Le projet ne se limite pas à fournir des types.

Les données sont validées à l’exécution afin de pouvoir contrôler des valeurs issues de sources dynamiques, puis sérialisées avec des protections adaptées à leur injection dans le HTML.

La CLI d’audit complète cette approche en analysant les fichiers générés pour repérer notamment :

• les références locales cassées ;
• les identifiants dupliqués ;
• les incohérences structurelles ;
• les conflits dans les graphes produits.

L’objectif est de déplacer un maximum d’erreurs vers le développement ou la CI, plutôt que de les découvrir une fois le site déployé.

Intégrations Astro et Svelte

L’intégration Astro reste server-first : le composant <Schema /> produit du HTML statique et n’ajoute pas de JavaScript côté client.

Pour Svelte 5, l’intégration exploite au contraire la réactivité native du framework pour permettre aux données structurées de suivre les changements d’état lorsqu’un cas d’usage le nécessite.

Cette séparation permet de respecter les conventions de chaque écosystème sans dupliquer la logique métier du moteur.

Le rôle de Rootage

unschema-graph n’est pas un produit client Rootage : il s’agit d’un projet open source personnel de Johan Ledoux.

Rootage le soutient comme une initiative open source cohérente avec les sujets que nous travaillons au quotidien : qualité logicielle, architecture web, outillage développeur et mise en production fiable.

Cette distinction est volontaire. Elle permet de valoriser le travail technique réalisé sans présenter le projet comme une mission commerciale de l’agence.

Ce qu’on en retient

unschema-graph est un bon exemple de projet où un problème apparemment très spécialisé conduit à travailler plusieurs sujets d’ingénierie en profondeur :

• conception d’une API publique stable ;
• modélisation de données et relations entre entités ;
• validation statique et runtime ;
• sécurité de sérialisation ;
• compatibilité entre plusieurs frameworks ;
• tooling de développement et de CI ;
• documentation d’une librairie destinée à d’autres développeurs.

Le projet montre aussi l’intérêt de construire une abstraction ciblée : ne pas cacher Schema.org, mais fournir suffisamment de structure pour rendre son usage plus fiable, plus lisible et plus maintenable.