JSON explicado paso a paso: guía práctica con ejemplos

Qué es JSON y de dónde viene

JSON son las siglas de JavaScript Object Notation. Es un formato ligero de intercambio de datos, legible por humanos y fácil de parsear por máquinas. Lo propuso Douglas Crockford a principios de los 2000 como alternativa a XML, que por aquel entonces era el estándar de facto para comunicación entre sistemas. El planteamiento era simple: aprovechar la sintaxis de objetos de JavaScript para representar datos estructurados sin necesidad de etiquetas de apertura y cierre.

Veinticinco años después, JSON es el formato dominante en prácticamente todas las APIs REST modernas, en la configuración de miles de herramientas (package.json, tsconfig.json, VS Code settings…), en bases de datos NoSQL (MongoDB, CouchDB) y como formato de intercambio entre sistemas completamente distintos (un backend en Go puede enviar JSON a un frontend en React y ambos se entienden sin problemas).

La sintaxis de JSON en una página

A diferencia de XML, que tiene decenas de reglas, JSON cabe en una explicación corta. Solo existen seis tipos de datos:

• Objeto: colección no ordenada de pares clave-valor, delimitada por llaves {}. Las claves son siempre cadenas entre comillas dobles.
• Array: lista ordenada de valores, delimitada por corchetes [].
• Cadena (string): texto entre comillas dobles. Soporta escapes como \n (salto de línea), \t (tabulación), \\ (barra invertida) y \u00E9 (Unicode).
• Número: entero o decimal. No hay distinción entre int, float o long como en otros lenguajes.
• Booleano: true o false.
• Null: null.

Un ejemplo completo que combina todos los tipos:

{
  "usuario": {
    "nombre": "Laura",
    "edad": 34,
    "activo": true,
    "intereses": ["fotografía", "cine", "ajedrez"],
    "direccion": {
      "calle": "Gran Vía, 21",
      "ciudad": "Madrid",
      "codigo_postal": "28013"
    },
    "ultimo_login": null
  }
}

Tres cosas que mucha gente se salta y luego provoca errores:

• Las claves deben estar entre comillas dobles, nunca simples. { 'nombre': 'Laura' } no es JSON válido, aunque sí es un objeto JavaScript válido.
• No se permiten comas finales (trailing commas). Este JSON es inválido: [1, 2, 3,]. JavaScript lo acepta, JSON no.
• No admite comentarios. Ni // ni /* */. Si tu archivo tiene comentarios, no es JSON estándar (es JSON5, JSONC o similar).

Por qué JSON se impuso a XML

A principios de los 2000, todo el mundo usaba XML para APIs. Un request típico a un servicio SOAP podía verse así:

<soap:Envelope>
  <soap:Body>
    <GetUser>
      <UserId>42</UserId>
    </GetUser>
  </soap:Body>
</soap:Envelope>

Y la respuesta, con varios niveles de anidación y namespaces, solía ser el doble de larga. Esa verbosidad tenía un coste real: más ancho de banda, más lentitud de parseo y más dificultad de depuración.

JSON resolvía los tres problemas a la vez:

• Menos bytes: el ejemplo de arriba en JSON cabe en {"get_user":{"user_id":42}}.
• Parseo nativo en JavaScript: cualquier navegador puede ejecutar JSON.parse(respuesta) y ya tienes un objeto listo para usar. Con XML había que recorrer el DOM manualmente.
• Menos ambigüedad: no hay atributos vs elementos, no hay CDATA, no hay decisiones sobre si algo debe ser Laura o .

Hoy XML sigue teniendo nicho en documentos muy estructurados (documentos legales, formatos editoriales, configuraciones de Java/Maven), pero para APIs web y comunicación entre servicios JSON es la opción por defecto indiscutible.

Los errores más habituales al trabajar con JSON

Cuando la gente empieza a trabajar con JSON en APIs reales, estos son los tropezones más frecuentes:

1. Usar comillas simples en lugar de dobles

JavaScript acepta { nombre: 'Laura' } sin problema. JSON no. Cualquier parser estricto (y todos lo son) fallará con un error del tipo "Unexpected token". Regla: siempre comillas dobles, tanto en claves como en valores de cadena.

2. Olvidar escapar caracteres especiales

Si necesitas incluir una comilla doble dentro de una cadena, tienes que escaparla con barra invertida:

{ "cita": "Él dijo \"hola\" en voz baja" }

