Graphes et références d'entités
Un @graph unique permet aux entités reliées de référencer des nœuds partagés sans
répéter leurs propriétés dans plusieurs documents JSON-LD. unschema-graph construit
ce graphe, résout les identités relatives et fusionne les nœuds qui partagent un @id.
1. Pourquoi utiliser un @graph unifié ?
Section intitulée « 1. Pourquoi utiliser un @graph unifié ? »Lorsqu’un robot d’indexation (comme Googlebot) analyse une page web, il doit comprendre comment les différentes entités s’articulent :
- Cet
Articleest-il publié par cetteOrganization? - Cette
Personest-elle bien l’auteur de ce contenu ? - Comment le fil d’Ariane (
BreadcrumbList) se rattache-t-il à la page (WebPage) ?
Multiplier les balises <script type="application/ld+json"> complique la corrélation sémantique pour les algorithmes. Un tableau racine @graph réunit toutes vos entités en un véritable graphe de connaissances pour chaque page.
2. Définir des identifiants stables avec @id
Section intitulée « 2. Définir des identifiants stables avec @id »Pour référencer une entité depuis une autre, assignez-lui un @id :
import { Article, Organization, Person } from '@unschema-graph/core';
// 1. Organisation partagée avec identifiant fragmentconst organization = Organization({ '@id': '#organization', name: 'Acme Publishing', url: 'https://mon-site.fr',});
// 2. Auteur avec chemin et fragmentconst author = Person({ '@id': '/auteurs/ada#person', name: 'Ada Lovelace', url: 'https://mon-site.fr/auteurs/ada',});
// 3. Article référençant les deux entités via leur @idconst article = Article({ '@id': '#article', headline: 'Guide des graphes et références', image: 'https://mon-site.fr/couverture.jpg', datePublished: 'today', author: '/auteurs/ada#person', // Référence la Person publisher: '#organization', // Référence l'Organization});Références d’entités objets
Section intitulée « Références d’entités objets »Le pattern recommandé en v1 consiste à passer directement l’entité objet plutôt qu’un identifiant textuel. Chaque builder renvoyant un objet Schema.org strictement typé, TypeScript valide les types attendus dès la compilation :
const organization = Organization({ '@id': '#organization', name: 'Acme Publishing', url: 'https://mon-site.fr',});
const article = Article({ headline: 'Guide des données structurées', image: 'https://mon-site.fr/couverture.jpg', datePublished: '2026-09-29', author: 'Ada Lovelace', publisher: organization, // Référence d'entité objet typée !});Lorsque buildJsonLdGraph s’exécute :
- Il détecte que
organizationpossède un@id. - Il hisse
organizationcomme nœud racine du tableau@graph. - Il remplace automatiquement
article.publisherpar{ "@id": "https://mon-site.fr/#organization" }.
Raccourcis de chaînes d’identification
Section intitulée « Raccourcis de chaînes d’identification »Une chaîne est traitée comme référence lorsqu’elle commence par un fragment (#org),
un préfixe de chemin explicite (/a-propos#org, ./docs/page, ../docs/page) ou une URI
absolue avec n’importe quel schéma valide (https:, urn:, mailto:, tel:, etc.). Elle est alors transformée
en pointeur { "@id": "..." } :
// Ces deux syntaxes produisent exactement le même JSON-LD :publisher: '#organization'publisher: { '@id': '#organization' }Sinon, lorsque la relation déclare un fallbackType, la chaîne devient une entité
nommée inline. Sans type de fallback, une chaîne simple est rejetée : fournissez plutôt
une entité directe, une chaîne ressemblant explicitement à un identifiant ou un objet
{ '@id': '...' }.
author: 'Ada Lovelace'→{ "@type": "Person", "name": "Ada Lovelace" }brand: 'Acme Corp'→{ "@type": "Brand", "name": "Acme Corp" }brand: 'AC/DC'→{ "@type": "Brand", "name": "AC/DC" }
3. Node ou entité inline
Section intitulée « 3. Node ou entité inline »La distinction dépend de l’identité, pas de la profondeur d’imbrication :
- une entité imbriquée avec un
@iddevient son propre node dans@graph, tandis que son parent ne conserve que{ '@id': '...' }; - une entité imbriquée sans
@idreste inline dans son parent ; - un objet contenant uniquement
@idest déjà une référence et ne crée pas de node vide.
const organization = Organization({ '@id': '#organization', name: 'Acme',});
const website = WebSite({ '@id': '#website', name: 'Acme', url: 'https://example.com', publisher: organization,});
const graph = buildJsonLdGraph(website);// Organization est un node ; website.publisher vaut { '@id': '#organization' }.Les identités réutilisables comme Organization, Person, WebSite, WebPage,
Product, Service et Event sont des nodes potentiels courants. Les value objects
comme PostalAddress, GeoCoordinates, ContactPoint, Rating, AggregateRating et
NutritionInformation restent normalement inline, car ils ne possèdent généralement
pas d’identité propre. Il s’agit d’une convention de la bibliothèque pour produire des
graphes prévisibles, pas d’une règle Schema.org.
4. Sémantique des identifiants et des URL
Section intitulée « 4. Sémantique des identifiants et des URL »En cours de développement ou entre différents environnements (préproduction, production), il est courant d’écrire des identifiants relatifs comme #organization ou /a-propos#person.
Lorsque vous configurez baseUrl (ou la propriété site dans l’astro.config.mjs d’Astro), unschema-graph résout récursivement les valeurs @id relatives explicites. Les propriétés URL restent des chaînes URL : le collecteur ne déduit jamais leur sémantique depuis un nom comme url ou item.
Entrée @id |
baseUrl configurée |
Sortie dans @graph |
|---|---|---|
#organization |
https://mon-site.fr |
https://mon-site.fr/#organization |
#organization |
https://mon-site.fr/a-propos |
https://mon-site.fr/a-propos#organization |
#organization |
https://mon-site.fr/a-propos/ |
https://mon-site.fr/a-propos/#organization |
/a-propos |
https://mon-site.fr |
https://mon-site.fr/a-propos |
/a-propos#person |
https://mon-site.fr |
https://mon-site.fr/a-propos#person |
https://mon-site.fr/#organization |
https://mon-site.fr |
inchangé |
urn:example:foo |
https://mon-site.fr |
inchangé |
mailto:[email protected] |
https://mon-site.fr |
inchangé |
tel:+33123456789 |
https://mon-site.fr |
inchangé |
La résolution d’un fragment préserve la forme du chemin fournie par baseUrl : /a-propos et
/a-propos/ restent deux URL de document distinctes.
Les schémas intégrés distinguent ces valeurs explicitement : WebUrlSchema valide les
URL HTTP(S) absolues, RelativeOrAbsoluteUrlSchema valide les propriétés URL et les
relations d’entités normalisent les références en { '@id': valeur } avant la collecte.
Seules les propriétés @id explicites sont résolues. Les valeurs ordinaires comme
name, serviceType et description restent toujours intactes, même lorsqu’elles
ressemblent à un chemin, un fragment ou une URI.
5. Découverte, déduplication et fusion automatiques
Section intitulée « 5. Découverte, déduplication et fusion automatiques »Vous pouvez transmettre uniquement l’entité racine. Le collecteur parcourt récursivement
les relations objet et tableau, découvre chaque entité liée possédant un @id et émet
les dépendances avant le parent qui les référence.
const graph = buildJsonLdGraph(webpage);// Découvre WebPage → WebSite → Organization.Un même objet d’entité peut être réutilisé par plusieurs parents : il n’est enregistré
qu’une fois. Les relations cycliques entre entités identifiées se terminent sans boucle
et deviennent des références dans les deux directions. Les entités sans @id restent
inline et ne sont pas dédupliquées globalement.
Si plusieurs composants ou layouts déclarent des entités partageant le même @id résolu, unschema-graph les fusionne automatiquement en un nœud unique au lieu de créer des doublons.
// Dans le layout global :const baseOrg = Organization({ '@id': '#organization', name: 'Acme', url: 'https://mon-site.fr',});
// Dans la page locale :const richOrg = Organization({ '@id': '#organization', logo: 'https://mon-site.fr/logo.png', sameAs: ['https://twitter.com/acme'],});
// Passés ensemble au composant :<Schema items={[baseOrg, richOrg]} />Le graphe final ne contiendra qu’un seul nœud Organization combinant l’ensemble des propriétés : name, url, logo et sameAs.
La gestion des doublons est explicite et déterministe :
| Stratégie | Comportement |
|---|---|
merge (défaut) |
Combine les propriétés ; la dernière valeur conflictuelle gagne. |
first |
Conserve le premier node rencontré. |
last |
Le remplace par le dernier node rencontré. |
error |
Lève DuplicateEntityError pour tout doublon de @id. |
Utilisez onDiagnostic pour collecter les conflits de fusion et les références locales
cassées sous une forme exploitable par programme. Les fragments, chemins relatifs et
références de même origine sont vérifiés ; les références absolues externes et les
identifiants non HTTP sont conservés sans diagnostic.
const diagnostics: GraphDiagnostic[] = [];const graph = buildJsonLdGraph(items, { duplicateStrategy: 'merge', onDiagnostic: (diagnostic) => diagnostics.push(diagnostic),});Garanties de stabilité
Section intitulée « Garanties de stabilité »Les normalisations du Core ne modifient jamais les entités fournies, y compris leurs
tableaux et objets imbriqués. La collecte suit un ordre de découverte stable en
profondeur : une entrée et des options identiques produisent le même ordre de nodes et
la même sérialisation. Un document déjà normalisé peut être repassé dans
buildJsonLdGraph() sans dégrader sa structure ; les normalizers de références et d’ID
sont également idempotents.
{ "@type": "Organization", "@id": "https://mon-site.fr/#organization", "name": "Acme", "url": "https://mon-site.fr", "logo": { "@type": "ImageObject", "url": "https://mon-site.fr/logo.png" }, "sameAs": ["https://twitter.com/acme"]}6. Types Schema.org multiples
Section intitulée « 6. Types Schema.org multiples »Certaines entités relèvent de plusieurs types Schema.org à la fois (par exemple un Article qui est également un TechArticle ou une CreativeWork).
Utilisez le helper withAdditionalTypes() pour déclarer des types secondaires tout en conservant le type principal du builder :
import { Article, withAdditionalTypes } from '@unschema-graph/astro';
const techGuide = withAdditionalTypes( Article({ headline: 'Architecture TypeScript avancée', image: 'https://mon-site.fr/cover.jpg', datePublished: 'today', author: 'Ada Lovelace', }), ['TechArticle', 'CreativeWork']);Le champ @type résultant sera un tableau : ["Article", "TechArticle", "CreativeWork"].
Le helper conserve le type principal du builder en première position, supprime les
doublons dans l’ordre de première apparition et refuse les noms de type vides. Une
nouvelle application préserve ces invariants.
7. Sortie plate sans graphe (graph={false})
Section intitulée « 7. Sortie plate sans graphe (graph={false}) »Par défaut, <Schema /> enveloppe systématiquement vos entités dans un tableau @graph. Si vous ne rendez qu’une seule entité et exigez une structure plate sans @graph, désactivez l’option avec graph={false} :
<Schema item={article} graph={false} />Sortie générée :
{ "@context": "https://schema.org", "@type": "Article", "headline": "Architecture TypeScript avancée", ...}Étape suivante : comprendre quand intervient la validation et comment traiter ses échecs.