null, leerer String, 0 oder fehlendes Feld: Bedeutungsänderungen in JSON-APIs vermeiden

Vier unterschiedliche Darstellungen

In einem JSON-Objekt sind null, "", 0 und eine ausgelassene Eigenschaft unterschiedliche Darstellungen. null ist ein spezieller JSON-Wert; laut IBM kann er für Felder verschiedener Typen verwendet werden, darunter Arrays, Objekte und numerische Typen ([IBM: Umgang mit null und leeren JSON-Arrays und -Objekten](https://www.ibm.com/docs/es/baw/25.0.x?topic=format-handling-json-null-empty-arrays-objects)). "" ist ein leerer String und 0 eine Zahl. Eine fehlende Eigenschaft bedeutet, dass der Schlüssel im Objekt nicht vorkommt. Wer all diese Fälle einfach als „leer“ bezeichnet, kann daher einen wichtigen Unterschied übersehen, wenn Daten geprüft oder umgewandelt werden.

Diese Objekte enthalten zum Beispiel nicht dieselbe Darstellung: {"notiz": null}, {"notiz": ""}, {"notiz": 0} und {}. Im letzten Objekt wird der Schlüssel „notiz“ nicht gesendet; in den ersten drei ist er enthalten, jeweils mit einem anderen Wert. Das Beispiel vergleicht die Form des Payloads, legt aber nicht fest, wie eine API die einzelnen Varianten behandelt.

Die Unterschiede im Payload bestimmen für sich genommen nicht das Ergebnis eines Vorgangs. Es gibt hier keine allgemeingültige Regel dafür, wie eine ausgelassene Eigenschaft, null, ein leerer String oder 0 interpretiert werden, insbesondere bei der Aktualisierung einer Ressource. Im Vertrag des konkreten Endpunkts muss stehen, was erwartet wird und wie diese Fälle ausgelegt werden. Leiten Sie aus einem einzelnen Wert weder die Absicht des Nutzers noch den Vorgang ab, den der Dienst ausführt.

Wenn Sie zunächst die Darstellungen voneinander trennen, lassen sich präzise Fragen stellen: Wurde der Wert nicht angegeben? Wurde eine leere Antwort übermittelt? Wurde ausdrücklich 0 angegeben? Diese Fragen beschreiben mögliche Absichten, aber keine automatische JSON-Semantik. Die Zuordnung zwischen Absicht, Darstellung und Ergebnis muss für das betreffende Feld und den konkreten Vorgang bestätigt werden.

• null: expliziter JSON-Wert.
• "": expliziter leerer String.
• 0: explizite Zahl.
• Fehlende Eigenschaft: Der Schlüssel ist nicht im Objekt enthalten.

Klären Sie die Bedeutung im API-Vertrag

Prüfen Sie für jede Eigenschaft die Dokumentation des Endpunkts und notieren Sie, welchen Typ sie akzeptiert, ob sie erforderlich ist und ob null zulässig ist. Bei einer Aktualisierung sollten Sie außerdem nachlesen, was der Vertrag über eine ausgelassene Eigenschaft, eine mit null gesendete Eigenschaft und einen leeren String festlegt. Übernehmen Sie nicht automatisch eine Regel von einem anderen Vorgang oder Feld: Auch wenn zwei Eigenschaften ähnlich heißen oder verwendet werden, müssen Sie die Dokumentation des konkreten Vorgangs prüfen.

Es ist hilfreich, zwischen Fragen zu unterscheiden, die der Vertrag beantwortet, und solchen, die noch offen sind. Wenn die Dokumentation nur besagt, dass ein Feld ein String ist, wird dadurch nicht unbedingt geklärt, was es bedeutet, das Feld wegzulassen oder einen leeren String zu senden. Zeigt sie lediglich ein Beispiel mit einem numerischen Wert, bestätigt das allein nicht, was bei 0 geschieht. Halten Sie solche Unklarheiten fest, statt Lücken mit Annahmen zu füllen; bitten Sie um Bestätigung oder führen Sie nach Möglichkeit einen kontrollierten Test durch.

Prüfen Sie außerdem, ob der Typ der Quelldaten dem erwarteten Typ entspricht. "0042" ist beispielsweise so geschrieben ein String, während 42 eine Zahl ist. Wandeln Sie beide nicht ohne bestätigte Regel in gleichwertige Werte um. Wird die führende Null entfernt, ändert sich die gesendete Darstellung. Ob sie erhalten, umgewandelt oder anders behandelt werden soll, muss sich aus der vereinbarten Anforderung und dem Vertrag ergeben, nicht aus einer ungeprüften automatischen Konvertierung.

Microsoft Learn beschreibt, wie sich in .NET System.Text.Json so konfigurieren lässt, dass Nullbarkeitsannotationen bei der Serialisierung und Deserialisierung berücksichtigt werden ([Microsoft Learn: Nullbarkeitsannotationen berücksichtigen](https://learn.microsoft.com/es-es/dotnet/standard/serialization/system-text-json/nullable-annotations)). Diese Referenz behandelt die .NET-Konfiguration; sie legt nicht für sich genommen fest, wie die Ziel-API den Wert interpretiert. Wenn Sie diese beiden Ebenen getrennt betrachten, verwechseln Sie nicht die Verarbeitung eines Werts im Code mit der Bedeutung, die der Dienst für das Payload dokumentiert.

• Dokumentieren Sie für jede Eigenschaft den erwarteten Typ, ob sie erforderlich ist und welche Regeln für null und das Weglassen festgelegt sind.
• Kennzeichnen Sie jedes Verhalten, das der Vertrag nicht definiert, als offen; ersetzen Sie es nicht durch eine Annahme.

Dokumentieren Sie das Mapping, bevor Sie Daten umwandeln

Erstellen Sie als allgemeine Integrationspraxis eine Tabelle, die den eingehenden Zustand mit der Geschäftsabsicht und der vorgesehenen JSON-Ausgabe verknüpft. Halten Sie bei einem Kommentarfeld beispielsweise eine nicht angegebene Antwort und eine leere Antwort getrennt fest. Unterscheiden Sie bei einer Menge eine leere Eingabe von der Zahl 0. Die Tabelle darf keine allgemeingültige Umwandlung vorgeben: Befolgen Sie die bestätigten Regeln für diese API und machen Sie kenntlich, was noch nicht definiert ist.

Eine Tabellenzeile kann die eingehenden Daten beschreiben, ohne automatisch festzulegen, was gesendet wird. Beispiel: Quellfeld „Kommentar“; empfangener Zustand „keine Antwort“; Absicht „noch zu bestätigen“; dokumentierte Regel „nicht angegeben“; Ausgabe „nicht definiert“. Eine weitere Zeile kann einen leeren String und eine dritte eine eingegebene Antwort erfassen. So erkennt eine Person, die das Mapping prüft, welche Entscheidungen getroffen werden müssen, bevor der Ablauf die Werte umwandelt.

Machen Sie ausdrücklich kenntlich, ob ein vorhandener Wert beibehalten, gelöscht oder auf 0 gesetzt werden soll, sofern diese Absichten für den Ablauf relevant sind. Die Begriffe können unterschiedliche Ziele beschreiben, bestimmen aber nicht, welche JSON-Darstellung jeweils passt. Wenn der Vertrag die geeignete Ausgabe festlegt, halten Sie sie fest. Ist das nicht der Fall, vermerken Sie die Einschränkung und vereinbaren Sie vor der Automatisierung eine Alternative.

Verknüpfen Sie das Mapping mit dem Feld und dem Endpunkt, für den es dokumentiert wurde. Eine für eine Eigenschaft notierte Regel darf nicht ohne Bestätigung für eine andere übernommen werden. Es ist auch hilfreich, Beispiele für Ein- und Ausgaben zusammen mit der Regel aufzubewahren, denn so wird sichtbar, ob eine Umwandlung den Typ ändert, einen Schlüssel auslässt oder einen expliziten Wert sendet.

• Praktische Vorlage: Quellfeld | empfangener Zustand | Absicht | dokumentierte Regel | gesendete Eigenschaft und Wert.
• Fügen Sie konkrete Beispiele der Quelldaten hinzu, damit andere das Mapping prüfen können.
• Trennen Sie bestätigte Entscheidungen von offenen Fragen.

Testen Sie repräsentative Fälle

Bereiten Sie als allgemeine Arbeitsempfehlung kleine Beispiele vor, die für jedes Feld die relevanten Zustände abdecken. Bei einem Kommentar könnten Sie ein Objekt mit "kommentar": null, eines mit "kommentar": "" und eines ohne diesen Schlüssel vergleichen. Testen Sie bei einer Menge null, 0 oder das Weglassen nur, wenn der Vertrag diese Fälle zulässt. Ergänzen Sie auch einen üblichen Wert, um den normalen Ablauf zu prüfen. Anhand dieser Beispiele lässt sich kontrollieren, welches Payload erstellt wird; sie ersetzen weder die Erklärung im Vertrag noch erlauben sie, eine nicht dokumentierte Wirkung anzunehmen.

Notieren Sie für jedes Beispiel die erwartete Ausgabe und warum sie gemäß der vereinbarten Regel als korrekt gilt. Können Sie diese Begründung nicht aufschreiben, weil der Vertrag den Fall nicht klärt, kennzeichnen Sie ihn als offen, statt eine Erwartung zu erfinden. Diese Trennung erleichtert die Prüfung: Eine Abweichung kann auf eine Datenumwandlung zurückzuführen sein oder darauf, dass noch nicht entschieden wurde, was der Fall bedeuten soll.

Prüfen Sie auch Werte, die durch eine Umwandlung verändert werden könnten, etwa einen String mit Leerzeichen oder eine Kennung mit führenden Nullen. Entscheiden Sie ausdrücklich anhand der vereinbarten Anforderung, ob solche Werte beibehalten oder umgewandelt werden. Behandeln Sie Strings wie "0042" weiterhin getrennt von Zahlen wie 42, sofern keine bestätigte Regel etwas anderes festlegt. Das Beispiel besagt nicht, dass ein Format immer richtig ist; es soll dazu anregen, zu prüfen, ob das erzeugte Format den Erwartungen entspricht.

Vergleichen Sie das erzeugte Payload mit dem erwarteten und prüfen Sie die Antwort der API. Dass das JSON syntaktisch gültig ist, beweist allein nicht, dass es dem Vertrag entspricht oder die gewünschte Wirkung erzielt. Weicht das beobachtete Ergebnis von der Vereinbarung ab, stellen Sie zunächst fest, welche Darstellung gesendet und welche Regel verwendet wurde, bevor Sie die Umwandlung ändern.

• Berücksichtigen Sie die Fälle normaler Wert, leer, null, 0 und ausgelassene Eigenschaft, sofern sie für das Feld relevant und zulässig sind.
• Halten Sie Strings wie "0042" und Zahlen wie 42 getrennt, sofern keine bestätigte Regel etwas anderes festlegt.
• Notieren Sie für jeden Fall die erwartete Ausgabe oder kennzeichnen Sie die Auslegung ausdrücklich als offen.

Validieren Sie Änderungen und führen Sie ein hilfreiches Änderungsprotokoll

Prüfen Sie als allgemeine Checkliste die JSON-Syntax, die Namen und Typen der Eigenschaften sowie die dokumentierten Regeln des Endpunkts. Das sind unterschiedliche Aspekte: Ein Payload kann gültiges JSON sein und trotzdem nicht dem Vertrag entsprechen. Bevor Sie einen automatisierten Versand ausweiten, vergleichen Sie die Ausgaben der vorbereiteten Fälle mit den erwarteten Ausgaben und prüfen Sie die erhaltenen Antworten. So lassen sich Unterschiede zwischen der Vereinbarung und dem tatsächlich erstellten oder empfangenen Inhalt erkennen, ohne einer Antwort eine Bedeutung zuzuschreiben, die der Vertrag nicht festlegt.

Wenn sich das Mapping oder die Definition des Endpunkts ändert, prüfen Sie die betreffenden Beispiele erneut und halten Sie fest, welche Regel geändert wurde. Bewahren Sie eine kurze Beschreibung des Falls, des gesendeten Werts, der erwarteten Ausgabe und des beobachteten Ergebnisses auf, und zwar mit genügend Details, um die Prüfung nachvollziehen zu können. Machen Sie dieses Protokoll nicht zu einer alternativen Quelle für die Semantik: Widerspricht eine Beobachtung der Dokumentation oder ist sie unklar, prüfen Sie den Vertrag und klären Sie die Regel.

Verfolgen Sie bei der Untersuchung einer Abweichung den Wert vom ursprünglichen Zustand bis zur endgültigen JSON-Darstellung. Prüfen Sie, ob der Schlüssel enthalten ist, welcher Wert gesendet wurde und welchen Typ er hat, und vergleichen Sie das Ergebnis mit dem vereinbarten Mapping. So lässt sich erkennen, an welcher Stelle die Beispiele voneinander abweichen, ohne anzunehmen, dass null, ein leerer String, 0 und das Weglassen austauschbar sind.

Dies sind allgemeine Arbeitsempfehlungen; sie legen nicht das Verhalten einer bestimmten API fest. Die endgültige Entscheidung über eine Eigenschaft muss sich auf den Vertrag des Endpunkts stützen. Löst der Vertrag einen benötigten Fall nicht, lassen Sie die Automatisierung dieses Falls offen, bis seine Auslegung bestätigt wurde.

• Prüfliste: Vertrag konsultiert, Mapping dokumentiert, relevante Fälle geprüft und Antworten kontrolliert.
• Stimmt das beobachtete Ergebnis nicht mit dem erwarteten überein, pausieren Sie die Automatisierung, bis die Regel geklärt und korrigiert ist.

Häufige Fragen