Schémas personnalisés

Lorsque votre projet nécessite des types Schema.org non couverts par le catalogue intégré (tels que PodcastEpisode, MedicalWebPage ou TechArticle), utilisez defineSchema() pour créer vos propres builders avec le même niveau de validation et d’intégration au @graph.

1. Créer un builder personnalisé

Appelez defineSchema() en transmettant le nom du type @type Schema.org et un schéma Zod :

import { defineSchema } from '@unschema-graph/core';
import { z } from 'zod';

export const PodcastEpisode = defineSchema(
  'PodcastEpisode',
  z.object({
    name: z.string().min(1),
    url: z.string().url(),
    duration: z.string().optional(),
    partOfSeries: z.string().optional(),
  })
);

Votre builder personnalisé s’utilise désormais exactement comme les builders de base :

import { PodcastEpisode } from '../../lib/schemas/podcast';

const episode = PodcastEpisode({
  '@id': '#episode-42',
  name: 'Créer avec Astro & unschema-graph',
  url: 'https://mon-site.fr/podcast/episode-42',
  duration: 'PT45M',
  partOfSeries: '#podcast-series',
});

Chaque builder personnalisé :

Injecte automatiquement le type Schema.org ("PodcastEpisode").
Accepte un identifiant optionnel @id.
Rejette les clés inconnues pour bloquer les fautes de frappe.
Respecte le mode de sévérité onError (throw, warn, silent).
Expose .schema, .entityType et .safeParse().

2. Composer avec les schémas existants

Tous les schémas Zod du catalogue sont exportés avec le suffixe *Schema (PersonSchema, OrganizationSchema, ImageObjectSchema, IsoDateSchema). Vous pouvez les imbriquer directement dans vos schémas :

import {
  defineSchema,
  PersonSchema,
  ImageObjectSchema,
} from '@unschema-graph/core';
import { z } from 'zod';

export const PodcastSeries = defineSchema(
  'PodcastSeries',
  z.object({
    name: z.string(),
    description: z.string(),
    author: PersonSchema,
    image: ImageObjectSchema.optional(),
  })
);