Skip to content
AMN Docs

[Nom du Schéma]

[Nom du Schéma]

Documentation technique

Type de ressource : Schéma Sanity (Document / Object / Block)
Fichier source : sanity-studio/schemas/[filename].ts
Statut : [Actif / Déprécié / En développement]
Slice : [Numéro de la tranche verticale]
Version : 1.0

1. Vue d’ensemble (DOC)

1.1. Description

[Description concise du rôle de ce schéma dans l’architecture du site]

1.2. Objectif

  • [Objectif principal : ce que le schéma permet de modéliser]
  • [Bénéfice pour l’architecture ou les utilisateurs]

1.3. Cas d’usage

  • [Cas d’usage principal]
  • [Cas d’usage secondaire si applicable]

1.4. Relations avec d’autres schémas

Relation Schéma Type Description
Dépend de [Nom] [Référence/Composition] [Description]
Utilisé par [Nom] [Référence] [Description]

2. Structure des données (DOC)

2.1. Champs principaux

Nom du champ Type Obligatoire Description Validation
fieldName string ✅ [Description] [Règles de validation]
slug slug ✅ [Description] source: 'title'
status string ✅ [Description] Options: draft, published, archived

2.2. Champs SEO (si applicable)

Nom du champ Type Obligatoire Description Fallback
seo.metaTitle string ❌ Meta title pour SEO title
seo.metaDescription text ❌ Meta description excerpt
seo.ogImage image ❌ Image Open Graph mainImage

2.3. Champs de contenu riche (si applicable)

Nom du champ Type Description
body array Contenu Portable Text (blocs + spans)
pageBuilder array Liste de blocs PageBuilder (hero, features, etc.)

3. Contrats d’Entrée/Sortie (SPEC)

3.1. Inputs (création/modification)

Champ Type Validation Description
title string Rule.required() Titre obligatoire
slug slug source: 'title' Généré automatiquement depuis le titre

3.2. Outputs (structure du document)

Champ Type Description
_id string ID unique du document
_type string Type du document
_createdAt string Date de création
_updatedAt string Date de dernière modification

3.3. États du document

État Description Transition
draft Document en brouillon → published
published Document publié → archived
archived Document archivé → published

4. Implémentation (CODE)

4.1. Code du schéma

sanity-studio/schemas/[filename].ts
import { defineField, defineType } from 'sanity';


export default defineType({
  name: '[schemaName]',
  title: '[Titre lisible]',
  type: 'document', // ou 'object', 'block'
  fields: [
    defineField({
      name: 'title',
      title: 'Titre',
      type: 'string',
      validation: (Rule) => Rule.required(),
    }),
    defineField({
      name: 'slug',
      title: 'Slug',
      type: 'slug',
      options: { source: 'title' },
      validation: (Rule) => Rule.required(),
    }),
    // ... autres champs
  ],
  preview: {
    select: {
      title: 'title',
      subtitle: 'publishedAt',
      media: 'mainImage',
    },
  },
});

4.2. Requêtes GROQ associées

Requête principale (listing)

*[_type == "[schemaName]" && status == "published"] {
  _id,
  title,
  slug,
  publishedAt,
  mainImage,
  excerpt
} | order(publishedAt desc)

Requête détaillée (page unitaire)

*[_type == "[schemaName]" && slug.current == $slug][0] {
  ...,
  author->{name, image},
  categories[]->{title, slug}
}

4.3. Types TypeScript (génération automatique)

// src/types/sanity.d.ts (généré via sanity-typegen)
export type [SchemaName] = {
  _id: string;
  _type: '[schemaName]';
  title: string;
  slug: { _type: 'slug'; current: string };
  publishedAt: string;
  status: 'draft' | 'published' | 'archived';
  mainImage?: ImageAsset;
  excerpt?: string;
  seo?: SeoObject;
};

5. Tests attendus (TEST)

5.1. Tests unitaires

Scénario Description Résultat attendu
Validation du titre Créer un document sans titre Erreur de validation
Génération du slug Créer un document avec titre Slug généré automatiquement
Publication Changer le statut de draft à published Document passe en published

