Errores Comunes JSON y Cómo Solucionarlos: Guía de Debugging

# Errores Comunes JSON y Cómo Solucionarlos: Guía de Debugging

Trabajar con JSON puede ser frustrante cuando aparecen errores crípticos. Esta guía completa te ayudará a identificar, entender y resolver los errores JSON más comunes.

Errores de Sintaxis

1. Comas Finales (Trailing Commas)

{
  "nombre": "Ana",
  "edad": 28,  ← Error: coma final
}

Unexpected token } in JSON at position 32
SyntaxError: Unexpected token } in JSON

{
  "nombre": "Ana",
  "edad": 28
}

2. Comillas Simples

{
  'nombre': 'Ana',
  'edad': 28
}

Unexpected token ' in JSON at position 2

{
  "nombre": "Ana",
  "edad": 28
}

3. Claves Sin Comillas

{
  nombre: "Ana",
  edad: 28
}

Unexpected token n in JSON at position 2

{
  "nombre": "Ana",
  "edad": 28
}

4. Comentarios

{
  // Este es un comentario
  "nombre": "Ana",
  "edad": 28
}

Unexpected token / in JSON at position 2

{
  "nombre": "Ana",
  "edad": 28
}

5. Valores No Entrecomillados

{
  "nombre": Ana,
  "edad": 28
}

Unexpected token A in JSON at position 11

{
  "nombre": "Ana",
  "edad": 28
}

6. Números con Ceros a la Izquierda

{
  "codigo": 007
}

Unexpected number in JSON at position 13

{
  "codigo": 7
}
// O como string si necesitas el cero:
{
  "codigo": "007"
}

7. Falta de Comas

{
  "nombre": "Ana"
  "edad": 28
}

Unexpected string in JSON at position 18

{
  "nombre": "Ana",
  "edad": 28
}

Errores de Estructura

8. Arrays con Valores Heterogéneos Mal Formateados

{
  "valores": [1, 2, "tres" 4, 5]
}

Unexpected number in JSON at position 28

{
  "valores": [1, 2, "tres", 4, 5]
}

9. Objetos Anidados Mal Cerrados

{
  "usuario": {
    "nombre": "Ana",
    "contacto": {
      "email": "ana@ejemplo.com"

  }
}

Unexpected token } in JSON at position 78

{
  "usuario": {
    "nombre": "Ana",
    "contacto": {
      "email": "ana@ejemplo.com"
    }
  }
}

10. Valores Undefined

{
  "nombre": "Ana",
  "telefono": undefined
}

Unexpected token u in JSON at position 28

{
  "nombre": "Ana",
  "telefono": null
}
// O simplemente omitir la propiedad:
{
  "nombre": "Ana"
}

Errores de Codificación

11. Caracteres de Control

{
  "texto": "Línea 1
  Línea 2"
}

Unexpected token in JSON at position 22

{
  "texto": "Línea 1\nLínea 2"
}

• \n - Nueva línea
• \r - Retorno de carro
• \t - Tabulación
• \" - Comillas dobles
• \\ - Barra invertida

12. Comillas Sin Escapar

{
  "cita": "Ella dijo "Hola""
}

Unexpected token H in JSON at position 19

{
  "cita": "Ella dijo \"Hola\""
}

13. Encoding UTF-8 Inválido

El archivo tiene BOM (Byte Order Mark) o codificación incorrecta.

# Convertir a UTF-8 sin BOM
iconv -f UTF-8 -t UTF-8 -c archivo.json > archivo_limpio.json

# O en VS Code:
# 1. Abrir archivo
# 2. Clic en encoding (esquina inferior derecha)
# 3. Seleccionar "Save with Encoding"
# 4. Elegir "UTF-8"

Errores en JavaScript/TypeScript

14. JSON.parse() con String Vacío

const datos = JSON.parse("");

SyntaxError: Unexpected end of JSON input

const jsonString = "";
let datos;

try {
  datos = jsonString ? JSON.parse(jsonString) : {};
} catch (error) {
  console.error("JSON inválido:", error.message);
  datos = {};
}

15. JSON.parse() con Undefined o Null

const datos = JSON.parse(undefined);

