JSON para Desarrolladores: Sintaxis, Validación y Errores Comunes

· 12 min de lectura

Tabla de Contenidos

Qué es JSON y Por Qué Importa

JSON (JavaScript Object Notation) se ha convertido en el estándar de facto para el intercambio de datos en la web. A pesar de que su nombre sugiere una conexión con JavaScript, JSON es completamente independiente del lenguaje y es compatible con prácticamente todos los lenguajes de programación modernos.

Originalmente especificado por Douglas Crockford a principios de la década de 2000, JSON surgió como una alternativa ligera a XML. Su simplicidad y legibilidad humana lo convirtieron en el formato perfecto para APIs, archivos de configuración y almacenamiento de datos.

Hoy en día, JSON impulsa todo, desde APIs REST y bases de datos NoSQL hasta archivos de configuración y pipelines de datos. Entender JSON a fondo no es solo útil, es esencial para el desarrollo de software moderno.

Consejo rápido: JSON no es un lenguaje de programación ni un formato de base de datos. Es puramente un formato de serialización de datos: una forma de representar datos estructurados como texto.

Reglas de Sintaxis de JSON

La sintaxis de JSON es engañosamente simple, pero su rigurosidad sorprende a muchos desarrolladores. A diferencia de los objetos de JavaScript, JSON tiene cero tolerancia para las variaciones de sintaxis.

Aquí hay un ejemplo de JSON válido que demuestra la estructura básica:

{
  "name": "RunDev",
  "version": 2,
  "features": ["formatter", "validator", "converter"],
  "config": {
    "theme": "dark",
    "autoSave": true
  },
  "deprecated": null
}

Las Reglas No Negociables

Cada documento JSON debe seguir estas reglas estrictas:

¿Por Qué Tan Estricto?

La rigurosidad de JSON es intencional. Al eliminar la ambigüedad, JSON asegura que cualquier documento JSON válido pueda ser analizado de manera idéntica en todas las plataformas y lenguajes. Esta previsibilidad es lo que hace que JSON sea confiable para el intercambio de datos.

La falta de comentarios es a menudo criticada, pero obliga a los desarrolladores a hacer que sus datos sean autodocumentados a través de nombres de claves y estructura claros. Para archivos de configuración donde se necesitan comentarios, considera JSONC (JSON con Comentarios) o JSON5.

Consejo profesional: Usa nuestro Formateador JSON para corregir automáticamente errores de sintaxis comunes y asegurar que tu JSON sea válido antes del despliegue.

Entendiendo los Tipos de Datos de JSON

JSON admite exactamente seis tipos de datos. Este conjunto limitado mantiene el formato simple mientras cubre la mayoría de las necesidades de representación de datos.

Tipo Ejemplo Notas
Cadena "hello world" Debe estar entre comillas dobles. Admite secuencias de escape: \n, \t, \u0041, \", \\
Número 42, 3.14, -1, 1e10 Sin distinción entre entero y flotante. Sin hexadecimal, octal o valores especiales como Infinity
Booleano true, false Solo en minúsculas. "true" es una cadena, no un booleano
Null null Solo en minúsculas. Representa la ausencia intencional de valor
Array [1, "two", true] Lista ordenada. Puede contener tipos mixtos (aunque los arrays homogéneos son más claros)
Objeto {"key": "value"} Pares clave-valor no ordenados. Las claves deben ser cadenas y deberían ser únicas

Cadenas y Secuencias de Escape

Las cadenas JSON admiten varias secuencias de escape para caracteres especiales:

Las cadenas multilínea deben usar secuencias de escape; los saltos de línea literales no están permitidos:

{
  "correct": "Línea 1\nLínea 2\nLínea 3",
  "incorrect": "Línea 1
Línea 2
Línea 3"
}

Números: Qué Está Permitido y Qué No

Los números JSON son más restrictivos que la mayoría de los lenguajes de programación:

La especificación JSON no define límites de precisión, pero la mayoría de las implementaciones usan punto flotante de doble precisión IEEE 754, lo que significa que los enteros son seguros hasta 2^53 - 1 (9,007,199,254,740,991).

Consejo profesional: Para enteros grandes más allá del rango de enteros seguros de JavaScript, considera almacenarlos como cadenas para evitar la pérdida de precisión durante el análisis.

Objetos y Unicidad de Claves

Aunque la especificación JSON establece que las claves de objeto deben ser únicas, no exige cómo los analizadores deben manejar duplicados. Diferentes implementaciones se comportan de manera diferente:

Mejor práctica: Siempre asegúrate de que tus claves sean únicas para evitar comportamientos impredecibles en diferentes analizadores.

Errores Comunes y Cómo Evitarlos

Incluso los desarrolladores experimentados cometen errores de sintaxis JSON. Aquí están los errores más frecuentes y sus soluciones:

