Null, vuoto, zero o campo assente: come evitare cambiamenti di significato nel JSON di un’API

Quattro rappresentazioni diverse

In un oggetto JSON, null, "", 0 e una proprietà omessa sono rappresentazioni diverse. null è un valore speciale di JSON; la documentazione IBM indica che può essere utilizzato con campi di tipi diversi, tra cui array, oggetti e tipi numerici ([IBM: Gestione di array e oggetti JSON nulli e vuoti](https://www.ibm.com/docs/es/baw/25.0.x?topic=format-handling-json-null-empty-arrays-objects)). "" è una stringa vuota, 0 è un numero e una proprietà assente è una chiave che non compare nell’oggetto.

Per esempio, {"nota": null}, {"nota": ""}, {"nota": 0} e {} non hanno la stessa forma. Nell’ultimo oggetto la chiave nota non è presente; negli altri tre è presente con valori diversi. Questi esempi mostrano le rappresentazioni, ma non stabiliscono cosa farà un’API con ciascuna.

Può essere utile chiedersi se il dato non è stato fornito, se è stata data una risposta vuota o se è stato indicato esplicitamente zero. Sono possibili intenzioni, non significati automatici di JSON: la corrispondenza tra intenzione, rappresentazione e risultato va verificata per il campo e l’operazione specifici.

• null: valore JSON esplicito.
• "": stringa vuota esplicita.
• 0: numero esplicito.
• Proprietà assente: la chiave non è inclusa nell’oggetto.

Verifica il significato nel contratto dell’API

Per ogni proprietà, consulta la documentazione dell’endpoint: controlla il tipo previsto, se il campo è obbligatorio e se ammette null. Per un aggiornamento, verifica anche cosa specifica il contratto su una proprietà omessa o inviata come null o stringa vuota. Non trasferire automaticamente la regola di un altro campo o di un’altra operazione.

Se la documentazione dice soltanto che un campo è una stringa, potrebbe non chiarire cosa significhino l’omissione o una stringa vuota. Allo stesso modo, un esempio con un valore numerico non basta a chiarire il caso zero. Segna ciò che resta da definire e chiedi conferma prima di automatizzare una trasformazione basata su un’ipotesi.

Controlla anche il tipo del dato di origine. "0042" è una stringa, mentre 42 è un numero: convertirli cambia la rappresentazione e può rimuovere gli zeri iniziali. Conservare o trasformare il valore deve dipendere dal requisito concordato.

In .NET, Microsoft Learn spiega come configurare System.Text.Json affinché rispetti le annotazioni di nullabilità durante la serializzazione e la deserializzazione ([Microsoft Learn: Rispettare le annotazioni di nullabilità](https://learn.microsoft.com/es-es/dotnet/standard/serialization/system-text-json/nullable-annotations)). Questa configurazione riguarda la gestione dei dati in .NET; non stabilisce come l’API di destinazione interpreterà il payload.

• Per ogni proprietà, annota il tipo previsto, se è obbligatoria e le regole documentate per null e per l’omissione.
• Tieni separate le regole documentate e le domande ancora aperte.

Documenta la mappatura dei dati

Crea una tabella che colleghi lo stato ricevuto, l’esigenza aziendale e l’output JSON previsto. Per un campo di commento, registra separatamente una risposta non fornita e una risposta vuota; per una quantità, distingui un input vuoto dal numero 0. La tabella deve riflettere le regole confermate per quell’API, non introdurre conversioni universali.

Una riga può descrivere il dato senza decidere automaticamente cosa inviare: campo di origine «commento»; stato ricevuto «nessuna risposta»; esigenza «da confermare»; regola documentata «non specificata»; output «non definito». Altre righe possono registrare una stringa vuota o una risposta scritta. Così le decisioni mancanti sono visibili prima che il flusso trasformi i valori.

Quando è rilevante, distingui tra conservare un dato esistente, cancellarlo e assegnargli zero. Questi obiettivi possono essere diversi, ma non determinano da soli la rappresentazione JSON: annota quella prevista dal contratto o concorda come procedere se non è specificata.

Associa la mappatura al campo e all’endpoint per cui è stata definita. Includi esempi di input e output per mostrare se una trasformazione cambia il tipo, omette una chiave o invia un valore esplicito.

• Modello pratico: campo di origine | stato ricevuto | esigenza | regola documentata | proprietà e valore inviati.
• Includi esempi concreti e separa le decisioni confermate dai punti da chiarire.

Prova casi rappresentativi

Prepara esempi che coprano gli stati pertinenti per ciascun campo. Per un commento, puoi confrontare un oggetto con "commento": null, uno con "commento": "" e uno senza la chiave. Per una quantità, considera null, 0 o l’omissione solo quando il contratto ammette questi casi. Aggiungi un valore abituale per confrontare il percorso normale.

Per ogni esempio, annota l’output previsto e la regola concordata che lo giustifica. Se non puoi definire l’esito perché la documentazione non chiarisce il caso, segnala che è da chiarire invece di inventare un risultato atteso.

Controlla anche valori che una trasformazione potrebbe modificare, come una stringa con spazi o un identificativo con zeri iniziali. Mantieni distinte stringhe come "0042" e numeri come 42, a meno che una regola concordata non indichi diversamente.

Confronta il payload generato con quello previsto e considera anche la risposta dell’API. Un JSON ben formato non dimostra da solo che il payload rispetti il contratto o produca l’esito desiderato.

• Includi i casi normale, vuoto, null, zero e proprietà omessa quando sono pertinenti al campo e consentiti.
• Per ogni caso, annota l’output previsto oppure indica che l’interpretazione è ancora da definire.

Convalida le modifiche e proteggi i dati

Verifica la sintassi JSON, i nomi e i tipi delle proprietà e le regole documentate dell’endpoint. Sono controlli distinti: un payload può essere JSON valido ma non corrispondere al contratto. Se il risultato osservato differisce da quello previsto, controlla quale chiave e quale valore sono stati inviati e quale regola di mappatura è stata applicata.

Quando aggiorni la mappatura o la documentazione dell’endpoint, ricontrolla gli esempi pertinenti e annota le modifiche. Se conservi esempi, payload o risultati per la revisione, minimizza i dati registrati e oscura prima della condivisione o pubblicazione dati personali, credenziali, token e altri contenuti sensibili. Non includere segreti o identificativi interni non necessari.

Queste sono indicazioni operative generali, non una definizione del comportamento di una particolare API. Per ogni proprietà, fai riferimento al contratto dell’endpoint e chiarisci i casi necessari che non sono specificati prima di automatizzarli.

• Lista di controllo: contratto consultato, mappatura documentata, casi pertinenti verificati e risultati esaminati.
• Prima di condividere esempi o risultati, rimuovi o oscura i dati sensibili non necessari.

Domande frequenti