Valider un block.json contre son schéma officiel dans votre pipeline

Une agence avec laquelle nous collaborons a vu un bloc personnalisé disparaître complètement de l’inserteur de blocs après une mise à jour, sans le moindre message d’erreur visible dans l’interface. La cause, retrouvée après une heure de recherche : une virgule surnuméraire dans le fichier block.json, introduite lors d’un copier-coller rapide, rendait le JSON invalide. WordPress échouait silencieusement à enregistrer le bloc, sans avertissement explicite côté éditeur.

Ce genre d’incident, purement syntaxique, n’a rien à voir avec la logique du bloc lui-même — il aurait dû être intercepté avant même d’atteindre un environnement de recette, par une simple validation automatique dans le pipeline.

Étape 1 — Repérer le schéma officiel

WordPress publie et maintient un schéma JSON officiel pour la structure de block.json, disponible sur le dépôt GitHub du projet Gutenberg, à l’emplacement schemas/json/block.json. Ce schéma décrit précisément les clés attendues (apiVersion, name, title, attributes, supports…), leur type, et les valeurs autorisées.

Étape 2 — Installer un validateur de schéma JSON

Le paquet Node ajv-cli, ou plus simplement l’outil ajv utilisé par le script de validation officiel de WordPress lui-même, permet de valider un fichier contre un schéma en une seule commande :

npm install --save-dev ajv-cli ajv-formats

Étape 3 — Écrire le script de validation

Plutôt que de dupliquer le schéma officiel dans le dépôt du projet, où il finirait par se périmer, mieux vaut le récupérer directement lors de l’exécution du script, ou en garder une copie versionnée mise à jour manuellement à chaque montée de version majeure de WordPress :

#!/usr/bin/env bash
set -euo pipefail

npx ajv validate \
  -s schemas/block.schema.json \
  -d "src/blocks/*/block.json" \
  --spec=draft2020 \
  --strict=false

L’option --strict=false évite que des extensions légitimes de propriétés propres à un thème ou une extension spécifique ne soient rejetées à tort par une interprétation trop rigide du schéma.

Étape 4 — Intégrer la validation au pipeline

La vérification s’ajoute comme une étape distincte, exécutée avant les tests fonctionnels, de façon à échouer vite et à peu de frais si un fichier est mal formé :

name: Qualite

on: [pull_request]

jobs:
  valider-blocks:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: bash scripts/valider-block-json.sh

Étape 5 — Couvrir aussi les erreurs de contenu, pas seulement de syntaxe

Un JSON syntaxiquement valide peut malgré tout violer le schéma sur le fond : un apiVersion absent, un type d’attribut inconnu ("type": "texte" au lieu de "string"), ou une valeur textdomain incohérente avec celle déclarée dans l’en-tête du plugin. La validation par schéma intercepte ces cas tout aussi bien que les erreurs de syntaxe pure :

• Un attribut déclaré sans type ni source cohérents entre eux.
• Un apiVersion fixé à une valeur qui n’existe pas encore dans la version de WordPress ciblée par le projet.
• Une clé supports mal orthographiée, silencieusement ignorée par WordPress au lieu de faire échouer l’enregistrement.

Adapter la portée selon la maturité du projet

Sur un projet avec un seul bloc personnalisé, ce script peut sembler disproportionné. Il prend tout son sens à partir d’une dizaine de blocs maintenus par plusieurs développeurs, où une revue de code manuelle systématique du JSON devient peu fiable dans la durée.

Un fichier de configuration déclarative comme block.json mérite le même niveau de rigueur automatisée qu’un fichier de code : sa syntaxe ne se « teste » pas à l’exécution, elle échoue silencieusement.

Pour aller plus loin

Cette validation porte uniquement sur la déclaration du bloc, pas sur son comportement à l’exécution — la construction du rendu du bloc lui-même, ses attributs dynamiques ou sa logique JavaScript relèvent de tests fonctionnels distincts, hors du périmètre de cette vérification purement structurelle. Combinée à un script de linting JSON classique, cette étape supplémentaire ferme une porte d’entrée aux régressions les plus bêtes et les plus coûteuses en temps de diagnostic.