Ce que le schéma show_in_rest vérifie vraiment sur une métadonnée exposée

« The register_meta() function now accepts a schema for the show_in_rest argument, used to validate and sanitize the meta value when exposed in the REST API. » Cette phrase, tirée de la documentation officielle de WordPress sur l’API des métadonnées, résume en une ligne un mécanisme souvent mal compris : le schéma déclaré au moment d’enregistrer une métadonnée n’est pas qu’un détail de documentation destiné aux clients de l’API. Il alimente une validation réellement exécutée à chaque requête REST.

Cette notion mérite d’être clarifiée, car elle évite un piège courant : dupliquer une logique de validation déjà couverte par le schéma, ou pire, croire qu’aucune validation n’a lieu et laisser passer des valeurs incohérentes jusqu’en base de données.

Ce que fait réellement l’argument show_in_rest

Quand register_meta() reçoit un argument show_in_rest sous forme de tableau contenant une clé schema, WordPress ne se contente pas d’exposer la métadonnée dans les réponses de l’API REST. Il utilise ce schéma pour valider toute valeur reçue en écriture via l’API, à l’aide de la fonction interne rest_validate_value_from_schema().

register_meta(
    'post',
    'nombre_places_disponibles',
    array(
        'type'         => 'integer',
        'single'       => true,
        'show_in_rest' => array(
            'schema' => array(
                'type'    => 'integer',
                'minimum' => 0,
                'maximum' => 500,
            ),
        ),
    )
);

Avec cette déclaration, une requête REST qui tenterait d’écrire la valeur -5 ou 10000 dans nombre_places_disponibles échoue avant même d’atteindre la logique métier de l’extension, avec une erreur de validation standard renvoyée par l’API. Le schéma sert donc à la fois de documentation pour les intégrateurs et de garde-fou effectif contre les valeurs incohérentes.

Fonctionnement interne : où intervient la validation

Ce mécanisme s’appuie sur le même moteur de validation de schéma que celui utilisé pour valider les arguments des routes REST déclarées via register_rest_route(). Concrètement, WordPress compare la valeur reçue au schéma déclaré, vérifie le type, les bornes numériques éventuelles, la présence dans une liste de valeurs autorisées via enum, et rejette la requête si la valeur ne correspond pas.

Ce contrôle intervient au moment où l’API REST traite la métadonnée exposée, pas au moment où elle est enregistrée par un code interne à l’extension via update_post_meta() directement. Une valeur incohérente écrite directement en PHP, sans passer par l’API REST, ne sera pas bloquée par ce schéma : la validation liée à show_in_rest ne protège que le point d’entrée REST, pas l’ensemble des chemins d’écriture possibles.

La différence essentielle avec sanitize_callback

Le schéma déclaré dans show_in_rest valide, il ne nettoie pas. Une valeur qui respecte le schéma mais contient malgré tout des caractères indésirables, par exemple une chaîne contenant des balises HTML alors que le champ attend un texte simple, passera la validation de schéma sans problème si le type déclaré est string. C’est le rôle de l’argument sanitize_callback, distinct, de nettoyer effectivement la valeur avant son enregistrement.

register_meta(
    'post',
    'nom_affiche',
    array(
        'type'              => 'string',
        'single'            => true,
        'sanitize_callback' => 'sanitize_text_field',
        'show_in_rest'      => array(
            'schema' => array(
                'type'      => 'string',
                'maxLength' => 100,
            ),
        ),
    )
);

Dans cet exemple, le schéma vérifie la longueur maximale, tandis que sanitize_callback retire les balises HTML éventuelles et normalise les espaces. Les deux mécanismes se complètent, mais aucun ne remplace l’autre.

Cas d’usage concrets

• Restreindre une métadonnée de statut à une liste fermée de valeurs, via enum dans le schéma, sans coder cette liste une seconde fois dans un contrôleur REST personnalisé.
• Borner une métadonnée numérique, comme une quantité ou une note, sans écrire de condition manuelle dans un rappel de validation séparé.
• Documenter automatiquement la structure attendue d’une métadonnée pour les intégrateurs consultant le schéma exposé par l’API.

Piège fréquent : oublier que la validation ne couvre que la REST

L’erreur la plus commune consiste à croire que déclarer un schéma via show_in_rest sécurise entièrement une métadonnée, y compris contre des écritures effectuées ailleurs dans le code de l’extension elle-même. Ce n’est pas le cas : toute écriture directe via update_post_meta(), dans un traitement interne ou une tâche planifiée, contourne totalement ce schéma. La validation reste spécifique au point d’entrée REST.

Un schéma REST protège la porte d’entrée de l’API, pas l’ensemble de la maison : le code interne de l’extension reste responsable de sa propre rigueur.

En résumé

Le schéma déclaré via show_in_rest lors d’un register_meta() n’est pas un simple élément de documentation : il alimente une validation réellement appliquée par WordPress sur les requêtes REST. Comprendre cette mécanique évite de dupliquer une validation déjà couverte, tout en gardant à l’esprit qu’elle ne dispense jamais d’un sanitize_callback pour le nettoyage effectif de la valeur.