Null, chaîne vide, zéro ou champ absent : éviter les changements de sens en JSON pour une API

Quatre représentations distinctes

Dans un objet JSON, null, "", 0 et une propriété omise sont des représentations distinctes. null est une valeur spéciale de JSON ; la documentation d’IBM indique qu’elle peut être utilisée avec des champs de différents types, notamment des tableaux, des objets et des types numériques ([IBM : Gestion des tableaux et objets JSON nuls et vides](https://www.ibm.com/docs/es/baw/25.0.x?topic=format-handling-json-null-empty-arrays-objects)). "" est une chaîne vide et 0 est un nombre. Une propriété absente signifie que la clé ne figure pas dans l’objet.

Par exemple, ces objets ne contiennent pas la même représentation : {"note": null}, {"note": ""}, {"note": 0} et {}. Dans le dernier objet, la clé note n’est pas envoyée ; dans les trois premiers, elle apparaît avec une valeur différente. Ces exemples comparent les payloads, mais ne définissent pas l’effet qu’aura chacune de ces variantes pour une API : il faut vérifier le contrat du point de terminaison concerné.

Décrire l’un de ces cas comme simplement « vide » peut masquer une différence importante lors de l’examen ou de la transformation des données. Distinguer les représentations aide à poser des questions précises : la donnée n’a-t-elle pas été fournie ? Une réponse vide a-t-elle été fournie ? Zéro a-t-il été indiqué explicitement ? Ce sont des intentions possibles, pas une sémantique automatique de JSON.

• null : valeur JSON explicite.
• "" : chaîne vide explicite.
• 0 : nombre explicite.
• Propriété absente : la clé ne figure pas dans l’objet.

Confirmer la signification dans le contrat de l’API

Pour chaque propriété, consultez la documentation du point de terminaison et notez le type accepté, si elle est obligatoire et si elle peut prendre la valeur null. Pour une mise à jour, vérifiez aussi ce que le contrat indique au sujet d’une propriété omise ou envoyée avec la valeur null ou une chaîne vide. Ne transposez pas automatiquement une règle d’une autre opération ou d’un autre champ.

Le contrat peut ne pas préciser tous les cas. Par exemple, indiquer qu’un champ est une chaîne ne clarifie pas nécessairement le sens de son omission ou de l’envoi d’une chaîne vide. Consignez les incertitudes et demandez une confirmation plutôt que de les résoudre par supposition.

Vérifiez également que le type de la donnée source correspond à celui attendu. Par exemple, "0042" est une chaîne telle qu’elle est écrite, tandis que 42 est un nombre. Ne les convertissez pas l’un en l’autre sans règle confirmée, notamment si la transformation risque de supprimer un zéro initial.

Dans .NET, Microsoft Learn explique comment configurer System.Text.Json pour respecter les annotations de nullabilité lors de la sérialisation et de la désérialisation ([Microsoft Learn : Respecter les annotations de nullabilité](https://learn.microsoft.com/es-es/dotnet/standard/serialization/system-text-json/nullable-annotations)). Cette référence concerne la configuration de .NET ; elle ne définit pas l’interprétation du payload par l’API destinataire.

• Pour chaque propriété, consignez le type attendu, son caractère obligatoire et les règles documentées concernant null et l’omission.
• Notez les comportements que le contrat ne précise pas, au lieu de les supposer.

Documenter le mappage avant de transformer les données

Un tableau de mappage peut relier l’état reçu à l’intention métier et à la sortie JSON prévue. Pour un champ de commentaire, consignez séparément l’absence de réponse et une réponse vide. Pour une quantité, distinguez une entrée vide du nombre 0. La sortie prévue doit refléter les règles confirmées pour le point de terminaison ; les cas non définis restent à clarifier.

Une ligne peut décrire la donnée sans décider automatiquement de ce qui sera envoyé : champ source « commentaire » ; état reçu « aucune réponse » ; intention « à confirmer » ; règle documentée « non précisée » ; sortie « non définie ». Une autre ligne peut consigner une chaîne vide et une troisième une réponse rédigée. Cette présentation rend visibles les décisions qui restent à prendre.

Si les notions de conserver une donnée existante, de l’effacer et de lui attribuer zéro sont pertinentes pour le flux, consignez-les séparément. Elles décrivent des objectifs qui peuvent différer, mais ne déterminent pas à elles seules la représentation JSON correspondante.

Associez chaque règle au champ et au point de terminaison pour lesquels elle a été documentée. Des exemples d’entrée et de sortie permettent de voir si une transformation change le type, omet une clé ou envoie une valeur explicite.

• Modèle pratique : champ source | état reçu | intention | règle documentée | propriété et valeur envoyées.
• Ajoutez des exemples de données source et distinguez les décisions confirmées des questions en suspens.

Comparer des cas représentatifs

Pour examiner la représentation produite, comparez de petits exemples couvrant les états pertinents pour chaque champ. Pour un commentaire, vous pouvez comparer un objet contenant "commentaire": null, un autre contenant "commentaire": "" et un troisième sans cette clé. Pour une quantité, n’incluez null, 0 ou l’omission que si le contrat autorise ces cas. Une valeur habituelle peut servir de point de comparaison.

Pour chaque exemple, consignez la sortie prévue et la règle convenue qui la justifie. Si le contrat ne précise pas le cas, indiquez que son interprétation reste à clarifier plutôt que d’inventer un résultat attendu.

Les exemples peuvent aussi rendre visibles des différences de représentation : une chaîne contenant des espaces, "0042" et le nombre 42 ne sont pas écrits de la même manière. Déterminez, selon l’exigence convenue, si une valeur doit être conservée ou transformée.

Comparez le payload généré à celui qui était prévu et examinez la réponse de l’API. Un JSON bien formé ne prouve pas à lui seul que le payload respecte le contrat ni qu’il produira l’effet souhaité.

• Comparez les cas normal, vide, null, zéro et propriété omise lorsque le champ et le contrat le permettent.
• Distinguez les chaînes, comme "0042", des nombres, comme 42.
• Pour chaque cas, notez la sortie prévue ou précisez que son interprétation reste à clarifier.

Vérifier les changements et garder une trace utile

Lors de l’examen d’un payload, vérifiez sa syntaxe JSON, les noms et les types des propriétés, puis comparez les valeurs aux règles documentées du point de terminaison. Un payload peut être un JSON valide sans respecter le contrat. Examinez également la réponse reçue, sans lui attribuer un sens que le contrat ne définit pas.

Si le mappage ou la définition du point de terminaison change, réexaminez les exemples concernés et consignez la règle modifiée. Une note indiquant le cas, la valeur envoyée, la sortie prévue et le résultat observé peut aider à comprendre les écarts. Si une observation contredit la documentation ou reste incomprise, clarifiez la règle avant de modifier la transformation.

Pour examiner l’origine d’un écart, suivez la donnée depuis son état source jusqu’à sa représentation JSON finale. Vérifiez si la clé a été incluse, quelle valeur a été envoyée et quel est son type, puis comparez le résultat au mappage consigné.

• Liste de vérification : contrat consulté, mappage consigné, cas pertinents comparés et réponse examinée.
• Si un cas nécessaire reste sans interprétation confirmée, laissez sa transformation en suspens.

Questions fréquentes