JSON Toolkit

Guía de reparación JSON: rescatar salidas rotas de LLM sin perder confianza

En resumen: Salidas de LLM envueltas en cercas de markdown, con comas finales y literales de Python, no sobreviven a un parser estricto — igual que configuraciones editadas a mano sin comillas. Esta guía traza la frontera real entre nueve clases de errores que un reparador corrige y cuatro que nunca corregirá, explica por qué una máquina de estados vence a las regex, y entrega una cadena de parseo lista para producción con jsonrepair y json-repair.

Intermedio~6 min de lecturaPublicado el 2026-11-08Actualizado el 2026-11-08
Diagrama del pipeline de reparación JSON: retirada de cercas, normalización de comillas, equilibrio de llaves y validación final

Un parser estricto no concede nada a una entrada rota: un mensaje de error, un número de línea — y ni un solo byte de tus datos. El reparador existe para convertir «fallo total» en «suficientemente bueno para ejecutarse» — pero lo que rellena es siempre la mejor suposición sobre la intención, nunca una garantía de corrección.

Uno: de dónde viene el JSON roto

La reparación no es magia — empieza examinando la entrada. En proyectos reales, el JSON no estándar proviene de tres fuentes concentradas:

  1. Salidas de LLM. Los modelos de lenguaje generan texto token a token; no ejecutan ningún serializador JSON. Aunque pidas «solo JSON», el modelo envuelve la respuesta en una cerca ```json, antepone «Aquí tienes tus datos», deja una coma final, o choca con el límite de tokens y se detiene a mitad de un objeto.
  2. Copiar desde otros lenguajes. Un objeto JavaScript impreso vía console.log lleva comillas simples y claves sin comillas; un diccionario de Python se imprime como True/False/None. Estas cadenas «con aspecto de JSON» estallan al primer contacto con JSON.parse.
  3. Configuraciones JSON5/JSONC. Archivos como tsconfig permiten legítimamente comentarios y comas finales. Pega uno en un parser estricto y rechazará el archivo entero.

Las tres fuentes requieren tratamientos distintos, pero los reparadores cubren todas — siempre que el error esté en su lista declarada de casos corregibles.

Dos: nueve clases de errores que un reparador realmente corrige

Combinando la documentación de la biblioteca jsonrepair con los listados de capacidades publicados por proveedores de herramientas, los errores corregibles automáticamente se dividen en nueve clases:

Clase Entrada rota Resultado reparado
Coma final [1, 2, 3,] [1, 2, 3]
Comillas simples / tipográficas {'a': 'b'}、{"a": "b"} {"a": "b"}
Claves sin comillas {name: 'Ada'} {"name": "Ada"}
Comentarios {"a": 1 /* nota */} {"a": 1}
Literales de Python {"ok": True, "v": None} {"ok": true, "v": null}
Cercas markdown ```json {...} ``` {...}
Comas ausentes [1 2] [1, 2]
Llaves / comillas sin cerrar {"a": [1, 2 {"a": [1, 2]}
JSONP / concatenación de cadenas cb({...})、"x" + "y" {...}、"xy"

Lo que comparten estas nueve clases: los datos están todos; rota está solo la sintaxis. El reparador ajusta puntuación y envoltorios sin tocar un solo valor. Algunos detalles merecen atención aparte:

  • Los números con cero inicial se vuelven cadenas. 007 se repara como "007", no como 7, para no perder dígitos. Si el campo es realmente un código textual, es correcto; si es un número de verdad, la decisión es tuya.
  • Las palabras desnudas se vuelven cadenas. NaN no se puede reparar en número — algunas implementaciones emiten "NaN", otras null. El comportamiento varía entre bibliotecas; prueba la tuya antes de enchufarla a una canalización.
  • La entrada válida pasa intacta. Todo reparador serio ejecuta primero una ruta rápida de parseo estricto. El JSON válido nunca entra en la lógica de reparación, así que «reparar un documento bueno en uno malo» es imposible.

Tres: cuatro cosas que un reparador no corrige

La frontera del otro lado es igual de explícita. No esperes reparación para:

  1. Páginas de error HTML o prosa pura. No hay estructura JSON alguna en la entrada, y ninguna herramienta puede crear datos de la nada.
  2. Datos sintácticamente válidos pero erróneos. Una clave mal escrita, un valor en el sitio equivocado, un número guardado como cadena — son problemas semánticos que cualquier parser, reparadores incluidos, deja pasar sin rechistar.
  3. Datos perdidos por truncamiento. La finalización puede convertir {"items": [{"id": 1}, {"na en JSON válido, pero el valor del campo name jamás vuelve. Recibes un objeto «válido pero incompleto». En producción, comprueba stopReason === "max_tokens" antes de decidir entre completar o reintentar.
  4. Claves duplicadas y estructuras ambiguas. Cuál de dos claves idénticas gana depende de la implementación del parser. Los reparadores responsables ofrecen un modo strict que lanza error en lugar de elegir uno en silencio.

Una frase resume la frontera de confianza: la reparación es una mejor suposición, no una garantía de corrección. Dejar pasar un resultado de reparación sin verificar aguas abajo intercambia un error de sintaxis ruidoso por un error de datos silencioso.

Cuatro: dos escuelas de implementación — una URL zanja la disputa

Los reparadores del mercado vienen en dos sabores, y la brecha se manifiesta en un tipo de entrada muy concreto.

La escuela de sustitución regex aplica buscar-y-reemplazar global sobre patrones rotos. Considera esta entrada:

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

Una regex que convierte comillas simples en dobles mascullará también el contenido de la URL; una regex de limpieza de comentarios que borra cada // cortará http:// por la mitad. Dentro de una cadena y fuera de una estructura, los caracteres se ven idénticos — la regex no puede distinguirlos.

La escuela de la máquina de estados carácter a carácter rastrea un estado de parseo: dentro de una cadena con comillas dobles, con simples, dentro de un comentario de línea, de un comentario de bloque, o esperando un valor. Al ver ', primero pregunta «¿estoy dentro de una cadena?» y solo entonces decide si convierte la comilla o la salta. http://example.com está dentro de una cadena con comillas dobles, así que la máquina de estados sabe que el // de ahí son datos, no un comentario, y lo conserva. jsonrepair y json-healer pertenecen a esta escuela, y el mantra comunitario «un reparador no es buscar-y-reemplazar» se refiere justamente a esto.

El orden completo del pipeline de reparación (según la implementación divulgada por devkits) también merece una mirada: retirar cercas → normalizar comillas tipográficas → extraer el primer bloque equilibrado → retirar comentarios → envolver claves desnudas en comillas → quitar comas finales → convertir literales → al final re-serializar con JSON.stringify. Esa re-serialización final es el paso clave: hagan lo que hagan las fases anteriores, la salida se regenera desde el resultado parseado, así que cualquier parser estricto aguas abajo la consume.

Cinco: conectarlo en código — una cadena de parseo secuencial

Cuando conectas la reparación en código, el orden importa más que la elección de la biblioteca. Siguiendo los patrones publicados por json2toon y aijsonmedic, la secuencia debe ser: comprobación de truncamiento → extracción del tramo JSON → parseo estricto → reparación como respaldo → validación por esquema.

import { jsonrepair } from "jsonrepair";

export function parseModelJson(text, stopReason) {
  if (stopReason === "max_tokens") {
    // Reparar una salida truncada deja datos ausentes — reintenta
    throw new Error("Truncated output: retry with a higher max_tokens");
  }
  // Extrae el tramo JSON: el LLM puede charlar antes y después
  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);   // ruta rápida para entrada válida
  } catch {
    return JSON.parse(jsonrepair(candidate));  // reparación como respaldo
  }
}

En el lado de Python, el paquete json-repair (más de 4.700 estrellas) ofrece loads(), que devuelve un objeto directamente:

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}

Dos detalles de ingeniería más:

  • Alinea tus stacks. Si frontend y backend reparan ambos, elige implementaciones con semántica compartida — el json-repair de Python y su port a TypeScript @yarmu/json-repair, o jsonmend, cuyas versiones Python y JS superan el mismo corpus de conformidad de 485 casos. Si no, la misma salida se repara en A en el cliente y en B en el servidor, y la depuración se convierte en una pesadilla.
  • Activa el registro de reparaciones. @yarmu/json-repair con logging: true devuelve una matriz de cada operación de reparación. Un salto repentino en la tasa de reparaciones suele significar que el prompt o la versión del modelo cambió — una señal más temprana que cualquier informe de errores.

Un paso tras la reparación no es negociable: la validación por esquema. Sintácticamente válido no significa utilizable. Campos ausentes, tipos erróneos y claves inesperadas los captura un esquema. El enfoque de pruebas de contrato se aplica aquí directamente; consulta nuestra guía sobre pruebas de contrato con JSON Schema.

Seis: lista de prevención — la reparación más barata es la que no necesitas

La reparación es el respaldo. La victoria real es producir menos JSON roto en la fuente, en orden de prioridad:

  1. Structured Outputs (modo json_schema). La decodificación queda constreñida por el esquema, así que una coma final simplemente no puede generarse. El modo strict de OpenAI falla en torno al 0,1%, a cambio de exigencias duras como additionalProperties: false.
  2. Modo JSON (json_object). Garantiza solo validez sintáctica — no la forma — y el truncamiento por límite de tokens sigue ocurriendo.
  3. Instrucciones explícitas. En endpoints sin modo JSON, formular «sin cercas, sin comentarios, sin comas finales, emite solo el objeto» reduce la tasa de errores un 70–80%.
  4. Bajar la temperature, subir el límite de tokens. Lo primero reduce la deriva hacia la prosa; lo segundo reduce los truncamientos.
  5. Reintentar con el error adjunto. Cuando la validación falla, añade a la conversación la salida rota más la «ruta JSON + mensaje de error» y pide de nuevo. Con un error preciso, los modelos suelen corregirse a sí mismos.

En la práctica, apilar «structured outputs + reparación de respaldo + validación por esquema» cubre prácticamente cada escenario.

Siete: repartir el trabajo — la conversión de dialecto no es reparación

En la caja de herramientas de este sitio hay dos destinos que cubren segmentos distintos de esta canalización:

  • Problemas de dialecto (comentarios, comillas simples, comas finales) van directo al convertidor JSON5. La conversión JSON5 ↔ JSON estándar cubre exactamente esas tres clases, con semántica explícita, sin adivinanzas. Si toda la entrada es un archivo JSONC/JSON5, la conversión es más predecible que la reparación. Sobre las decisiones de los dialectos en sí, consulta la guía JSON5 y JSONC.
  • Tras la reparación, pasa el resultado por la herramienta de parseo JSON para validar y formatear — con errores localizados a fila y columna, confirmando que un parser estricto realmente acepta la salida.
  • Problemas de clase biblioteca (literales de Python, finalización de truncamiento, envoltorios JSONP, cercas markdown) aún requieren jsonrepair / json-repair en el lado del código — no existe una reparación equivalente de un clic en el navegador, porque estas reparaciones implican inferir la intención, y una biblioteca local es un hogar más seguro para ello que un convertidor universal.

Si lo que tienes en las manos es un mensaje de error y no datos rotos, empieza por la guía de corrección de errores de parseo JSON para traducir el mensaje a coordenadas, y solo entonces decide: editar a mano o reparar.

FAQ

¿La reparación JSON corrompe mis datos?

Para las nueve clases corregibles solo cambian puntuación y envoltorios — los valores quedan intactos, y el //, las comas y las llaves dentro de cadenas los preserva la máquina de estados. Pero la finalización de truncamiento entrega objetos incompletos, los números con cero inicial se vuelven cadenas, y el manejo de NaN varía entre bibliotecas. Revisar los campos clave tras la reparación es obligatorio.

¿Qué relación hay entre reparar y validar?

La validación te dice dónde la entrada es ilegal; la reparación te entrega un documento legal. El flujo fiable hace ambas: reparar primero, validar después — el esquema captura tipos y campos obligatorios, la comprobación sintáctica confirma que un parser estricto acepta el resultado. Reparar sin validar intercambia un error de sintaxis ruidoso por un error de datos silencioso.

El LLM siempre envuelve la salida en una cerca ```json — ¿qué hago?

A corto plazo, extrae: toma el texto del primer { o [ hasta el último } o ] y parsealo; un reparador con retirada de cercas también se traga el mensaje entero. A largo plazo, usa structured outputs o una instrucción explícita «sin cercas markdown» para que la cerca jamás se genere.

¿jsonrepair o json-repair — cuál elegir?

Para JavaScript, el paquete npm jsonrepair (soporta transform en streaming); para Python, json-repair de PyPI. Si ambos extremos reparan, elige un par de semántica alineada — por ejemplo, json-repair más su port TS — para que la misma entrada se repare idénticamente a ambos lados.

¿Los reparadores manejan español y comillas tipográficas?

Sí. Las comillas tipográficas de teclados españoles (« »), los espacios indivisibles y el BOM al inicio del archivo están todos en la lista estándar de reparación; las comillas tipográficas se normalizan a comillas rectas. Pasa el resultado una vez por un validador y listo.