Migration vers la v1
unschema-graph 1.0 stabilise l’API publique, introduit les références relationnelles d’entités objets, applique une validation stricte Schema.org avec Zod et apporte une découverte déterministe du graphe.
Version 0.10.0 — Gel de l’API publique La version 0.10.0 fige le contrat d’API publique pour Core, Astro et Svelte avant
1.0.0-rc.1. Si vous effectuez une mise à niveau depuis0.9.xou des versions antérieures, ce guide détaille ce nettoyage et les évolutions architecturales.
0.9.x → 0.10.0 — Nettoyage de l’API publique
Section intitulée « 0.9.x → 0.10.0 — Nettoyage de l’API publique »La version 0.10.0 retire intentionnellement les exports racine accidentels et les primitives internes avant 1.0.0-rc.1.
1. createEntityRef supprimé au profit de entityRef
Section intitulée « 1. createEntityRef supprimé au profit de entityRef »L’alias déprécié createEntityRef a été supprimé. Utilisez entityRef à la place :
// Avant (déprécié) :import { createEntityRef } from '@unschema-graph/core';
// En 0.10.0+ :import { entityRef } from '@unschema-graph/core';2. Helpers internes retirés des exports racine
Section intitulée « 2. Helpers internes retirés des exports racine »Les primitives d’implémentation de bas niveau ont été retirées des barils racine pour protéger les évolutions internes :
resolveIdetresolveEntityIds: passezbaseUrlàbuildJsonLdGraph(entities, { baseUrl })au lieu de résoudre manuellement les identifiants.EntityIdSchema,isIdReference,IdObjectSchema,TypedEntitySchemaetEntityReferenceSchema: utilisez la validation des builders,entityRef()ouwithAdditionalProperties()plutôt que de valider directement des chaînes d’ID ou des formats de référence.normalizeZodIssuesetformatZodError: les erreurs de validation sont automatiquement formatées parSchemaValidationErrorlevée par les builders etvalidateSchema().- Les schémas internes communs (
WebUrlSchema,RelativeOrAbsoluteUrlSchema,SearchActionSchema,SpeakableSchema,ImageUrlOrObject,IsoDateSchema,IsoDurationSchema) ne font plus partie de l’API publique : utilisez les APIs haut niveau documentées commecreateSearchAction(),ImageObject(),formatIsoDate()etformatIsoDuration()lorsque cela s’applique.
Nouveautés et évolutions majeures en v1
Section intitulée « Nouveautés et évolutions majeures en v1 »1. Références relationnelles d’entités objets
Section intitulée « 1. Références relationnelles d’entités objets »Dans les versions pré-1.0 ou lors d’écritures manuelles, relier des entités imposait de synchroniser manuellement des identifiants textuels (ex. publisher: '#organization').
En v1, vous pouvez passer directement les objets entités retournés par les builders :
// Avant : uniquement des chaînes d'identificationconst article = Article({ headline: 'Bonjour le monde', publisher: '#organization',});
// En v1 : référence d'entité objet strictement typéeconst organization = Organization({ '@id': '#organization', name: 'Acme', url: 'https://mon-site.fr',});
const article = Article({ headline: 'Bonjour le monde', publisher: organization, // Typé et vérifié par TypeScript});Références textuelles explicites
Section intitulée « Références textuelles explicites »Une chaîne devient une référence @id uniquement lorsqu’elle ressemble explicitement à un
identifiant : fragment (#person), chemin (/personnes/ada#person, ./page, ../page) ou URI
absolue. Les noms simples sont développés uniquement par les relations qui définissent un type
de fallback, comme Article.author. Les relations génériques sans fallback rejettent les noms
simples :
ProfilePage({ mainEntity: '#person' }); // Référence explicite valideProfilePage({ mainEntity: Person({ name: 'Ada Lovelace' }) }); // Entité directe valideProfilePage({ mainEntity: 'Ada Lovelace' }); // Erreur de validation2. Découverte automatique du graphe
Section intitulée « 2. Découverte automatique du graphe »Vous n’avez plus besoin d’assembler manuellement toutes les entités reliées dans un tableau. Passer une entité racine explore récursivement toutes les entités référencées dotées d’un @id :
// En v1 : passer l'entité racine découvre automatiquement le site et l'organisationconst graph = buildJsonLdGraph(webpage, { baseUrl: 'https://mon-site.fr',});3. Typage strict Schema.org et propriétés additionnelles
Section intitulée « 3. Typage strict Schema.org et propriétés additionnelles »Les schémas intégrés constituent un sous-ensemble sélectionné, modélisé sur la baseline du vocabulaire Schema.org 30.1. Ils rejettent les propriétés absentes du schéma de bibliothèque concerné, sans prétendre couvrir tout Schema.org.
Si votre CMS ou API requiert des propriétés personnalisées :
- Utilisez
withAdditionalProperties:import { Article, withAdditionalProperties } from '@unschema-graph/core';const article = Article({ headline: 'Bonjour le monde' });const articlePersonnalise = withAdditionalProperties(article, { customField: 'value' }); - Ou définissez un nouveau type avec
defineSchema.
3.1. Corrections de vocabulaire Schema.org 30.1
Section intitulée « 3.1. Corrections de vocabulaire Schema.org 30.1 »Le contrat 0.9 remplace la propriété supplantée Restaurant.menu par hasMenu :
const restaurant = Restaurant({ name: 'Chez Pierre', address: '15 Boulevard Saint-Germain, Paris', hasMenu: '/menu',});servesCuisine et hasMenu sont acceptés par Restaurant, mais pas par les builders
génériques LocalBusiness, Store ou d’hébergement. FAQPage.questions et
WebSite.searchUrl restent des facilités d’entrée documentées : elles produisent
respectivement le vocabulaire courant mainEntity et potentialAction.
4. Diagnostics de graphe structurés (onDiagnostic)
Section intitulée « 4. Diagnostics de graphe structurés (onDiagnostic) »Au lieu d’erreurs silencieuses ou de fusions inattendues, la construction du graphe accepte un callback optionnel onDiagnostic pour inspecter les événements broken-reference et duplicate-conflict :
const graph = buildJsonLdGraph(webpage, { baseUrl: 'https://mon-site.fr', onDiagnostic(diagnostic) { console.warn(`[${diagnostic.code}] ${diagnostic.message}`); },});5. CLI d’audit en intégration continue (CI)
Section intitulée « 5. CLI d’audit en intégration continue (CI) »Le CLI d’audit est stabilisé pour une utilisation en CI avec le mode strict :
npx @unschema-graph/core audit dist --strictIl renvoie le code de sortie 0 en cas de succès et 1 si des références orphelines ou des blocs JSON-LD malformés sont détectés.
Checklist de migration pas-à-pas
Section intitulée « Checklist de migration pas-à-pas »- Mettez à jour les paquets ensemble : Passez
@unschema-graph/core,@unschema-graph/astroet@unschema-graph/svelteen^1.0.0. - Vérifiez les appels aux builders : Assurez-vous que les champs obligatoires sont bien renseignés d’après la documentation des builders Schema.org.
- Adoptez les références d’objets : Remplacez les chaînes d’identification par des références d’entités objets directes lorsque c’est pertinent.
- Configurez
baseUrl: Assurez-vous quebaseUrl(ousitedansastro.config.mjs) est configuré pour résoudre les fragments en URLs canoniques absolues. - Lancez le typecheck et l’audit : Exécutez
pnpm run typechecketnpx @unschema-graph/core audit dist --strictpour vérifier la résolution propre du graphe.