5.2. Tests d’intégration

Scénario Dépendances Description Résultat attendu
Consommation Astro Route Astro Récupération des données via GROQ Données typées correctement
Indexation Pagefind Build Astro Indexation du contenu généré Contenu indexé et searchable

5.3. Tests E2E

Scénario Parcours utilisateur Description Résultat attendu
Création → Publication Sanity Studio → Build → Site Créer et publier un document Document visible sur le site

6. Intégration (INTÉG)

6.1. Intégration avec les composants

Composant Type Rôle Méthode d’intégration
Route Astro L2 Rendu du contenu Requête GROQ via getSanityClient()
Pagefind L2 Indexation Indexation du HTML généré
Webhook L3 Déclenchement rebuild Événement publish

6.2. Points d’attention

  • Le schéma doit être compatible avec sanity-typegen
  • Les requêtes GROQ doivent utiliser les projections explicites
  • Le statut published doit être filtré en production

6.3. Vérification de cohérence

  • Le schéma ne casse aucun schéma existant
  • Les requêtes GROQ retournent les données attendues
  • Les types TypeScript sont générés correctement
  • Les tests E2E passent

7. Sécurité

7.1. Mécanismes de sécurité

  • ✅ Les documents draft ne sont accessibles qu’en mode preview
  • ✅ Les permissions Sanity sont configurées par rôle
  • ✅ Les tokens API ont les permissions minimales nécessaires

7.2. Validation des entrées

  • ✅ Les champs obligatoires sont validés côté Sanity
  • ✅ Les slugs sont uniques et valides
  • ✅ Les statuts suivent le cycle draft → published → archived

8. Performance et limites

8.1. Limites Sanity

Limite Valeur Stratégie d’optimisation
Taille du document 16 MB Éviter les champs trop volumineux
Profondeur des références 10 niveaux Limiter les références imbriquées

8.2. Optimisations appliquées

  • ✅ Utilisation de projections GROQ pour réduire la taille des réponses
  • ✅ Mise en cache CDN pour les requêtes en production

9. Débogage et troubleshooting

9.1. Problèmes courants

Symptôme Cause probable Solution
Schéma non visible dans Studio Cache du navigateur Vider le cache et rafraîchir
Types TypeScript incorrects Schéma modifié sans régénération Exécuter sanity typegen generate
Requête GROQ vide Filtre incorrect Vérifier la syntaxe GROQ

9.2. Commandes de debug

Terminal window
# Extraire le schéma depuis Sanity
npx sanity schema extract


# Générer les types TypeScript
npx sanity typegen generate

10. Bonnes pratiques

10.1. Architecture

  • ✅ Toujours utiliser des types générés par sanity-typegen
  • ✅ Centraliser les requêtes GROQ dans src/lib/queries.ts
  • ✅ Documenter les champs et leurs validations

10.2. Code

  • ✅ Utiliser defineField pour chaque champ
  • ✅ Configurer le preview pour une meilleure UX dans Studio
  • ✅ Utiliser des validations appropriées

10.3. Maintenance

  • ✅ Mettre à jour ce fichier lors de toute modification du schéma
  • ✅ Régénérer les types après modification
  • ✅ Tester les requêtes GROQ après modification

11. Évolutions et roadmap

11.1. Améliorations planifiées

  • [Évolution 1]
  • [Évolution 2]

11.2. Limitations connues

  • ❌ [Limitation 1]
  • ❌ [Limitation 2]

12. Ressources liées

  • Documentation Sanity : [Lien vers docs officielles]
  • DAT L1 : §4 - Modélisation et Schémas des Données
  • Schémas dépendants : [Liste]
  • Pages Astro consommatrices : [Liste des fichiers .astro]

13. Historique des modifications

Date Version Description Auteur
YYYY-MM-DD 1.0 Création initiale [Nom]
Switch to normal mode

Contents

Built with StarlightPowered by Cloudflare