JSON Lines oder JSON-Array: Datensätze für eine API vorbereiten, ohne Daten zu verlieren

JSON Lines und ein JSON-Array sind nicht dasselbe Format

JSON ist ein Textformat zur Darstellung strukturierter Daten. JSON Lines, auch JSONL genannt, organisiert diese Daten als Datensätze: Jede Zeile enthält einen eigenständigen JSON-Wert. Die Claris-Hilfe dokumentiert beispielsweise den Export von Datensätzen in eine JSON-Lines-Textdatei. Ein JSON-Array hingegen ist eine einzelne Struktur, die eine Folge von Werten in eckigen Klammern enthält. Der Unterschied ist wichtig, denn eine Datei kann als JSONL gültig sein, aber kein einzelnes gültiges JSON-Dokument für den Verbraucher darstellen, der sie einlesen soll.

Betrachte diese beiden Zeilen: „{"id":1,"name":"Ana"}“ und „{"id":2,"name":"Luis"}“. Zusammen stellen sie zwei Datensätze im JSON-Lines-Format dar. Das entsprechende Array lautet „[{"id":1,"name":"Ana"},{"id":2,"name":"Luis"}]“. Die Objekte und ihre Werte sind gleich; geändert hat sich die Struktur, die sie zusammenfasst. Es reicht nicht, die Dateiendung umzubenennen oder die Zeilen einfach aneinanderzureihen: Zuerst musst du feststellen, welches Format vorliegt und welches benötigt wird.

• JSON Lines: ein JSON-Wert pro Zeile; die Datei kann mehrere eigenständige Datensätze enthalten.
• JSON-Array: ein Dokument mit eckigen Klammern, das null oder mehr durch Kommas getrennte Werte enthält.

Bestätige die vom Endpunkt verlangte Struktur

Prüfe vor jeder Umwandlung die Dokumentation des konkreten Endpunkts und, falls vorhanden, dessen OpenAPI-Spezifikation. Suche nach einem Beispiel für den Anfrage-Body und prüfe, ob ein Array an der Wurzel, ein Objekt mit einer Datensatz-Eigenschaft, ein einzelnes Objekt oder eine andere Übermittlungsform erwartet wird. Leite die Struktur weder aus dem Namen des Endpunkts noch daraus ab, dass er mehrere Datensätze entgegennimmt: Der Vertrag für diesen Vorgang legt fest, welche Form zulässig ist.

Notiere auch die Vertragsanforderungen für jedes Feld: genaue Namen, Werttypen, Pflichtfelder und den Umgang mit zusätzlichen, nullen oder leeren Feldern. Ein Datensatz, der das Feld „id“ als Zahl enthält, ist nicht unbedingt gleichwertig mit einem, der es als Text übermittelt. Wenn die Dokumentation eine Regel nicht klärt, suche nach einem offiziellen Beispiel oder kläre die Erwartung mit dem zuständigen Team, bevor du den gesamten Stapel vorbereitest. Die äußere Dateistruktur zu ändern, behebt keine Unvereinbarkeit zwischen Feldern und Vertrag.

• Identifiziere den Endpunkt und das Anfragebeispiel für den tatsächlichen Vorgang.
• Halte die erwartete Wurzelstruktur und die Typen fest, bevor du die Datei änderst.
• Trenne bestätigte Regeln von offenen Fragen, die geklärt werden müssen.

Wandle eine Stichprobe um, ohne die Datensätze zu verändern

Arbeite zunächst mit einer kleinen Kopie, die repräsentative Datensätze und, falls vorhanden, Grenzfälle enthält. Wenn der Endpunkt ein Array aus Objekten verlangt, besteht die konzeptionelle Umwandlung darin, vor das erste Objekt eine öffnende eckige Klammer zu setzen, die Objekte durch Kommas zu trennen und das Array nach dem letzten Objekt zu schließen. Nach dem letzten Element darf kein Komma stehen. Das Ergebnis für zwei Datensätze wäre: „[{"id":1,"name":"Ana"},{"id":2,"name":"Luis"}]“. Dies veranschaulicht die Struktur und garantiert nicht, dass dieser konkrete Endpunkt diese Felder akzeptiert.

