Aller au contenu

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.


Lorsqu’un robot d’indexation (comme Googlebot) analyse une page web, il doit comprendre comment les différentes entités s’articulent :

  • Cet Article est-il publié par cette Organization ?
  • Cette Person est-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.


Pour référencer une entité depuis une autre, assignez-lui un @id :

src/lib/schema.ts
import { Article, Organization, Person } from '@unschema-graph/core';
// 1. Organisation partagée avec identifiant fragment
const organization = Organization({
'@id': '#organization',
name: 'Acme Publishing',
url: 'https://mon-site.fr',
});
// 2. Auteur avec chemin et fragment
const 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 @id
const 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
});

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 :

  1. Il détecte que organization possède un @id.
  2. Il hisse organization comme nœud racine du tableau @graph.
  3. Il remplace automatiquement article.publisher par { "@id": "https://mon-site.fr/#organization" }.

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" }

La distinction dépend de l’identité, pas de la profondeur d’imbrication :

  • une entité imbriquée avec un @id devient son propre node dans @graph, tandis que son parent ne conserve que { '@id': '...' } ;
  • une entité imbriquée sans @id reste inline dans son parent ;
  • un objet contenant uniquement @id est 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.


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.

Exemple : Layout global + Page spécifique
// 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),
});

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.

Nœud fusionné
{
"@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"]
}

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 :

src/pages/docs/[slug].astro
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.


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.