Aller au contenu

Validation & Diagnostics

Chaque builder d’unschema-graph applique deux niveaux de protection : le typage statique TypeScript pour l’autocomplétion dans votre éditeur, et une validation stricte à l’exécution avec Zod pour les données dynamiques et externes.

unschema-graph valide les contraintes implémentées par ses schémas. La bibliothèque ne prétend pas valider l’intégralité du vocabulaire Schema.org ni garantir l’éligibilité à un résultat enrichi d’un moteur de recherche.

La bibliothèque sépare trois préoccupations :

Niveau Ce qui est contrôlé
Syntaxe JSON-LD et composition du graphe Structure sérialisable, identités, références et règles de graphe implémentées par le Core.
Modèle Schema.org implémenté Types et propriétés pris en charge par un builder générique comme Article.
Profil consommateur Règles supplémentaires implémentées pour un consommateur, comme GoogleArticle.

Un builder générique ne rejette pas une entité uniquement parce qu’un champ exigé par Google manque. Activez explicitement un profil consommateur lorsque c’est votre cible :

import { Article, GoogleArticle } from '@unschema-graph/core';
const articleGenerique = Article({ headline: 'Article Schema.org' });
const articleProfilGoogle = GoogleArticle({
headline: 'Profil Article',
image: '/couverture.jpg',
datePublished: '2026-10-01',
author: 'Ada Lovelace',
});

GoogleArticleSchema et GoogleRecipeSchema sont exportés pour la composition directe. Leurs règles décrivent les profils actuellement implémentés par la bibliothèque ; les respecter ne promet ni indexation ni affichage d’un résultat enrichi par Google.


Contrairement aux interfaces TypeScript qui disparaissent à la compilation, unschema-graph valide vos données au moment de l’exécution grâce à Zod.

Les schémas sont stricts : les clés inconnues ou mal orthographiées sont immédiatement rejetées :

src/pages/article.astro
import { Article } from '@unschema-graph/astro';
const article = Article({
headline: 'Bien démarrer avec unschema-graph',
image: '/cover.jpg',
datePublished: 'today',
author: 'Ada Lovelace',
// ❌ Faute de frappe interceptée par TypeScript et Zod :
datePublised: 'today',
});

Lorsqu’une anomalie survient, unschema-graph met en forme l’erreur Zod en un diagnostic lisible indiquant le chemin précis de la propriété et une suggestion de correction.


Vous pouvez piloter la réaction du moteur en cas de schéma invalide :

Mode Comportement en cas d’erreur Usage recommandé
throw Lève une exception SchemaValidationError détaillée Builds CI / Production (empêche de déployer un SEO erroné)
warn Affiche un avertissement clair en console et renvoie null Développement local (n’interrompt pas le travail sur la page)
silent Renvoie null sans aucun message en console Pipelines personnalisés

Dans votre configuration Astro (astro.config.mjs) :

astro.config.mjs
import { defineConfig } from 'astro/config';
import { schemaGraph } from '@unschema-graph/astro';
export default defineConfig({
integrations: [
schemaGraph({
// Lève une exception en production, avertit en dev :
onError: process.env.NODE_ENV === 'production' ? 'throw' : 'warn',
}),
],
});

Vous pouvez également surcharger le mode de sévérité sur un builder particulier via son second argument :

const produitOptionnel = Product(donneesExternes, { onError: 'warn' });

Lorsque vous consommez des APIs externes, des webhooks de CMS headless ou des contenus soumis par des utilisateurs, utilisez .safeParse() pour éviter toute interruption d’exécution :

src/lib/cms-loader.ts
import { Article } from '@unschema-graph/core';
const result = Article.safeParse(donneesCms);
if (result.success) {
// result.data est strictement typé en ArticleOutput
console.log('Article valide :', result.data.headline);
} else {
// result.error est une instance de SchemaValidationError
console.warn('Schéma CMS invalide :', result.error.message);
console.table(result.error.details);
}

Lorsque result.success vaut false, le tableau result.error.details fournit des informations actionnables :

interface IssueDetail {
code: string; // ex. 'unrecognized_keys', 'invalid_type'
path: string; // ex. 'Article.headline', 'Article.author.name'
message: string; // Description compréhensible de l'anomalie
expected?: string; // Type ou contrainte attendue
received?: string; // Valeur ou type reçu
suggestion?: string; // Suggestion en cas de faute de frappe
}

Les relations d’entités ajoutent une aide spécialisée. Par exemple, passer un Product comme WebSite.publisher produit :

Property "WebSite.publisher"
Expected: Organization | Person | @id reference
Received: Product
Suggestion: Pass Organization(...), Person(...), '#organization', or { '@id': '#organization' }.

Les mêmes valeurs path, expected, received et suggestion sont disponibles dans error.details. Le terminal, la CI, la toolbar de développement Astro et de futurs outils IDE peuvent ainsi exploiter une forme de diagnostic stable et unique.


Lorsque Schema.org intègre de nouvelles propriétés expérimentales non encore présentes dans la bibliothèque standard, utilisez withAdditionalProperties() :

src/pages/product.astro
import { Product, withAdditionalProperties } from '@unschema-graph/astro';
const baseProduct = Product({
name: 'Clavier mécanique',
image: 'https://mon-site.fr/clavier.jpg',
});
// Attache des propriétés personnalisées après validation
const product = withAdditionalProperties(baseProduct, {
color: 'Bleu nuit',
switchType: 'Tactile silencieux',
});

La validation indique si les données respectent un builder. Elle ne contrôle pas le HTML produit par votre application et ne garantit aucune éligibilité sur une plateforme externe. Exécutez l’audit du HTML compilé après le build de production.

Étape suivante : comprendre la normalisation des dates et durées.