SyntaxError: Unexpected token u in JSON at position 0

function parsearJSON(str) {
  if (str === null || str === undefined) {
    return null;
  }

  try {
    return JSON.parse(str);
  } catch (error) {
    console.error("Error parseando JSON:", error.message);
    return null;
  }
}

16. Circular References en JSON.stringify()

const obj = { nombre: "Ana" };
obj.self = obj;  // Referencia circular

JSON.stringify(obj);

TypeError: Converting circular structure to JSON

// Opción 1: Usar replacer
const visto = new WeakSet();
const json = JSON.stringify(obj, (key, value) => {
  if (typeof value === "object" && value !== null) {
    if (visto.has(value)) {
      return "[Circular]";
    }
    visto.add(value);
  }
  return value;
});

// Opción 2: Usar biblioteca
import { stringify } from 'circular-json';
const json = stringify(obj);

17. Funciones y Símbolos en JSON.stringify()

const obj = {
  nombre: "Ana",
  saludar: function() { console.log("Hola"); },
  id: Symbol('id')
};

console.log(JSON.stringify(obj));
// {"nombre":"Ana"}  - función y símbolo ignorados

const obj = {
  nombre: "Ana",
  saludar: "function() { console.log('Hola'); }",
  id: "symbol-id"
};

// O usar replacer personalizado
const json = JSON.stringify(obj, (key, value) => {
  if (typeof value === 'function') {
    return value.toString();
  }
  if (typeof value === 'symbol') {
    return value.toString();
  }
  return value;
});

Errores en Validación de Datos

18. Tipo de Dato Incorrecto

// API devuelve string pero esperamos número
const usuario = {
  id: "123",  // String en vez de número
  edad: "28"  // String en vez de número
};

// Validación y conversión
function validarUsuario(datos) {
  return {
    id: parseInt(datos.id, 10),
    edad: parseInt(datos.edad, 10)
  };
}

// O usar Zod para validación
import { z } from 'zod';

const UsuarioSchema = z.object({
  id: z.number(),
  edad: z.number()
});

// Esto lanzará error si tipos no coinciden
const usuario = UsuarioSchema.parse(datos);

19. Propiedades Faltantes

const usuario = {
  nombre: "Ana"
  // falta email
};

console.log(usuario.email.toLowerCase());  // TypeError

// Verificar existencia
if (usuario.email) {
  console.log(usuario.email.toLowerCase());
}

// Operador opcional chaining
console.log(usuario.email?.toLowerCase());

// Valor por defecto
const email = usuario.email ?? "sin-email@ejemplo.com";

// Validación con Zod
const UsuarioSchema = z.object({
  nombre: z.string(),
  email: z.string().email()
});

try {
  const usuarioValido = UsuarioSchema.parse(usuario);
} catch (error) {
  console.error("Usuario inválido:", error.errors);
}

Herramientas de Debugging

JSONLint

// Pegar JSON y validar
// Muestra exactamente dónde está el error

Big JSON Viewer

✓ Detecta errores de sintaxis
✓ Muestra línea exacta del error
✓ Formatea automáticamente
✓ Funciona con archivos grandes

jq en Línea de Comandos

# Validar sintaxis JSON
jq . archivo.json

# Si hay error, muestra la línea exacta
jq . datos.json
# parse error: Expected separator between values at line 5, column 12

VS Code

{
  "json.validate.enable": true,
  "json.format.enable": true
}

• Ctrl + Shift + P → "Format Document"
• Ver errores en panel "Problemas"

Node.js Script de Validación

const fs = require('fs');

function validarJSON(archivo) {
  try {
    const contenido = fs.readFileSync(archivo, 'utf-8');
    JSON.parse(contenido);
    console.log(✓ ${archivo} es JSON válido);
    return true;
  } catch (error) {
    console.error(✗ Error en ${archivo}:);
    console.error(  Línea: ${error.message});

    // Mostrar línea problemática
    const lineas = contenido.split('\n');
    const numeroLinea = extraerNumeroLinea(error.message);
    if (numeroLinea) {
      console.error(  ${lineas[numeroLinea - 1]});
    }

    return false;
  }
}

