JSON Toolkit

JSON-Reparatur-Leitfaden: Kaputte LLM-Ausgaben retten, ohne das Vertrauen zu verlieren

Fazit: LLM-Ausgaben in Markdown-Zäunen, mit trailing commas und Python-Literalen übersteht kein strikter Parser — ebenso wenig wie manuell editierte Konfigurationen ohne Anführungszeichen. Dieser Leitfaden zieht die echte Grenze zwischen neun reparierbaren Fehlerklassen und vier unheilbaren, erklärt, warum Zustandsmaschinen Regex schlagen, und liefert eine produktionsreife Parse-Kette mit jsonrepair und json-repair.

Fortgeschritten~6 Min. LesezeitVeröffentlicht 2026-11-08Aktualisiert 2026-11-08
Diagramm der JSON-Reparatur-Pipeline: Zaun-Entfernung, Anführungszeichen-Normalisierung, Klammerausgleich, finale Validierung

Ein strikter Parser gibt kaputtem Input nichts: eine Fehlermeldung, eine Zeilennummer — und nicht ein einziges Byte deiner Daten. Ein Reparateur existiert, um „totales Versagen“ in „gut genug zum Laufen“ zu verwandeln — aber was er ergänzt, ist immer nur eine bestmögliche Vermutung über die Absicht, niemals eine Garantie für Korrektheit.

Eins: Wo kaputtes JSON herkommt

