JSON Toolkit

Guida alla riparazione JSON: recuperare gli output LLM rotti senza perdere fiducia

In sintesi: Gli output LLM avvolti in recinti markdown, con virgole finali e letterali Python, non sopravvivono a un parser rigoroso — nemmeno le config modificate a mano senza virgolette. Questa guida traccia il confine reale tra nove classi di errori che un riparatore corregge e quattro che non correggerà mai, spiega perché le macchine a stati battono le regex e fornisce una catena di parsing pronta per la produzione con jsonrepair e json-repair.

Intermedio~6 min di letturaPubblicato il 2026-11-08Aggiornato il 2026-11-08
Diagramma della pipeline di riparazione JSON: rimozione dei recinti, normalizzazione delle virgolette, bilanciamento delle parentesi, validazione finale

Un parser rigoroso non concede nulla a un input rotto: un messaggio di errore, un numero di riga — e nemmeno un byte dei tuoi dati. Il riparatore esiste per trasformare "fallimento totale" in "abbastanza buono da girare" — ma quello che riempie è sempre la migliore congettura sull'intento, mai una garanzia di correttezza.

Uno: da dove viene il JSON rotto

La riparazione non è magia: inizia esaminando l'input. Nei progetti reali, il JSON non standard proviene da tre fonti concentrate:

  1. Output LLM. I modelli linguistici generano testo token per token; non eseguono un serializzatore JSON. Anche chiedendo "solo JSON", il modello avvolge la risposta in un recinto ```json, antepone "Ecco i tuoi dati", lascia una virgola finale o raggiunge il tetto di token e si ferma in mezzo a un oggetto.
  2. Copia da altri linguaggi. Un oggetto JavaScript stampato via console.log porta virgolette singole e chiavi senza virgolette; un dizionario Python si stampa come True/False/None. Queste stringhe "dall'aspetto JSON" esplodono al primo contatto con JSON.parse.
  3. Config JSON5/JSONC. File come tsconfig permettono legittimamente commenti e virgole finali. Incollarne uno in un parser rigoroso e rifiuta l'intero file.

Le tre fonti richiedono trattamenti diversi, ma i riparatori coprono tutte — purché l'errore sia nella loro lista dichiarata di casi correggibili.

Due: nove classi di errori che un riparatore corregge davvero

Combinando la documentazione della libreria jsonrepair con gli elenchi di capacità pubblicati dai fornitori di strumenti, gli errori automaticamente correggibili si dividono in nove classi:

Classe Input rotto Risultato riparato
Virgola finale [1, 2, 3,] [1, 2, 3]
Virgolette singole / tipografiche {'a': 'b'}、{"a": "b"} {"a": "b"}
Chiavi senza virgolette {name: 'Ada'} {"name": "Ada"}
Commenti {"a": 1 /* nota */} {"a": 1}
Letterali Python {"ok": True, "v": None} {"ok": true, "v": null}
Recinti markdown ```json {...} ``` {...}
Virgole mancanti [1 2] [1, 2]
Parentesi / virgolette non chiuse {"a": [1, 2 {"a": [1, 2]}
JSONP / concatenazione di stringhe cb({...})、"x" + "y" {...}、"xy"

Ciò che queste nove classi condividono: i dati sono tutti lì; rotta è solo la sintassi. Il riparatore aggiusta punteggiatura e involucri senza toccare un solo valore. Alcuni dettagli meritano attenzione specifica:

  • I numeri con lo zero iniziale diventano stringhe. 007 viene riparato in "007", non in 7, per non perdere cifre. Se il campo è davvero un codice testuale è corretto; se è un numero vero, la decisione è tua.
  • Le parole nude diventano stringhe. NaN non può essere riparato in numero — alcune implementazioni emettono "NaN", altre null. Il comportamento varia tra librerie; testa la tua prima di metterla in una pipeline.
  • L'input valido passa indenne. Ogni riparatore serio esegue prima un percorso veloce di parsing rigoroso. Il JSON valido non entra mai nella logica di riparazione, quindi "riparare un buon documento in uno cattivo" è impossibile.

Tre: quattro cose che un riparatore non corregge

Il confine dall'altro lato è altrettanto esplicito. Non aspettarti riparazioni per:

  1. Pagine di errore HTML o pura prosa. Non c'è nessuna struttura JSON nell'input, e nessun strumento può creare dati dal nulla.
  2. Dati sintatticamente validi ma sbagliati. Una chiave sbagliata di ortografia, un valore nel posto sbagliato, un numero salvato come stringa — sono problemi semantici che ogni parser, riparatori inclusi, lascia passare senza fiatare.
  3. Dati persi per troncamento. Il completamento può trasformare {"items": [{"id": 1}, {"na in JSON valido, ma il valore di name non torna mai. Ricevi un oggetto "valido ma incompleto". In produzione, controlla stopReason === "max_tokens" prima di decidere se completare o ritentare.
  4. Chiavi duplicate e strutture ambigue. Quale di due chiavi identiche vince dipende dall'implementazione del parser. I riparatori responsabili offrono una modalità strict che lancia errore invece di scegliere in silenzio.

Una frase riassume il confine di fiducia: la riparazione è una congettura, non una garanzia di correttezza. Lasciar passare un risultato di riparazione non verificato a valle scambia un errore di sintassi rumoroso con un errore di dati silenzioso.

Quattro: due scuole di implementazione — una URL decide la disputa

I riparatori in commercio esistono in due varianti, e la differenza appare su un tipo di input ben preciso.

La scuola della sostituzione regex applica cerca-e-sostituisci globale ai pattern rotti. Considera questo input:

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

Una regex che converte le virgolette singole in doppie masticherà anche il contenuto dell'URL; una regex di pulizia dei commenti che elimina ogni // taglierà http:// in due. Dentro una stringa e fuori da una struttura i caratteri sembrano identici — la regex non può distinguerli.

La scuola della macchina a stati carattere per carattere traccia uno stato di parsing: dentro una stringa tra virgolette doppie, tra virgolette singole, dentro un commento di riga, un commento a blocco, o in attesa di un valore. Vedendo ', chiede prima "sono dentro una stringa?" e solo poi decide se convertire la virgoletta o saltarla. http://example.com si trova dentro una stringa tra virgolette doppie, quindi la macchina a stati sa che il // è dati, non commento, e lo preserva. jsonrepair e json-healer appartengono a questa scuola, e il mantra della community "un riparatore non è un cerca-e-sostituisci" si riferisce proprio a questo.

L'ordine completo della pipeline di riparazione (come divulgato dall'implementazione devkits) merita uno sguardo: rimuovere i recinti → normalizzare le virgolette tipografiche → estrarre il primo blocco bilanciato → rimuovere i commenti → virgolettare le chiavi nude → eliminare le virgole finali → convertire i letterali → ri-serializzare con JSON.stringify. Quel ri-serializzazione finale è il passaggio chiave: qualunque cosa abbiano fatto le fasi precedenti, l'output è rigenerato dal risultato analizzato, quindi ogni parser rigoroso a valle lo consuma.

Cinque: integrarlo nel codice — una catena di parsing sequenziale

Quando integri la riparazione nel codice, l'ordine conta più della scelta della libreria. Seguendo i pattern pubblicati da json2toon e aijsonmedic, la sequenza deve essere: controllo di troncamento → estrazione della porzione JSON → parse rigoroso → riparazione come fallback → validazione dello schema.

import { jsonrepair } from "jsonrepair";

export function parseModelJson(text, stopReason) {
  if (stopReason === "max_tokens") {
    // Riparare un output troncato lascia comunque dati mancanti — ritenta
    throw new Error("Truncated output: retry with a higher max_tokens");
  }
  // Estrai la porzione JSON: l'LLM può chiacchierare prima e dopo
  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);   // percorso veloce per input valido
  } catch {
    return JSON.parse(jsonrepair(candidate));  // riparazione come fallback
  }
}

Lato Python, il pacchetto json-repair (oltre 4.700 stelle) offre loads(), che restituisce direttamente un oggetto:

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}

Due dettagli ingegneristici:

  • Allinea le tue stack. Se frontend e backend riparano entrambi, scegli implementazioni con semantica condivisa — il Python json-repair e il suo port TypeScript @yarmu/json-repair, oppure jsonmend, le cui versioni Python e JS superano lo stesso corpus di conformità di 485 casi. Altrimenti lo stesso output si ripara in A sul client e in B sul server, e il debug diventa un incubo.
  • Attiva il log di riparazione. @yarmu/json-repair con logging: true restituisce un array di ogni operazione di riparazione. Un picco improvviso nel tasso di riparazioni di solito significa che il prompt o la versione del modello è cambiata — un segnale più precoce di qualsiasi report di errore.

Un passo dopo la riparazione è non negoziabile: la validazione dello schema. Sintatticamente valido non significa utilizzabile. Campi mancanti, tipi errati e chiavi inaspettate sono tutti catturati da uno schema. L'approccio dei test di contratto si applica direttamente qui; vedi la nostra guida sui test di contratto JSON Schema.

Sei: checklist di prevenzione — la riparazione più economica è quella di cui non hai bisogno

La riparazione è il fallback. Produrre meno JSON rotto alla fonte è la vera vittoria, in ordine di priorità:

  1. Structured Outputs (modalità json_schema). La decodifica è vincolata dallo schema, quindi una virgola finale semplicemente non può essere generata. La modalità strict di OpenAI fallisce circa nello 0,1% dei casi, al costo di requisiti rigidi come additionalProperties: false.
  2. Modalità JSON (json_object). Garantisce solo validità sintattica — non la forma — e il troncamento per limite di token continua a verificarsi.
  3. Istruzioni esplicite. Sui endpoint senza modalità JSON, scrivere "niente recinti, niente commenti, niente virgole finali, emetti solo l'oggetto" riduce il tasso di errori del 70–80%.
  4. Abbassare la temperature, alzare il limite di token. La prima riduce la deriva verso la prosa; la seconda riduce i troncamenti.
  5. Ritentare con l'errore allegato. Quando la validazione fallisce, aggiungi alla conversazione l'output rotto più il "percorso JSON + messaggio di errore" e chiedi di nuovo. I modelli di solito si autocorreggono davanti a un errore preciso.

In pratica, impilare "structured outputs + riparazione di fallback + validazione dello schema" copre praticamente ogni scenario.

Sette: dividere il lavoro — la conversione di dialetto non è riparazione

Nel toolbox di questo sito ci sono due destinazioni che coprono segmenti distinti di questa pipeline:

  • Problemi di dialetto (commenti, virgolette singole, virgole finali) vanno direttamente al convertitore JSON5. La conversione JSON5 ↔ JSON standard copre esattamente queste tre classi, con semantica esplicita, senza indovinelli. Se l'intero input è un file JSONC/JSON5, la conversione è più prevedibile della riparazione. Per i compromessi dei dialetti stessi, vedi la guida JSON5 e JSONC.
  • Dopo la riparazione, passa il risultato per lo strumento di parsing JSON per validare e formattare, con errori localizzati a riga e colonna, confermando che un parser rigoroso accetta davvero l'output.
  • Problemi di classe libreria (letterali Python, completamento di troncamento, involucri JSONP, recinti markdown) richiedono ancora jsonrepair / json-repair lato codice — non esiste una riparazione equivalente in un clic nel browser, perché queste riparazioni implicano inferire l'intento, e una libreria locale ne è una sede più sicura rispetto a un convertitore universale.

Se ciò che hai in mano è un messaggio di errore piuttosto che dati rotti, inizia con la guida alla correzione degli errori di parsing JSON per tradurre il messaggio in coordinate, e solo allora decidi: modifica a mano o riparazione.

FAQ

La riparazione JSON corrompe i miei dati?

Per le nove classi correggibili cambiano solo punteggiatura e involucri — i valori restano intatti, e //, virgole e graffe dentro le stringhe sono preservati dalla macchina a stati. Ma il completamento di troncamento restituisce oggetti incompleti, i numeri con zero iniziale diventano stringhe, e la gestione di NaN varia tra librerie. Verificare i campi chiave dopo la riparazione è obbligatorio.

Che rapporto c'è tra riparazione e validazione?

La validazione ti dice dove l'input è illegale; la riparazione ti consegna un documento legale. Il flusso affidabile fa entrambe: prima riparare, poi validare — lo schema cattura tipi e campi obbligatori, il controllo sintattico conferma che un parser rigoroso accetta il risultato. Riparare senza validare scambia un errore di sintassi rumoroso con un errore di dati silenzioso.

L'LLM avvolge sempre l'output in un recinto ```json — cosa faccio?

Nel breve termine, estrai: prendi il testo dal primo { o [ fino all'ultimo } o ] e analizzalo; un riparatore con rimozione dei recinti ingoia anche il messaggio intero. Nel lungo termine, usa structured outputs o un'istruzione esplicita "niente recinti markdown" così che il recinto non venga mai generato.

jsonrepair o json-repair — quale scegliere?

Per JavaScript il pacchetto npm jsonrepair (supporta transform in streaming); per Python json-repair da PyPI. Se entrambe le estremità riparano, scegli una coppia a semantica allineata — per esempio json-repair più il suo port TS — così lo stesso input si ripara identicamente da entrambi i lati.

I riparatori gestiscono italiano e virgolette tipografiche?

Sì. Le virgolette tipografiche prodotte dalle tastiere italiane (« »), gli spazi unificatori e il BOM all'inizio del file sono tutti nell'elenco standard di riparazione; le virgolette tipografiche vengono normalizzate in virgolette dritte. Passa il risultato una volta in un validatore e hai finito.