Lo mismo ocurre con saltos de línea (\n), tabulaciones (\t) y la propia barra invertida (\\). Cuando generas JSON a mano es fácil olvidarse; cuando lo generas con JSON.stringify() en código, el lenguaje lo hace automáticamente.

3. Comas finales

Este error te lo va a marcar cualquier linter decente:

{
  "items": [
    "manzana",
    "pera",
    "naranja",     ← ❌ coma sobrante
  ]
}

JavaScript lo aceptaría, JSON no. Si trabajas con un archivo JSON y tu editor muestra un error al final del array o del objeto, mira si hay una coma sobrante.

4. Codificación incorrecta

JSON debe estar siempre en UTF-8. Si tu archivo se guarda en Latin-1 o Windows-1252, las ñ, las tildes y los emojis se corromperán. En editores modernos (VS Code, Sublime, Zed) puedes ver y cambiar la codificación en la barra inferior.

5. Duplicar claves

JSON no prohíbe explícitamente duplicar claves en el mismo nivel, pero el comportamiento queda indefinido: unos parsers cogen la primera, otros la última. Evítalo siempre:

{ "total": 100, "total": 200 }   ← ⚠️ ambiguo

Cómo validar y formatear JSON sin salir del navegador

El ciclo habitual de trabajo con JSON es: copias un texto, no sabes si es válido, lo pegas en algún sitio para formatearlo, lo revisas, lo corriges, lo vuelves a usar. Ese flujo tradicionalmente implica usar servicios online que suben tu texto a un servidor para procesarlo.

En GarTools este paso se hace completamente en el navegador, lo cual es importante cuando el JSON contiene datos sensibles: tokens de API, respuestas con información personal de clientes, configuraciones internas, dumps de bases de datos.

• El validador de JSON analiza la estructura línea por línea y te indica exactamente en qué fila y columna está el error con un mensaje en castellano ("se esperaba una coma", "cadena sin cerrar", "clave duplicada").
• El formateador de JSON toma un JSON minificado (típicamente una sola línea muy larga) y lo reformatea con indentación de 2 o 4 espacios, ordenando claves alfabéticamente si lo necesitas. También permite el proceso inverso: minificar un JSON indentado para enviarlo por la red.

Ambas herramientas aceptan archivos de hasta varios megabytes sin bloquear la UI del navegador.

Conversión entre JSON y otros formatos

Otro flujo muy común es pasar de JSON a CSV (para abrirlo en Excel) o de CSV a JSON (para alimentar una API). Las herramientas de conversión de GarTools resuelven ambos casos:

• JSON → CSV: útil cuando tienes una respuesta de API con una lista de objetos y quieres abrirla en Excel o Google Sheets para hacer análisis rápido. La herramienta detecta los campos automáticamente y los convierte en columnas.
• CSV → JSON: útil cuando tienes un export de CRM en CSV y necesitas alimentar un endpoint REST que espera JSON. La herramienta soporta separadores por comas y punto y coma (importante en España), detecta cabeceras automáticamente y respeta los tipos de datos cuando son obvios (números, booleanos).

Ambos procesos son bidireccionales sin pérdida: puedes hacer JSON → CSV → JSON y obtener exactamente lo mismo que tenías al principio, siempre que el CSV no contenga estructuras anidadas (porque CSV es plano por definición).

Cuándo NO usar JSON

A pesar de ser muy versátil, JSON no es siempre la mejor opción. Hay casos donde otros formatos funcionan mejor:

• Configuración con comentarios: usa JSONC (con comentarios), YAML o TOML.
• Datos tabulares masivos: CSV es más compacto y se procesa en streaming.
• Datos binarios eficientes: Protocol Buffers, MessagePack o CBOR son órdenes de magnitud más compactos.
• Documentos con estructura compleja: XML sigue siendo mejor para documentos editoriales y formatos donde el orden y los atributos importan.

Pero para el 90 % de las APIs y la mayoría de los intercambios entre aplicaciones modernas, JSON es y seguirá siendo la elección correcta.

Conclusión

JSON es un formato pequeño en superficie y enorme en impacto. Dominarlo consiste en: entender sus seis tipos de datos, respetar las reglas estrictas de sintaxis (comillas dobles, sin comas finales, sin comentarios) y tener a mano un par de herramientas para validar y formatear cuando algo se rompa. Con el formateador, el validador y los conversores de GarTools, ese flujo cabe en cuatro clics y nada sale nunca de tu equipo.