Null versus fehlende Felder in JSON-APIs

Worum es geht

In einer Antwort können "middleName": null, ein fehlender Schlüssel middleName und "middleName": "" alle „kein zweiter Vorname“ bedeuten, aber sie können auch „unbekannt“, „nicht angefragt“ und „leer“ bedeuten. In einer Anfrage können dieselben drei „nicht ändern“, „Wert löschen“ und „auf leer setzen“ bedeuten. Standards beziehen dazu Position. JSON Merge Patch (RFC 7396, zitiert) gibt null in einem Patch eine besondere Bedeutung, nämlich das Entfernen des Members aus dem Ziel, weshalb der RFC das Format für Dokumente, die explizite null-Werte verwenden, als ungeeignet bezeichnet. ProtoJSON (zitiert) weist Serialisierer an, null nicht auszugeben, und Parser, null als gültigen Wert für jedes Feld zu akzeptieren, der das Feld ungesetzt lässt, als wäre es abwesend. Googles JSON Style Guide (zitiert) rät, Eigenschaften wegzulassen, deren Wert leer oder null ist, ausser es gibt einen starken semantischen Grund für ihr Vorhandensein.

Warum es wichtig ist

Clients, die in Sprachen mit optionalen Typen geschrieben sind (Go-Pointer, Rust Option, TypeScript undefined versus null), bilden diese Fälle unterschiedlich ab. Ein Update-Endpunkt, der „weggelassen“ nicht von „null“ unterscheiden kann, löscht Felder entweder versehentlich oder kann sie überhaupt nicht löschen.

So wird es angewendet

• Pro API festlegen, ob Antworten für nicht gesetzte optionale Felder null ausgeben oder sie weglassen, dies dokumentieren und nicht mischen. Weglassen hält die Payloads klein und passt zu ProtoJSON; explizites null hält die Feldliste für tabellarische Konsumenten stabil.
• Für Teilaktualisierungen Merge-Patch-Semantik verwenden: abwesend bedeutet unverändert, null bedeutet löschen, ein Wert bedeutet setzen. Alternativ eine Feldmaske akzeptieren (updateMask=name,email), die die Felder auflistet, die die Anfrage setzen will, was auch ein Löschen ohne null erlaubt.
• Bei feldselektierten Antworten null nie für „nicht angefragt“ verwenden; das Feld weglassen.
• Leere Sammlungen als [] zurückgeben, nicht als null oder abwesend, damit Clients ohne Prüfungen iterieren können.
• Im Schema Optionalität (required) getrennt von Nullbarkeit (type: ["string", "null"]) ausdrücken; ein Feld kann erforderlich und dennoch nullbar sein, oder optional und dennoch nie null.
• Den Standardwert angeben, den der Server anwendet, wenn ein Feld beim Erstellen fehlt.

Stolpersteine

Deserialisierer, die einen fehlenden Schlüssel in einen Standardwert (0, false, leerer String) verwandeln, bevor die Anwendung ihn sieht, sodass „nicht gesetzt“ verloren geht. PATCH-Bodys, die durch Serialisieren eines ganzen clientseitigen Objekts erzeugt werden und dadurch jedes Feld erneut senden und gleichzeitige Änderungen überschreiben. SDKs, die „explizit null“ nicht darstellen können und daher ein Feld nicht löschen können.