Error Incorrecto Correcto
Comillas simples {'name': 'test'} {"name": "test"}
Coma final {"a": 1, "b": 2,} {"a": 1, "b": 2}
Claves sin comillas {name: "test"} {"name": "test"}
Comentarios {"a": 1 // comment} Eliminar comentarios o usar JSONC
Valor undefined {"a": undefined} {"a": null}
Ceros iniciales {"port": 080} {"port": 80}
Saltos de línea literales "línea1
línea2"		 "línea1\nlínea2"
Valores de función {"fn": function(){}} No compatible—usar cadenas o reestructurar

La Trampa del Objeto JavaScript

La mayor fuente de errores JSON es tratarlo como sintaxis literal de objeto JavaScript. Se ven similares pero tienen diferencias críticas:

// Objeto JavaScript válido
const jsObj = {
  name: 'test',        // clave sin comillas, comillas simples
  age: 30,
  active: true,
  getData: function() { return this.name; },  // funciones permitidas
  // comentario permitido
};

// JSON válido (como cadena)
const jsonStr = `{
  "name": "test",
  "age": 30,
  "active": true
}`;

Recuerda: JSON es un formato de datos, no código. No puede contener funciones, comentarios o lógica ejecutable.

Problemas de Codificación de Caracteres

JSON debe estar codificado en UTF-8, UTF-16 o UTF-32. UTF-8 es la codificación más común y recomendada. Ten cuidado con:

Consejo rápido: Pega tu JSON en nuestro Validador JSON para identificar instantáneamente errores de sintaxis, problemas de codificación y problemas estructurales.

Validando JSON: Herramientas y Técnicas

La validación es crucial para detectar errores antes de que causen fallos en tiempo de ejecución. Aquí te mostramos cómo validar JSON en diferentes entornos.

Validación por Línea de Comandos

Validación rápida usando herramientas integradas:

# Python (integrado, disponible en todas partes)
python3 -m json.tool data.json

# Formatear e imprimir y validar
python3 -m json.tool data.json output.json

# jq (procesador JSON potente)
jq . data.json

# jq con detalles de error
jq . data.json || echo "JSON inválido"

# Node.js en una línea
node -e "console.log(JSON.parse(require('fs').readFileSync('data.json')))"

# Usando jsonlint (instalar vía npm)
jsonlint data.json

Validación Programática

Valida JSON en el código de tu aplicación:

// JavaScript/Node.js
function isValidJSON(str) {
  try {
    JSON.parse(str);
    return true;
  } catch (e) {
    console.error('Error JSON:', e.message);
    return false;
  }
}

# Python
import json

def is_valid_json(json_str):
    try:
        json.loads(json_str)
        return True
    except json.JSONDecodeError as e:
        print(f'Error JSON: {e}')
        return False

// Go
import "encoding/json"

func isValidJSON(data []byte) bool {
    var js json.RawMessage
    return json.Unmarshal(data, &js) == nil
}

Validación de Esquema

La validación de sintaxis solo verifica si el JSON está bien formado. La validación de esquema asegura que la estructura de datos y los tipos coincidan con tus requisitos.

JSON Schema es el estándar para definir la estructura JSON:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1
    },
    "age": {
      "type": "integer",
      "minimum": 0,
      "maximum": 150
    },
    "email": {
      "type": "string",
      "format": "email"
    }
  },
  "required": ["name", "email"]
}

Bibliotecas populares de validación de esquema:

Consejo profesional: Usa nuestro Validador de Esquema JSON para probar tus esquemas contra datos de muestra antes de implementarlos en código.

Herramientas de Validación en Línea

Para verificaciones rápidas durante el desarrollo:

Mejores Prácticas de Análisis y Serialización

El análisis convierte texto JSON en estructuras de datos nativas. La serialización hace lo contrario. Ambas operaciones tienen implicaciones de rendimiento y seguridad.

Prácticas de Análisis Seguro

Siempre envuelve el análisis JSON en manejo de errores:

// JavaScript - Análisis básico
try {
  const data = JSON.parse(jsonString);
  // Usar data
} catch (error) {
  console.error('Error al analizar JSON:', error.message);
  // Manejar el error apropiadamente
}

// JavaScript - Con función reviver
const data = JSON.parse(jsonString, (key, value) => {
  // Transformar fechas desde cadenas
  if (key.endsWith('Date') && typeof value === 'string') {
    return new Date(value);
  }
  return value;
});

Mejores Prácticas de Serialización

Controla cómo los objetos se convierten a JSON:

// JavaScript - Serialización básica
const json = JSON.stringify(data);

// Formatear con indentación
const json = JSON.stringify(data, null, 2);

// Serialización personalizada con replacer
const json = JSON.stringify(data, (key, value) => {
  // Eliminar campos sensibles
  if (key === 'password' || key === 'apiKey') {
    return undefined;
  }
  // Convertir BigInt a cadena
  if (typeof value === 'bigint'