Champ nul contre champ absent dans les API JSON

Ce que c'est

Dans une réponse, "middleName": null, l'absence de clé middleName, et "middleName": "" peuvent tous signifier « pas de second prénom », mais peuvent aussi signifier « inconnu », « non demandé » et « vide ». Dans une requête, les trois mêmes cas peuvent signifier « ne pas changer », « effacer la valeur » et « définir comme vide ». Les standards prennent position. JSON Merge Patch (RFC 7396, citée) donne à null, dans un patch, un sens particulier : la suppression du membre de la cible, raison pour laquelle la RFC qualifie le format d'inadapté aux documents qui utilisent des valeurs null explicites. ProtoJSON (citée) indique aux sérialiseurs de ne pas émettre null, et aux analyseurs d'accepter null comme valeur légale pour tout champ, laissant ce champ non défini, comme s'il était absent. Le JSON Style Guide de Google (cité) conseille de retirer les propriétés dont la valeur est vide ou nulle, sauf raison sémantique forte de les conserver.

Pourquoi c'est important

Les clients écrits dans des langages à types optionnels (pointeurs Go, Option de Rust, undefined contre null en TypeScript) traduisent ces cas différemment. Un point de terminaison de mise à jour incapable de distinguer « omis » de « null » efface des champs par accident, ou ne peut jamais les effacer.

Comment l'appliquer

• Décider par API si les réponses émettent null pour les champs optionnels non définis ou les omettent, le documenter, et ne pas mélanger les deux approches. L'omission garde les charges utiles petites et correspond à ProtoJSON ; le null explicite garde la liste des champs stable pour les consommateurs tabulaires.
• Pour les mises à jour partielles, utiliser la sémantique du merge-patch : absent signifie inchangé, null signifie effacer, une valeur signifie définir. Ou bien accepter un masque de champs (updateMask=name,email) listant les champs que la requête entend définir, ce qui permet aussi d'effacer sans null.
• Ne jamais utiliser null pour « non demandé » dans des réponses à sélection de champs ; omettre le champ.
• Renvoyer les collections vides sous la forme [], jamais null ni absentes, afin que les clients itèrent sans vérification.
• Dans le schéma, exprimer l'optionalité (required) séparément de la nullabilité (type: ["string", "null"]) ; un champ peut être requis mais nullable, ou optionnel mais jamais null.
• Indiquer la valeur par défaut que le serveur applique quand un champ est absent à la création.

Pièges

Des désérialiseurs qui transforment une clé manquante en valeur par défaut (0, false, chaîne vide) avant que l'application ne la voie, si bien que « non défini » est perdu. Des corps PATCH produits en sérialisant tout un objet côté client, qui renvoient chaque champ et écrasent des changements concurrents. Des SDK incapables de représenter « explicitement null » et donc incapables d'effacer un champ.