function extraerNumeroLinea(mensaje) {
  const match = mensaje.match(/line (\d+)/);
  return match ? parseInt(match[1]) : null;
}

// Validar múltiples archivos
const archivos = ['datos1.json', 'datos2.json'];
archivos.forEach(validarJSON);

Mejores Prácticas para Prevenir Errores

1. Usa un Linter

# ESLint para archivos .json
npm install --save-dev eslint eslint-plugin-json

# .eslintrc.js
module.exports = {
  plugins: ['json'],
  overrides: [
    {
      files: ['.json'],

      extends: ['plugin:json/recommended']
    }
  ]
};

// Modo desarrollo: validación estricta
if (process.env.NODE_ENV === 'development') {
  const validarDatos = (datos) => {
    // Validación exhaustiva
    if (!datos.id || typeof datos.id !== 'number') {
      throw new Error('ID inválido');
    }
    // ... más validaciones
  };
}

async function obtenerDatos() {
  try {
    const respuesta = await fetch('/api/datos');
    const datos = await respuesta.json();

    // Validar estructura básica
    if (!datos || typeof datos !== 'object') {
      throw new Error('Formato de datos inválido');
    }

    return datos;
  } catch (error) {
    console.error('Error obteniendo datos:', error);
    // Devolver datos por defecto o reintenta
    return { error: true, mensaje: error.message };
  }
}

import Ajv from 'ajv';

const ajv = new Ajv();

const schema = {
  type: 'object',
  properties: {
    nombre: { type: 'string' },
    edad: { type: 'number', minimum: 0 },
    email: { type: 'string', format: 'email' }
  },
  required: ['nombre', 'email']
};

const validate = ajv.compile(schema);

const datos = {
  nombre: "Ana",
  email: "ana@ejemplo.com",
  edad: 28
};

if (validate(datos)) {
  console.log('✓ Datos válidos');
} else {
  console.error('✗ Errores:', validate.errors);
}

// test/json-validation.test.js
import { describe, it, expect } from 'vitest';
import fs from 'fs';

describe('Validación de archivos JSON', () => {
  it('config.json debe ser válido', () => {
    const contenido = fs.readFileSync('./config.json', 'utf-8');
    expect(() => JSON.parse(contenido)).not.toThrow();
  });

  it('datos.json debe tener estructura correcta', () => {
    const contenido = fs.readFileSync('./datos.json', 'utf-8');
    const datos = JSON.parse(contenido);

    expect(datos).toHaveProperty('usuarios');
    expect(Array.isArray(datos.usuarios)).toBe(true);
  });
});

// Streaming para archivos muy grandes
const fs = require('fs');
const JSONStream = require('JSONStream');

fs.createReadStream('datos_grandes.json')
  .pipe(JSONStream.parse('usuarios.'))
  .on('data', (usuario) => {
    // Procesar cada usuario individualmente
    console.log(usuario);
  })
  .on('error', (error) => {
    console.error('Error:', error);
  });

Pretty Print para Debugging

// Formatear JSON para lectura fácil
console.log(JSON.stringify(datos, null, 2));

// Con colores en Node.js
console.dir(datos, { depth: null, colors: true });

// Mostrar solo ciertas propiedades
console.log(JSON.stringify(datos, ['nombre', 'email'], 2));

Comparar JSON

import { diff } from 'deep-object-diff';

const original = { nombre: "Ana", edad: 28 };
const actualizado = { nombre: "Ana", edad: 29, ciudad: "Madrid" };

const diferencias = diff(original, actualizado);
console.log(diferencias);
// { edad: 29, ciudad: "Madrid" }

Conclusión

La mayoría de errores JSON son sintácticos y fáciles de resolver una vez identificados. Usar herramientas de validación, linters y schemas puede prevenir muchos problemas.

Checklist de Debugging

• ✓ Verifica comillas dobles (no simples)
• ✓ Revisa comas finales
• ✓ Asegura que las claves tengan comillas
• ✓ Valida estructura de llaves/corchetes
• ✓ Escapa caracteres especiales
• ✓ Usa herramientas como JSONLint o Big JSON Viewer
• ✓ Implementa validación en runtime
• ✓ Escribe tests para datos críticos

¡Debugging feliz con JSON!