Dev Tools

Entendiendo JSON: Estructura, Sintaxis y Errores Comunes Explicados

porEditorial Team

jsondata-formatsyntaxapiweb-developmentvalidation

Introducción: JSON Es el Lenguaje Universal de Datos en la Web

JSON — JavaScript Object Notation — es el formato de intercambio de datos más utilizado en internet. Sustenta prácticamente todas las APIs REST, impulsa bases de datos NoSQL como MongoDB y CouchDB, y sirve como formato de configuración para innumerables herramientas de desarrollo, incluyendo package.json, tsconfig.json y los overrides de docker-compose. Si trabajas con tecnología web, trabajas con JSON todos los días.

A pesar de su omnipresencia, la estricta sintaxis de JSON provoca errores constantemente. Una coma mal colocada, una clave sin comillas o un comentario de JavaScript pegado en un archivo JSON causa un fallo total en el parseo con un mensaje de error que varía según el entorno de ejecución. Esta guía cubre JSON desde sus fundamentos: su historia, tipos de datos, reglas de sintaxis, los errores más comunes y cómo se compara con formatos alternativos. Usa nuestro formateador y validador JSON gratuito para detectar y corregir errores al instante mientras sigues esta guía.

Historia de JSON: De los Literales JavaScript a un Estándar IETF

Douglas Crockford formalizó JSON alrededor de 2001, reconociendo que la sintaxis de literales de objetos JavaScript — ya usada en navegadores — podía servir como alternativa ligera a XML para el intercambio de datos. El formato era tan simple que no necesitaba código de parseo para entornos JavaScript: eval() podía parsearlo directamente (aunque esto fue identificado posteriormente como un riesgo de seguridad; ver la sección sobre parseo seguro más adelante).

JSON obtuvo estandarización formal a través de ECMA-262 (como subconjunto de JavaScript) y más tarde a través del IETF. El RFC 4627 (2006) fue el primer RFC dedicado a JSON. El RFC 7159 (2014) lo reemplazó con aclaraciones importantes, especialmente que un texto JSON podía ser cualquier valor JSON, no solo un objeto o array. El RFC 8259 (2017) es la especificación definitiva actual, sustituyendo al RFC 7159 y alineándose con el estándar ECMA-404. Cuando alguien se refiere a "JSON válido", significa JSON conforme al RFC 8259.

Una fuente común de confusión: JSON se derivó de la sintaxis de objetos JavaScript pero no es un subconjunto de JavaScript. JSON requiere cadenas con comillas dobles, prohíbe comas finales y comentarios, y no soporta undefined, funciones ni objetos Date. Un literal de objeto JavaScript válido casi nunca es JSON válido.

Tipos de Datos JSON: Seis Valores Primitivos

JSON tiene exactamente seis tipos de datos. Cada valor en un documento JSON debe ser uno de estos:

String (Cadena)

Una secuencia de caracteres Unicode entre comillas dobles: "hola mundo". Las cadenas deben usar comillas dobles — las comillas simples son un error de sintaxis. Los caracteres especiales dentro de las cadenas deben escaparse con una barra invertida: \" (comilla doble), \\ (barra invertida), \/ (barra diagonal, opcional), \n (nueva línea), \r (retorno de carro), \t (tabulación), \uXXXX (escape Unicode para cualquier punto de código).

Number (Número)

Los números JSON usan notación decimal estándar: 42, -7, 3.14, 1.5e10. JSON no soporta octal (077), hexadecimal (0xFF), NaN, Infinity ni -Infinity. Estos son valores específicos de JavaScript ausentes de la especificación JSON. Los números mayores que Number.MAX_SAFE_INTEGER (2^53 − 1) pierden precisión cuando son parseados por JavaScript; para enteros grandes, usa cadenas.

Boolean (Booleano)

Exactamente true o false en minúsculas. True, TRUE o "true" (una cadena) no son valores booleanos en JSON.

Null

Exactamente null en minúsculas. Representa un valor intencionalmente ausente o vacío.

Object (Objeto)

Una colección no ordenada de pares clave-valor entre llaves. Las claves deben ser cadenas (con comillas dobles). Los valores pueden ser cualquier tipo JSON. Los pares clave-valor se separan con comas, y las claves y valores se separan con dos puntos:

{"nombre": "Alicia", "edad": 30, "activo": true}

Los objetos JSON no garantizan el orden de las claves. Las claves duplicadas están técnicamente permitidas por la especificación pero tienen comportamiento indefinido — la mayoría de los parsers conservan el último valor mientras algunos rechazan el documento. Evita las claves duplicadas.

Array (Arreglo)

Una lista ordenada de valores entre corchetes, separados por comas. Los valores pueden ser de cualquier tipo JSON y no necesitan ser homogéneos:

[1, "dos", null, true, {"clave": "valor"}]

Reglas de Sintaxis JSON: La Lista Completa

