Si trabajas con APIs, configuraciones, exportaciones de datos o automatizaciones, te encontrarás con JSON a diario. Es un formato de texto ligero que representa datos estructurados con objetos y listas, legible tanto para personas como para máquinas. Sus reglas son pocas, pero el analizador no perdona: una comilla simple o una coma sobrante invalidan todo el archivo. En esta guía tienes la sintaxis completa, los errores más comunes y cómo convertir entre JSON y CSV.
Sintaxis básica
Un documento JSON es un único valor, normalmente un objeto o un array:
{
"nombre": "Lucía Fernández",
"edad": 34,
"activa": true,
"ciudad": "Valencia",
"idiomas": ["español", "inglés"],
"direccion": {
"calle": "Calle Mayor 12",
"cp": "46001"
},
"telefono": null
}Reglas:
- Los objetos van entre llaves
{}y contienen pares"clave": valorseparados por comas. - Los arrays van entre corchetes
[]y contienen valores separados por comas. - Las claves son siempre cadenas entre comillas dobles.
- No hay coma después del último elemento.
Tipos de datos
| Tipo | Ejemplo | Notas |
|---|---|---|
| Cadena | "Hola" |
Solo comillas dobles; escapes con \ |
| Número | 42, -3.5, 1.2e3 |
Punto decimal, sin ceros a la izquierda, sin NaN ni Infinity |
| Booleano | true, false |
En minúsculas |
| Nulo | null |
En minúsculas |
| Objeto | {"a": 1} |
Claves únicas recomendadas |
| Array | [1, 2, 3] |
Puede mezclar tipos |
No hay tipo fecha: las fechas se guardan como cadenas, idealmente en formato ISO 8601 ("2026-10-08T10:30:00Z"), o como número Unix. La guía de Unix timestamp explica la segunda opción.
Ojo con los decimales: aunque en español se use coma decimal, en JSON el separador es siempre el punto: "precio": 19.99, nunca 19,99.
Caracteres especiales en cadenas
{ "texto": "Dijo \"hola\" y se fue.\nSegunda línea", "ruta": "C:\\datos\\archivo.txt" }Se escapan \", \\, \n (salto de línea), \t (tabulador) y caracteres Unicode con \u00F1 (ñ). Las tildes y la ñ pueden escribirse directamente si el archivo está en UTF-8.
Los errores más comunes
| Error | Incorrecto | Correcto |
|---|---|---|
| Coma final | {"a": 1, "b": 2,} |
{"a": 1, "b": 2} |
| Comillas simples | {'a': 'x'} |
{"a": "x"} |
| Clave sin comillas | {a: 1} |
{"a": 1} |
| Coma decimal | {"precio": 9,99} |
{"precio": 9.99} |
| Comentarios | {"a": 1 // nota} |
Eliminar el comentario |
undefined o NaN |
{"x": undefined} |
{"x": null} |
| Falta una coma | {"a": 1 "b": 2} |
{"a": 1, "b": 2} |
| Comillas tipográficas | {“a”: 1} |
{"a": 1} |
Las comillas tipográficas (“ ”) aparecen al copiar desde Word, correos o chats. Son invisibles a simple vista y rompen el archivo.
Validar y formatear
Un JSON minificado ocupa una sola línea y es ilegible. El formateador de JSON lo indenta, lo valida y señala la línea exacta del error. Úsalo para:
- Revisar la respuesta de una API.
- Encontrar la coma que falta en un archivo de configuración.
- Minificar el JSON antes de enviarlo para ahorrar bytes.
En la línea de comandos, jq hace lo mismo:
cat datos.json | jq .JSON frente a CSV
| Característica | JSON | CSV |
|---|---|---|
| Estructura | Anidada (objetos dentro de objetos) | Plana (filas y columnas) |
| Tipos de datos | Cadena, número, booleano, nulo | Todo es texto |
| Tamaño | Más grande (repite claves) | Más compacto |
| Uso típico | APIs, configuración, NoSQL | Hojas de cálculo, exportaciones |
Un mismo dato en ambos formatos:
[{"nombre": "Ana", "ciudad": "Bogotá"}, {"nombre": "Luis", "ciudad": "Lima"}]nombre,ciudad
Ana,Bogotá
Luis,LimaPara pasar de uno a otro, usa el conversor de CSV a JSON. Recuerda que en España y en muchos países latinoamericanos Excel usa punto y coma como separador de CSV, porque la coma es el separador decimal; revisa el delimitador al importar.
JSON en la web
- APIs REST devuelven JSON con la cabecera
Content-Type: application/json. - Datos estructurados: Google recomienda JSON-LD para el marcado schema; lo explicamos en la guía de datos estructurados.
- Configuración:
package.json,composer.jsonomanifest.json. - Tokens JWT: su contenido es JSON codificado en Base64URL; puedes inspeccionarlo con el decodificador JWT.
Leer JSON en distintos lenguajes
Casi todos los lenguajes incluyen un analizador de JSON:
// JavaScript
const datos = JSON.parse('{"ciudad": "Sevilla", "habitantes": 684000}');
const texto = JSON.stringify(datos, null, 2); // con sangría de 2 espacios# Python
import json
datos = json.loads('{"ciudad": "Sevilla", "habitantes": 684000}')
texto = json.dumps(datos, ensure_ascii=False, indent=2)En Python, ensure_ascii=False evita que la ñ y las tildes se conviertan en secuencias ñ. Si el analizador lanza un error, el mensaje suele indicar la línea y la columna: busca justo antes de esa posición, porque el fallo (una coma o una comilla) suele estar en el carácter anterior.
JSON grande y JSON Lines
Para millones de registros, cargar un único array gigante en memoria es lento. El formato JSON Lines (.jsonl) guarda un objeto por línea, de modo que se puede procesar línea a línea y añadir registros sin reescribir el archivo. Es habitual en exportaciones de logs y en conjuntos de datos.
Buenas prácticas
- Usa UTF-8 siempre.
- Elige un estilo de claves y mantenlo (
camelCaseosnake_case). - Guarda fechas en ISO 8601 con zona horaria.
- No guardes importes de dinero como decimales flotantes si necesitas exactitud: usa céntimos enteros o cadenas.
- Valida antes de desplegar cualquier archivo de configuración.