Behalte jeden Eigenschaftsnamen, Wert und Typ unverändert bei, sofern der Vertrag keine notwendige Umwandlung vorgibt. Wandle „0012“ nicht in 12 um, ändere keinen booleschen Wert in eine Zeichenkette und entferne keine Eigenschaften, nur weil sie wiederholt zu sein scheinen. Wenn du den Vorgang automatisierst, sollte der Prozess jede Zeile als JSON-Wert einlesen und eine Liste von Werten erstellen. Vermeide es, den Text mit improvisierten Ersetzungen von Zeilenumbrüchen oder Kommas zu bearbeiten. Vergleiche anschließend die Eingabe- und Ausgabestichprobe Feld für Feld.

• Bewahre das Original unverändert auf und wandle eine Kopie um.
• Teste zunächst mit wenigen Datensätzen und behalte die ursprünglichen Typen und Werte bei.
• Erzeuge Trennzeichen und Klammern mit einem Werkzeug, das die Struktur versteht, nicht mit blinden Ersetzungen.

Erkenne Syntaxfehler und unerwartete Datensätze

Ein häufiger Fehler besteht darin, Objekte aneinanderzureihen, ohne sie in ein Array umzuwandeln: „{"id":1}{"id":2}“. Auch wenn jeder Abschnitt wie ein Objekt aussieht, entspricht diese Folge nicht der Struktur des oben gezeigten Arrays. Ebenso können nach dem letzten Element ein Komma stehen, eine Klammer fehlen oder ein Anführungszeichen innerhalb einer Zeichenkette nicht maskiert sein. Sieh dir die Meldung des Parsers und die angegebene Stelle an. Wenn der Fehler auf eine Zeile oder Position verweist, prüfe den betreffenden Datensatz und auch das unmittelbar davorstehende Zeichen.

Prüfe leere Zeilen und Werte, die keine Objekte sind. Entscheide nicht intuitiv, dass eine leere Zeile verworfen werden kann: Lege diese Regel anhand der Quelle und des empfangenden Prozesses fest und dokumentiere verworfene Zeilen. Ebenso können „null“, eine Zeichenkette oder ein Array gültige JSON-Werte sein, sind aber keine Datensatzobjekte. Wenn der Vertrag Objekte erwartet, identifiziere solche Werte vor dem Senden, anstatt ihre Annahme zu erzwingen oder sie stillschweigend zu entfernen.

• Prüfe Klammern, Kommas, Anführungszeichen und Escape-Zeichen, wenn sich das Ergebnis nicht parsen lässt.
• Zähle und klassifiziere leere Zeilen sowie Werte, die keine Objekte sind.
• Verbirg Fehler nicht, indem du Datensätze ohne vereinbarte Regel verwirfst.

Validiere Datensätze, Zeichen und das vollständige Ergebnis

Vergleiche vor dem Senden die Zahl der Quelldatensätze mit der Zahl der Elemente im resultierenden Array. Wenn dokumentierte Ausnahmen vorliegen, halte fest, wie viele Zeilen ausgelassen wurden und warum. Andernfalls muss jede Abweichung untersucht werden. Prüfe den ersten und den letzten Datensatz sowie zusätzlich eine Stichprobe aus der Mitte. So lassen sich Abschneidungen am Anfang oder Ende und Fehler finden, die nur einen Teil der Datei betreffen.

Validiere, dass sich das Ergebnis als einzelnes JSON-Dokument parsen lässt und die Wurzel die verlangte Form hat. Prüfe in repräsentativen Fällen Feldnamen, Typen, Nullwerte, leere Zeichenketten und Sonderzeichen: Anführungszeichen, umgekehrte Schrägstriche, Zeilenumbrüche oder Zeichen mit Akzenten. Bestätige auch die von Werkzeug oder Endpunkt erwartete Kodierung; ändere sie nicht, ohne die Anforderung zu prüfen. Schlägt die Validierung fehl, bewahre die Originaldatei auf, behebe die Ursache und führe die Prüfungen für das gesamte Ergebnis erneut aus.