Las reglas de sintaxis de JSON son intencionalmente mínimas. Las violaciones causan fallos de parseo inmediatos:

  • Siempre cadenas con comillas dobles. Las comillas simples ('valor') son un error de sintaxis.
  • Sin comas finales. {"a": 1,} y [1, 2, 3,] son inválidos. La coma después del último elemento está prohibida.
  • Sin comentarios. Ni // comentarios de línea ni /* comentarios de bloque */ existen en JSON. Este es el error más común cuando se copian fragmentos de configuración de documentación que usa JSONC (JSON con comentarios).
  • Sin undefined. El undefined de JavaScript no tiene equivalente en JSON. Serializar un objeto con valores undefined a través de JSON.stringify() elimina silenciosamente esas claves.
  • Sin funciones. JSON es un formato de datos, no de código. Las funciones no se pueden representar.
  • Sin NaN ni Infinity. Estos valores de número de JavaScript no tienen representación en JSON. Intentar serializarlos produce null.
  • Sin números hexadecimales. 0xFF no es un número JSON válido.
  • Las claves deben ser cadenas. {nombre: "Alicia"} (clave sin comillas) es JSON inválido, aunque sea JavaScript válido.
  • Unicode es válido. JSON soporta cualquier carácter Unicode en cadenas. Los caracteres no ASCII pueden aparecer literalmente o como escapes \uXXXX.

Errores Comunes de Sintaxis JSON y Cómo Corregirlos

Los siguientes errores son responsables de la gran mayoría de los fallos de parseo JSON en la práctica. Nuestro validador JSON los detecta todos e indica la línea y posición exactas:

Coma Final

El error más común. Fácil de introducir al añadir o eliminar el último elemento de un objeto o array:

// Inválido:
{"nombre": "Alicia", "edad": 30,}

// Válido:
{"nombre": "Alicia", "edad": 30}

Cadenas con Comillas Simples

Frecuente cuando los desarrolladores familiarizados con la sintaxis de Python o de objetos JavaScript escriben JSON a mano:

// Inválido:
{'nombre': 'Alicia'}

// Válido:
{"nombre": "Alicia"}

Claves Sin Comillas

Válido en JavaScript pero no en JSON:

// Inválido (literal de objeto JavaScript, no JSON):
{nombre: "Alicia"}

// JSON válido:
{"nombre": "Alicia"}

Comentarios

Copiados de ejemplos de configuración JSONC:

// Inválido:
{"puerto": 3000 // puerto de desarrollo
}

Corchete de Cierre Faltante

Especialmente común en estructuras anidadas. El mensaje de error del parser ("Final inesperado de la entrada") indica que la estructura nunca fue cerrada:

// Inválido:
{"usuario": {"nombre": "Alicia", "roles": ["admin", "editor"]}
// Falta la llave de cierre exterior

NaN e Infinity

Valores específicos de JavaScript que no tienen equivalente en JSON:

// JSON inválido (JavaScript válido):
{"ratio": NaN, "limite": Infinity}

// Alternativas válidas:
{"ratio": null, "limite": 1e308}

JSON vs Formatos Similares

JSON no es el único formato de datos. Elegir el formato correcto para un caso de uso requiere entender los compromisos:

JSON vs YAML

YAML es un superconjunto de JSON (cualquier JSON válido es YAML válido) y está diseñado para la autoría humana. YAML soporta comentarios, cadenas multilínea, referencias/anclas, y no requiere comillas para la mayoría de las cadenas. Usa indentación para la estructura en lugar de llaves y corchetes. YAML se prefiere para archivos de configuración (GitHub Actions, Kubernetes, Ansible) porque los humanos lo editan frecuentemente. JSON se prefiere para la comunicación API máquina a máquina porque su sintaxis estricta es más rápida de parsear y menos ambigua.

JSON vs XML

XML fue el formato de intercambio de datos dominante antes de JSON. XML soporta atributos, esquemas (XSD), espacios de nombres y contenido mixto. JSON es significativamente más compacto para los mismos datos: una representación XML de 2–3× más grande que JSON es habitual. JSON es más fácil de trabajar en JavaScript. XML sigue siendo prevalente en sistemas empresariales (servicios SOAP, formatos de documentos como DOCX/XLSX) e industrias que requieren su ecosistema de validación.

JSON vs TOML

TOML está diseñado específicamente para la configuración. Soporta comentarios, es más legible para configuraciones muy anidadas y maneja cadenas multilínea de forma natural. TOML no es adecuado para el intercambio de datos genérico y no tiene tanta compatibilidad como JSON.

JSON vs Protocol Buffers

Protocol Buffers (protobuf) es un formato de serialización binaria de Google. Los mensajes protobuf están definidos por esquema, son típicamente 3–10× más pequeños que JSON y más rápidos de serializar/deserializar. El compromiso: el formato binario no es legible por humanos, requiere archivos de esquema y generación de código, y es más difícil de depurar. Protobuf se prefiere para comunicación de microservicios internos de alto rendimiento; JSON para APIs públicas donde importan la legibilidad humana y el parseo independiente del lenguaje.

JSON5 y JSONC

JSON5 es un superconjunto de JSON que permite comentarios, comas finales, cadenas con comillas simples y cadenas multilínea. JSONC (JSON con comentarios) añade solo comentarios y comas finales. Ambos se usan en archivos de configuración de herramientas de desarrollo (tsconfig.json acepta JSONC). Ni JSON5 ni JSONC deben usarse en comunicación API — los parsers JSON estándar los rechazarán.

JSON en APIs: Convenciones y Cabeceras

Las APIs REST que intercambian JSON deben usar la cabecera Content-Type: application/json tanto en peticiones como en respuestas. Esto indica a los clientes y proxies el formato del cuerpo. Para las peticiones, también establece Accept: application/json para indicar el formato de respuesta esperado.

Durante el desarrollo y la depuración, el JSON bien formateado (con indentación y saltos de línea) es significativamente más fácil de leer. Para las respuestas de API en producción, el JSON minificado (sin espacios en blanco innecesarios) reduce el tamaño del payload. La diferencia puede ser del 20–30% del tamaño sin comprimir para respuestas API típicas. La mayoría de las APIs de producción aplican compresión gzip o brotli para todas las respuestas de texto, lo que en gran medida elimina la sobrecarga del espacio en blanco, pero la minificación también reduce el uso de memoria durante el parseo.

Usa nuestro formateador JSON para cambiar instantáneamente entre JSON embellecido y minificado, o para validar una respuesta de API durante la depuración.

Parsear JSON de Forma Segura

En JavaScript, la forma correcta de parsear JSON es JSON.parse(cadenaJson). Nunca uses eval(cadenaJson) — aunque técnicamente funciona para JSON válido, ejecuta código JavaScript arbitrario y es una vulnerabilidad de seguridad crítica si la cadena JSON proviene de una fuente no confiable.

JSON.parse() lanza un SyntaxError si la entrada no es JSON válido. Siempre envuélvelo en un try/catch cuando manejes datos externos:

try {
const datos = JSON.parse(cadenaRaw);
// usar datos
} catch (e) {
console.error("JSON inválido:", e.message);
}

El parámetro reviver de JSON.parse() permite transformar valores durante el parseo. Un caso de uso común es convertir cadenas de fecha ISO 8601 de vuelta a objetos Date de JavaScript:

JSON.parse(texto, (clave, valor) => {
if (typeof valor === "string" && /^\d{4}-\d{2}-\d{2}T/.test(valor)) {
return new Date(valor);
}
return valor;
})

Para números mayores que Number.MAX_SAFE_INTEGER, el JSON.parse() de JavaScript pierde precisión. Si tu API maneja enteros grandes (IDs de base de datos más allá de 2^53, cantidades financieras en satoshis), represéntalos como cadenas en JSON o usa una librería como json-bigint para un parseo BigInt correcto.

JSON Schema: Validar la Estructura, No Solo la Sintaxis

JSON Schema es un vocabulario para describir la estructura de los documentos JSON. Mientras que la validación de sintaxis JSON comprueba que el texto se puede parsear, la validación de JSON Schema comprueba que los datos parseados se ajustan a una forma esperada: los campos requeridos están presentes, los valores tienen los tipos correctos, las cadenas coinciden con patrones y los números están dentro de rangos.

Un JSON Schema mínimo para un objeto usuario:

{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"required": ["id", "email"],
"properties": {
"id": {"type": "integer", "minimum": 1},
"email": {"type": "string", "format": "email"},
"nombre": {"type": "string", "maxLength": 100}
},
"additionalProperties": false
}

JSON Schema es valioso para los contratos de API: el esquema describe exactamente qué acepta la API, las librerías de clientes pueden auto-validar peticiones y respuestas, y los pipelines de CI pueden aplicar la compatibilidad del esquema en cada build usando librerías como ajv (Node.js), jsonschema (Python) o Newtonsoft.Json.Schema (.NET).

Cómo Nuestro Formateador JSON Te Ayuda a Trabajar con JSON

Nuestro formateador y validador JSON gratuito proporciona tres funciones centrales que abordan las necesidades más comunes de trabajo con JSON:

  • Validación de sintaxis: Pega cualquier texto JSON y ve instantáneamente si es válido. Los mensajes de error incluyen el número de línea y el desplazamiento de carácter para un diagnóstico rápido. Los errores comunes como comas finales, comillas simples y corchetes faltantes se detectan y reportan claramente.
  • Embellecido: Convierte JSON minificado o en una sola línea en una forma indentada y legible por humanos. Esencial al depurar respuestas de API comprimidas o al leer archivos de configuración generados por máquinas.
  • Minificado: Elimina todos los espacios en blanco para producir la representación JSON más compacta. Útil antes de incrustar JSON en un archivo JavaScript, almacenarlo en una columna de base de datos o enviarlo como parámetro de URL.

Todo el procesamiento ocurre completamente en tu navegador — los datos JSON nunca abandonan tu máquina. No se requiere cuenta y no hay límites de tamaño de archivo.

← Volver al Blog