Reparatur ist keine Magie — schau dir zuerst den Input an. In echten Projekten stammt nicht-standardkonformes JSON aus drei konzentrierten Quellen:

  1. LLM-Ausgaben. Sprachmodelle erzeugen Text Token für Token; sie führen keinen JSON-Serializer aus. Selbst bei der Aufforderung „nur JSON“ wickelt das Modell die Ausgabe in einen ```json-Zaun, stellt „Hier sind deine Daten“ davor, lässt ein trailing comma zurück oder stoppt mitten im Objekt, weil das Token-Limit erreicht ist.
  2. Copy-Paste aus anderen Sprachen. Ein per console.log ausgegebenes JavaScript-Objekt trägt einfache Anführungszeichen und Schlüssel ohne Anführungszeichen; ein Python-Dict druckt sich als True/False/None. Diese „JSON-artigen“ Strings explodieren beim ersten Kontakt mit JSON.parse.
  3. JSON5/JSONC-Konfigurationen. Dateien wie tsconfig erlauben legal Kommentare und trailing commas. So eine Datei in einen strikten Parser gepastet — und er lehnt das ganze Dokument ab.

Die drei Quellen verlangen unterschiedliche Behandlung, aber Reparatoren decken alle ab — vorausgesetzt, der Fehler liegt auf ihrer deklarierten Liste reparabler Fälle.

Zwei: Neun Fehlerklassen, die ein Reparateur wirklich behebt

Kombiniert man die jsonrepair-Dokumentation mit den Capability-Listen der Tool-Anbieter, lassen sich automatisch reparierbare Fehler in neun Klassen einteilen:

Klasse Kaputter Input Repariert
Trailing comma [1, 2, 3,] [1, 2, 3]
Einfache / typografische Anführungszeichen {'a': 'b'}、{"a": "b"} {"a": "b"}
Schlüssel ohne Anführungszeichen {name: 'Ada'} {"name": "Ada"}
Kommentare {"a": 1 /* Hinweis */} {"a": 1}
Python-Literale {"ok": True, "v": None} {"ok": true, "v": null}
Markdown-Zäune ```json {...} ``` {...}
Fehlende Kommas [1 2] [1, 2]
Unge schlossene Klammern / Strings {"a": [1, 2 {"a": [1, 2]}
JSONP / String-Konkatenation cb({...})、"x" + "y" {...}、"xy"

Gemeinsam ist diesen neun: die Daten sind alle da; kaputt ist nur die Syntax. Der Reparateur justiert Interpunktion und Verpackung, ohne einen einzigen Wert anzufassen. Ein paar Details verdienen besondere Aufmerksamkeit:

  • Zahlen mit führender Null werden zu Strings. 007 wird zu "007" repariert, nicht zu 7, damit keine Ziffer verloren geht. Ist das Feld wirklich ein Textcode, ist das korrekt; ist es eine echte Zahl, entscheidest du.
  • Nackte Wörter werden zu Strings. NaN lässt sich nicht zu einer Zahl reparieren — manche Implementierungen geben "NaN" aus, andere null. Das Verhalten unterscheidet sich zwischen Bibliotheken; teste deine, bevor du sie in eine Pipeline hängst.
  • Valider Input läuft unverändert durch. Jeder seriöse Reparateur fährt zuerst einen Fast-Path mit striktem Parsen. Valides JSON gelangt nie in die Reparatur-Logik — ein „gutes Dokument kaputt reparieren“ ist unmöglich.

Drei: Vier Dinge, die ein Reparateur nicht reparieren kann

Die Grenze auf der anderen Seite ist genauso explizit. Erwarte keine Reparatur für:

  1. HTML-Fehlerseiten oder reinen Prosatext. Es gibt keinerlei JSON-Struktur im Input, und kein Tool kann Daten aus dem Nichts erschaffen.
  2. Syntaktisch valide, aber falsche Daten. Ein falsch geschriebener Schlüssel, ein Wert am falschen Platz, eine Zahl als String gespeichert — das sind semantische Probleme, die jeder Parser, Reparatoren eingeschlossen, kommentarlos durchlässt.
  3. Daten, die durch Abbruch verloren gingen. Autovervollständigung macht aus {"items": [{"id": 1}, {"na valides JSON, aber der Wert von name kehrt nie zurück. Du bekommst ein „valides, aber unvollständiges“ Objekt. In der Produktion prüfe stopReason === "max_tokens", bevor du zwischen Ergänzen und Wiederholen entscheidest.
  4. Doppelte Schlüssel und mehrdeutige Strukturen. Welcher von zwei identischen Schlüsseln gewinnt, hängt von der Parser-Implementierung ab. Verantwortungsvolle Reparatoren bieten einen Strict-Modus, der einen Fehler wirft, statt stillschweigend einen zu wählen.

Ein Satz fasst die Vertrauensgrenze zusammen: Reparatur ist eine bestmögliche Vermutung, keine Korrektheitsgarantie. Unverifizierte Reparatur-Ergebnisse an Downstream durchzureichen, tauscht einen lauten Syntaxfehler gegen einen stillen Datenfehler.

Vier: Zwei Implementierungsschulen — eine URL entscheidet den Streit

Reparatoren kommen in zwei Geschmacksrichtungen, und der Unterschied zeigt sich bei einem ganz bestimmten Input.

Die Regex-Ersetzungsschule wendet globales Suchen-und-Ersetzen auf kaputte Muster an. Betrachte diesen Input:

{"url": "http://example.com", 'note': 'fine'}

Ein Regex, der einfache in doppelte Anführungszeichen umwandelt, zerkaut auch den URL-Inhalt; ein Kommentar-Cleanup-Regex, der jedes // löscht, halbiert http://. Innerhalb eines Strings und außerhalb einer Struktur sehen die Zeichen identisch aus — Regex kann sie nicht unterscheiden.

Die Schule des zeichenweisen Zustandsautomaten verfolgt einen Parse-Zustand: innerhalb eines Strings mit doppelten Anführungszeichen, in einem mit einfachen, in einem Zeilenkommentar, in einem Blockkommentar oder wartend auf einen Wert. Sieht er ', fragt er zuerst „bin ich in einem String?“ und entscheidet erst dann, das Anführungszeichen zu konvertieren oder zu überspringen. http://example.com sitzt in einem String mit doppelten Anführungszeichen — der Zustandsautomat weiß, dass das // Daten sind, kein Kommentar, und bewahrt sie. jsonrepair und json-healer gehören zu dieser Schule, und das Community-Mantra „ein Reparateur ist kein Suchen-und-Ersetzen“ meint genau das.

Die komplette Reihenfolge der Reparatur-Pipeline (wie von der devkits-Implementierung offengelegt) lohnt ebenfalls einen Blick: Zäune entfernen → typografische Anführungszeichen normalisieren → ersten balancierten Block extrahieren → Kommentare entfernen → nackte Schlüssel in Anführungszeichen setzen → trailing commas entfernen → Literale konvertieren → mit JSON.stringify neu serialisieren. Diese finale Reserialisierung ist der Schlüsselschritt: was auch immer die früheren Stufen taten, die Ausgabe wird aus dem Parse-Ergebnis neu erzeugt, sodass jeder strikte Downstream-Parser sie schluckt.

Fünf: In Code anbinden — eine sequentielle Parse-Kette

Wenn du Reparatur in Code bindest, zählt die Reihenfolge mehr als die Bibliothekswahl. Nach den von json2toon und aijsonmedic veröffentlichten Mustern sollte die Sequenz sein: Abbruchprüfung → JSON-Span-Extraktion → striktes Parse → Reparatur-Fallback → Schema-Validierung.

import { jsonrepair } from "jsonrepair";

export function parseModelJson(text, stopReason) {
  if (stopReason === "max_tokens") {
    // Reparierter, abgebrochener Output bleibt lückenhaft — wiederhole den Aufruf
    throw new Error("Truncated output: retry with a higher max_tokens");
  }
  // JSON-Span extrahieren: LLMs plappern gern davor und danach
  const start = text.search(/[[{]/);
  const end = Math.max(text.lastIndexOf("}"), text.lastIndexOf("]"));
  const candidate = start >= 0 && end > start ? text.slice(start, end + 1) : text;
  try {
    return JSON.parse(candidate);   // Fast-Path für validen Input
  } catch {
    return JSON.parse(jsonrepair(candidate));  // Reparatur-Fallback
  }
}

Auf der Python-Seite bietet das Paket json-repair (über 4.700 Sterne) loads(), das direkt ein Objekt zurückgibt:

from json_repair import repair_json
import json

broken = "{name: 'Ada', tags: ['x',], active: True}"
data = json.loads(repair_json(broken))
# {'name': 'Ada', 'tags': ['x'], 'active': True}

Zwei Engineering-Details:

  • Stapel ausrichten. Wenn Frontend und Backend beide reparieren, wähle Implementierungen mit geteilter Semantik — Python json-repair und seinen TypeScript-Port @yarmu/json-repair, oder jsonmend, dessen Python- und JS-Versionen denselben Konformitätskorpus aus 485 Fällen bestehen. Sonst repariert derselbe Output clientseitig zu A und serverseitig zu B, und das Debugging wird zur Qual.
  • Reparatur-Logging einschalten. @yarmu/json-repair mit logging: true liefert ein Array jeder Reparatur-Operation. Ein plötzlicher Anstieg der Reparaturen bedeutet meist, dass Prompt oder Modellversion sich geändert haben — ein früheres Signal als jeder Fehlerbericht.

Ein Schritt nach der Reparatur ist nicht verhandelbar: Schema-Validierung. Syntaktisch valide heißt nicht brauchbar. Fehlende Felder, falsche Typen und unerwartete Schlüssel fängt das Schema. Der Contract-Testing-Ansatz passt direkt hierher; siehe unseren Leitfaden zu JSON-Schema-Contract-Testing.

Sechs: Präventions-Checkliste — die billigste Reparatur ist die, die du nie brauchst

Reparatur ist der Fallback. Weniger kaputtes JSON an der Quelle ist der eigentliche Sieg, in Prioritätsreihenfolge:

  1. Structured Outputs (json_schema-Modus). Die Dekodierung ist durch das Schema eingeschränkt, ein trailing comma kann schlicht nicht generiert werden. OpenAIs Strict-Modus versagt bei etwa 0,1 % — der Preis sind harte Anforderungen wie additionalProperties: false.
  2. JSON-Modus (json_object). Garantiert nur syntaktische Validität — nicht die Form — und Abbruch durchs Token-Limit passiert weiterhin.
  3. Explizite Anweisungen. Auf Endpoints ohne JSON-Modus senkt die Formulierung „keine Zäune, keine Kommentare, keine trailing commas, nur das Objekt ausgeben“ die Fehlerrate um 70–80 %.
  4. Temperature senken, Token-Limit erhöhen. Ersteres reduziert das Abdriften in Prosa; letzteres reduziert Abbrüche.
  5. Wiederholen mit angehängtem Fehler. Wenn die Validierung scheitert, hänge den kaputten Output plus „JSON-Pfad + Fehlermeldung“ an die Konversation und frage erneut. Mit präzisen Fehlern korrigieren sich Modelle meist selbst.

In der Praxis deckt die Schichtung „Structured Outputs + Reparatur-Fallback + Schema-Validierung“ praktisch jedes Szenario ab.

Sieben: Arbeitsteilung — Dialektkonvertierung ist keine Reparatur

Im Werkzeugkasten dieser Seite gibt es zwei Ziele, die unterschiedliche Segmente dieser Pipeline abdecken:

  • Dialekt-Probleme (Kommentare, einfache Anführungszeichen, trailing commas) gehen direkt zum JSON5-Konverter. Die Konvertierung JSON5 ↔ Standard-JSON deckt genau diese drei Klassen ab, mit expliziter Semantik ohne Raten. Ist der ganze Input eine JSONC/JSON5-Datei, ist Konvertierung vorhersagbarer als Reparatur. Zu den Abwägungen der Dialekte selbst siehe den JSON5- und JSONC-Leitfaden.
  • Nach der Reparatur schickst du das Ergebnis durch das JSON-Parse-Tool, um zu validieren und zu formatieren — Fehler auf Zeile und Spalte lokalisiert, bestätigend, dass ein strikter Parser die Ausgabe wirklich annimmt.
  • Probleme der Bibliotheksklasse (Python-Literale, Abbruch-Vervollständigung, JSONP-Verpackung, Markdown-Zäune) verlangen weiterhin jsonrepair / json-repair im Code — ein gleichwertiger Ein-Klick-Reparatur im Browser existiert nicht, weil diese Reparaturen Absichts-Inferenz mit sich bringen, und eine lokale Bibliothek dafür ein sichereres Zuhause ist als ein Universal-Konverter.

Wenn du kein kaputtes Datum, sondern eine Fehlermeldung in der Hand hältst, beginne mit dem Leitfaden zu JSON-Parse-Fehlern, um die Meldung in Koordinaten zu übersetzen, und entscheide dann: von Hand editieren oder reparieren.

FAQ

Beschädigt JSON-Reparatur meine Daten?

Für die neun reparierbaren Klassen ändern sich nur Interpunktion und Verpackung — Werte bleiben unangetastet, und //, Kommas und geschweifte Klammern innerhalb von Strings bewahrt der Zustandsautomat. Aber Abbruch-Vervollständigung liefert unvollständige Objekte, Zahlen mit führender Null werden zu Strings, und der Umgang mit NaN variiert je nach Bibliothek. Die Prüfung der Schlüsselfelder nach der Reparatur ist Pflicht.

Wie hängen Reparatur und Validierung zusammen?

Validierung sagt dir, wo der Input illegal ist; Reparatur liefert dir ein legales Dokument. Der verlässliche Workflow macht beides: erst reparieren, dann validieren — das Schema fängt Typen und Pflichtfelder, die Syntaxprüfung bestätigt, dass ein strikter Parser das Ergebnis akzeptiert. Reparieren ohne Validieren tauscht einen lauten Syntaxfehler gegen einen stillen Datenfehler.

Das LLM wickelt die Ausgabe immer in einen ```json-Zaun — was tun?

Kurzfristig: extrahieren. Nimm den Text vom ersten { oder [ bis zum letzten } oder ] und parse ihn; ein Reparateur mit Zaun-Entfernung schluckt auch die ganze Nachricht. Langfristig: nutze Structured Outputs oder eine explizite „keine Markdown-Zäune“-Anweisung, damit der Zaun nie entsteht.

jsonrepair oder json-repair — welches?

Für JavaScript das npm-Paket jsonrepair (unterstützt Streaming-Transform); für Python json-repair von PyPI. Wenn beide Enden reparieren, wähle ein semantisch ausgerichtetes Paar — etwa json-repair plus seinen TS-Port — damit derselbe Input beidseitig identisch repariert wird.

Können Reparatoren Umlaute und typografische Anführungszeichen?

Ja. Typografische Anführungszeichen aus deutschen Tastaturen („“), geschützte Leerzeichen und ein BOM am Dateianfang stehen alle auf der Standard-Reparaturliste; typografische Anführungszeichen werden zu geraden normalisiert. Schick das Ergebnis einmal durch einen Validator — fertig.