# « Notion : validation, migration et récupération, souvent confondues »

> Trois mécanismes internes du parser de blocs se confondent souvent quand un contenu ancien pose problème. Voici ce que chacun fait réellement, et où s'arrête sa responsabilité.

- Auteur : Clément Hadrot
- Publié le : 2026-02-25
- Mis à jour le : 2026-02-25
- Catégorie : Blocs Gutenberg
- URL : https://wpmoderne.dev.wordpress-developpement.fr/blocs/notion-validation-migration-recuperation-blocs/

## L’essentiel

- La validation compare, elle ne corrige jamais rien elle-même
- La migration transforme des attributs d'un ancien format vers un nouveau
- La récupération est une action manuelle proposée à l'utilisateur

« Le bloc a été migré automatiquement » entend-on parfois d'un client après un incident de contenu, alors qu'en réalité rien n'a été migré du tout, seulement invalidé. Cette confusion entre validation, migration et récupération revient souvent, y compris chez des développeurs expérimentés qui manipulent ces mécanismes sans toujours distinguer précisément où s'arrête la responsabilité de chacun.

## La validation : un simple comparateur, jamais un correcteur

La validation de bloc consiste à recalculer le rendu attendu à partir des attributs actuels (via la fonction `save` active) et à le comparer au HTML réellement stocké dans `post_content`. Si les deux diffèrent au-delà d'une tolérance de normalisation d'espaces, le bloc est marqué invalide. C'est tout ce que fait la validation : elle constate un écart, elle ne modifie jamais le contenu stocké, et elle ne sait absolument rien de la cause de cet écart, qu'il s'agisse d'un vrai changement de structure ou d'une simple différence d'encodage de caractères.

## La migration : transformer un ancien format vers le nouveau

La migration intervient dans le cadre du tableau `deprecated` de `registerBlockType`. Chaque entrée de ce tableau décrit un ancien schéma d'attributs et un ancien `save`, avec optionnellement une fonction `migrate` qui transforme les anciennes valeurs d'attributs vers le nouveau format actif. La migration ne s'exécute que lorsque l'éditeur détermine, via `isEligible` ou par correspondance de structure, qu'une entrée de déprécation correspond au contenu stocké.

```
const v1 = {
  attributes: { titre: { type: 'string', source: 'text', selector: 'h3' } },
  migrate({ titre }) {
    return { titre: titre.toUpperCase(), soulignement: false };
  },
  save({ attributes }) { /* ancien rendu */ },
};
```

> L'essentiel à retenir : La validation compare, elle ne corrige jamais rien elle-même ; La migration transforme des attributs d'un ancien format vers un nouveau ; La récupération est une action manuelle proposée à l'utilisateur

Un point souvent mal compris : la migration ne s'exécute qu'au moment où l'éditeur charge et affiche ce bloc précis dans son interface. Un article jamais rouvert dans l'éditeur depuis la mise à jour du bloc conserve indéfiniment son ancien format d'attributs en base de données, migré uniquement « à la volée » en mémoire à chaque chargement, jusqu'à ce que l'article soit resauvegardé.

## La récupération : une action manuelle, jamais automatique

La récupération (« Attempt Block Recovery » dans l'interface, aussi appelée « Tenter la récupération ») est le bouton proposé à l'utilisateur lorsque l'éditeur ne parvient à faire correspondre le contenu invalide à aucune entrée de déprécation connue. Contrairement à la migration, elle n'est jamais déclenchée automatiquement : c'est un choix explicite de l'utilisateur, qui accepte que l'éditeur retente de parser le contenu stocké avec la structure actuelle, au prix potentiel d'une perte de mise en forme si les deux structures divergent trop.

## Où ces trois mécanismes s'articulent dans le temps

| Mécanisme | Déclenchement | Modifie le contenu stocké ? |
| --- | --- | --- |
| Validation | Automatique, à chaque ouverture du bloc | Non, seulement un constat |
| Migration | Automatique, si une entrée deprecated correspond | En mémoire seulement, jusqu'à resauvegarde |
| Récupération | Manuelle, choix explicite de l'utilisateur | Oui, dès acceptation |

## Pièges fréquents

- Croire qu'un bloc « invalidé » a perdu son contenu : le contenu original reste intact en base tant qu'aucune sauvegarde n'a eu lieu après une récupération acceptée.
- Écrire une fonction `migrate` sans jamais la tester sur un contenu réel invalidé, en supposant à tort qu'elle s'exécute systématiquement au chargement de n'importe quel article.
- Confondre l'absence d'entrée `deprecated` correspondante avec un bug de migration : sans entrée correspondante, il n'y a simplement rien à migrer, seulement une proposition de récupération.

> Ces trois mécanismes ne se remplacent jamais l'un l'autre : la validation constate, la migration transforme un format connu, la récupération est un pari accepté par un humain.

## Ce que cette notion ne couvre pas en détail

La syntaxe complète du tableau `deprecated`, ses champs `isEligible`, et la mécanique fine de résolution parmi plusieurs entrées candidates ont déjà été traitées en profondeur ailleurs. Cet article se limite à distinguer les trois concepts entre eux, pas à détailler chacun exhaustivement.

## Pour aller plus loin

Comprendre cette distinction change la façon d'aborder un incident : face à un bloc invalidé en masse, la première question n'est jamais « pourquoi la migration a-t-elle échoué », mais « la validation a-t-elle raison de signaler un écart, et cet écart correspond-il à une perte réelle de donnée ou à une simple différence de sérialisation ».