• Vergleiche die Datensatzanzahl und erkläre jede Abweichung.
• Prüfe den ersten und letzten Datensatz sowie Stichproben aus der Mitte.
• Validiere Syntax, Wurzel, Felder, Typen, Zeichen und die erwartete Kodierung.

Entscheide, wann JSON Lines beibehalten werden sollte

Eine Umwandlung ist nicht immer besser. Wenn der Verbraucher JSON Lines unterstützt und die Verarbeitung Datensatz für Datensatz erfolgt, kann es sinnvoll sein, dieses Format beizubehalten. So lässt sich möglicherweise ein einziges großes Array vermeiden, und die ursprüngliche zeilenweise Organisation bleibt erhalten. Die Entscheidung hängt davon ab, was der empfangende Prozess akzeptiert und wie Fehler behandelt werden. Nimm nicht an, dass ein Endpunkt JSONL unterstützt, nur weil er JSON akzeptiert, oder dass die Annahme eines Arrays auch einzelne Datensätze einschließt.

Ein Array kann erforderlich sein, wenn der Vertrag eine einzelne Liste im Body einer Anfrage verlangt. Prüfe in diesem Fall auch die Stapelgröße und die Strategie zur Meldung von Teilfehlern, sofern die Dokumentation dazu Angaben macht. Ist unklar, ob alles zusammen oder in mehreren Gruppen gesendet werden sollte, teste mit einer kontrollierten Stichprobe und prüfe die Antwort, bevor du das Volumen erhöhst. Bewahre Originaldaten, umgewandelte Daten und Testergebnisse getrennt auf.

• Behalte JSON Lines bei, wenn der Verbraucher das Format unterstützt und eine Verarbeitung pro Datensatz geeignet ist.
• Verwende ein Array, wenn der Vertrag diese Struktur verlangt.
• Prüfe Größe und Fehlerbehandlung, bevor du einen vollständigen Stapel sendest.

Checkliste und Werkzeuge

Prüfe vor Abschluss der Vorbereitung, ob du das Quellformat identifiziert, den Vertrag bestätigt und eine unveränderte Kopie aufbewahrt hast. Teste eine Stichprobe mit mehr als einem Datensatz, validiere die resultierende Struktur und vergleiche Felder und Anzahlen. Notiere, wie du mit leeren Zeilen, fehlerhaften Datensätzen und unerwarteten Werten umgegangen bist. Wenn die Stichprobe die Prüfung besteht, wende dasselbe Verfahren auf die gesamte Datei an und wiederhole die Validierung. Gehe nicht davon aus, dass der endgültige Stapel korrekt ist, nur weil eine kleine Stichprobe fehlerfrei war.

Wenn du ein Konvertierungswerkzeug in Betracht ziehst, prüfe getrennt dessen Ein- und Ausgabeformate, ob es JSON Lines von herkömmlichem JSON unterscheidet, wie es leere Zeilen und ungültige Datensätze behandelt und wie es Fehler meldet. Teste es mit Fällen, die Sonderzeichen und Werte unterschiedlicher Typen enthalten. Apification bietet Integrationen von Cloud und Diensten über REST API, OpenAPI, Webhooks, iFrame und JavaScript sowie einen geführten Assistenten zur Verarbeitung von Daten und anderen Dateien. Diese Beschreibung bestätigt keine spezielle Umwandlung von JSON Lines: Prüfe, ob das benötigte Format unterstützt wird, bevor du dich auf eine bestimmte Funktion verlässt.

• Vertrag bestätigt und Originaldatei gesichert.
• Stichprobe validiert und Anzahlen verglichen.
• Fehler, leere Zeilen und Sonderzeichen geprüft.
• Konkrete Funktionen des Konvertierungswerkzeugs vor der Nutzung überprüft.

Häufige Fragen