JSON (JavaScript Object Notation) es un formato ligero, basado en texto, para almacenar e intercambiar datos estructurados. Se construye con objetos de pares clave/valor, arrays ordenados y un puñado de tipos de valor: cadenas, números, true, false y null. Es el formato por defecto de las API web y de muchos archivos de configuración porque las personas lo leen con facilidad y cualquier lenguaje de programación lo analiza sin esfuerzo. JSON es estricto: las claves y las cadenas necesitan comillas dobles, y no se permiten comas finales ni comentarios.
- JSON tiene exactamente seis tipos de valor: objeto, array, cadena, número, booleano (
true/false) ynull. - Las claves deben ser cadenas entre comillas dobles; las comillas simples nunca son válidas.
- Sin comas finales, sin comentarios, sin
undefined,NaNniInfinity. - La mayoría de los errores de «JSON no válido» vienen de una coma que falta o sobra, unas comillas incorrectas o un carácter sin escapar dentro de una cadena.
- Valida primero la sintaxis con un analizador estricto y, si hace falta, valida después la estructura con JSON Schema.
Qué aspecto tiene JSON
JSON nació de la sintaxis que usa JavaScript para los literales de objeto, pero es independiente del lenguaje. Está definido en la RFC 8259 y en el estándar ECMA-404, y el resumen de una página de json.org describe toda la gramática. Un documento típico tiene este aspecto:
{
"id": 1042,
"name": "Ada Lovelace",
"email": "ada@example.com",
"active": true,
"score": 98.5,
"manager": null,
"roles": ["admin", "editor"],
"address": {
"city": "London",
"postcode": "N1 9GU"
}
}Los espacios en blanco entre elementos (espacios, tabuladores y saltos de línea) se ignoran, así que los mismos datos pueden escribirse en una sola línea o repartirse con sangría. El nivel superior de un documento JSON puede ser cualquier valor, aunque las API casi siempre usan un objeto o un array.
Tipos de datos de JSON
| Tipo | Ejemplo | Reglas |
|---|---|---|
| Objeto | {"a": 1, "b": 2} | Conjunto desordenado de pares clave/valor entre llaves. Las claves son cadenas; dos puntos separan la clave del valor; comas separan los pares. |
| Array | [1, "two", false] | Lista ordenada de valores entre corchetes, separados por comas. Los valores pueden ser de tipos mezclados. |
| Cadena | "caf\u00e9 \"quoted\"" | Solo comillas dobles. Secuencias de escape con barra invertida: \" \\ \/ \b \f \n \r \t y \uXXXX. No se permiten saltos de línea ni tabuladores literales dentro de las cadenas. |
| Número | -12, 3.14, 6.02e23 | Solo decimal. Sin + inicial, sin ceros a la izquierda (07), sin hexadecimal, sin NaN ni Infinity. Un punto decimal debe tener dígitos a ambos lados. |
| Booleano | true, false | En minúsculas y sin comillas. |
| Nulo | null | En minúsculas y sin comillas. Representa un valor vacío o desconocido. |
No existe un tipo fecha. Las fechas suelen escribirse como cadenas en formato ISO 8601, como "2026-10-13T09:30:00Z", o como timestamps de Unix en números; nuestro conversor de timestamp Unix traduce de uno a otro.
Números y precisión
El estándar JSON no limita el tamaño ni la precisión de los números, pero los programas que lo leen sí. JavaScript almacena los números como valores de coma flotante de 64 bits, así que los enteros mayores que 9.007.199.254.740.991 (253 − 1) pueden perder precisión sin avisar. Para los ID grandes, muchas API los envían como cadenas, por ejemplo "id": "1234567890123456789".
Las reglas con las que se tropieza todo el mundo
JSON se parece a JavaScript, a los diccionarios de Python y a YAML, y por eso mismo la gente escribe JSON no válido sin querer. Estas reglas no tienen excepciones en el JSON estándar:
- Las claves deben ser cadenas entre comillas dobles.
{name: "Ada"}es JavaScript válido pero JSON no válido; escribe{"name": "Ada"}. - Solo comillas dobles.
'Ada'no es una cadena JSON. - Sin comas finales.
[1, 2, 3,]y{"a": 1,}no son válidos. - Sin comentarios. No se permite ni
// ...ni/* ... */. - Los valores literales van en minúsculas.
True,FALSEyNone(la grafía de Python) no son válidos; usatrue,falseynull. - Sin
undefined, funciones ni números especiales. Existen en JavaScript pero no tienen equivalente en JSON. - Las claves deberían ser únicas. El estándar dice que los nombres dentro de un objeto deberían ser únicos; con duplicados, los analizadores se comportan de forma distinta y muchos conservan en silencio solo el último.
Algunas herramientas aceptan variantes relajadas. Archivos como el settings.json de VS Code y el tsconfig.json de TypeScript se leen con analizadores que permiten comentarios (a menudo llamados JSONC), y JSON5 permite comentarios, comillas simples y comas finales. Son formatos distintos: un analizador de JSON estándar, incluido el que usa tu cliente de API o tu servidor, los rechazará.
Errores comunes de JSON y cómo corregirlos
El texto de los errores cambia de un analizador a otro. La tabla muestra el tipo de mensaje que verás en el módulo json de Python o en el JSON.parse de un navegador, lo que suele significar y cómo solucionarlo. La posición que se indica suele apuntar justo después del fallo real, así que mira también el carácter anterior.
| Problema | Mensaje de error típico | Solución |
|---|---|---|
Coma final: {"a": 1,} | "Expecting property name enclosed in double quotes" o "Unexpected token }" | Borra la coma después del último elemento del objeto o del array. |
Clave sin comillas o con comillas simples: {a: 1}, {'a': 1} | "Expecting property name enclosed in double quotes" o "Expected double-quoted property name" | Pon todas las claves entre comillas dobles. |
Valor de cadena con comillas simples: {"a": 'x'} | "Expecting value" o "Unexpected token '" | Usa comillas dobles y escapa como \" las comillas dobles que haya dentro. |
| Falta una coma entre elementos | "Expecting ',' delimiter" o "Expected ',' or '}' after property value" | Añade una coma entre los dos valores o pares de la línea indicada. |
| Comentario en el archivo | "Expecting value" o "Unexpected token /" | Quita el comentario o pasa la nota a un campo de datos como "_comment". |
Literales de Python o JavaScript: True, None, undefined, NaN | "Expecting value" o "Unexpected token" | Usa true, false o null; serializa los datos con una biblioteca JSON de verdad en lugar de imprimirlos. |
| Salto de línea o tabulador literal dentro de una cadena | "Invalid control character" o "Bad control character in string literal" | Sustitúyelo por \n o \t. |
Barra invertida sin escapar, como una ruta de Windows "C:\new" | "Invalid \escape" o "Bad escaped character" | Duplica las barras invertidas: "C:\\new". |
| Falta un corchete o unas comillas de cierre | "Unterminated string" o "Unexpected end of JSON input" | Comprueba que cada {, [ y " esté cerrado; la sangría de un formateador deja el hueco a la vista. |
| Dos documentos seguidos o texto después del final | "Extra data" o "Unexpected non-whitespace character after JSON" | Envuelve varios objetos en un array o procesa la entrada como JSON Lines (un documento por línea). |
| Respuesta vacía o página de error HTML analizada como JSON | "Expecting value: line 1 column 1" o "Unexpected token <" | Revisa el estado HTTP y el cuerpo de la respuesta; el servidor devolvió algo que no es JSON. |
La última fila es una de las más frecuentes en la práctica: el código llama a JSON.parse o a response.json() sobre una página de error que empieza con <!DOCTYPE html>, y el < se notifica como un token inesperado.
JSON frente a YAML y XML
| JSON | YAML | XML | |
|---|---|---|---|
| Estructura | Llaves y corchetes | Sangría | Etiquetas de apertura y cierre |
| Comentarios | No | Sí (#) | Sí (<!-- -->) |
| Tipos de datos | Cadena, número, booleano, null, objeto, array | Similares, más fechas y otros tipos según el analizador | Todo es texto salvo que un esquema asigne tipos |
| Atributos y contenido mixto | No | No | Sí |
| Verbosidad | Compacto | El más compacto a la vista | El más verboso |
| Usos típicos | API web, almacenamiento del navegador, manifiestos de paquetes, registros | Configuración: Kubernetes, Docker Compose, pipelines de CI | Documentos, SOAP, RSS y Atom, sitemaps, formatos de archivos ofimáticos |
| Principales trampas | Comillas y comas estrictas | Sensible a los espacios; algunos valores sin comillas se interpretan de forma inesperada | Verboso; los espacios de nombres y las entidades añaden complejidad |
YAML 1.2 se diseñó para que los documentos JSON sean, salvo casos límite poco frecuentes, también YAML válido, lo que hace sencillo convertir de uno a otro. Nuestro conversor JSON ↔ YAML funciona en ambas direcciones, el formateador y validador de YAML y el formateador y validador de XML validan los otros dos formatos, y el conversor CSV ↔ JSON convierte las exportaciones de hojas de cálculo en arrays de objetos.
Formatear y minificar
Como los espacios en blanco no son significativos, el mismo JSON puede formatearse para personas o para máquinas:
- El JSON formateado añade saltos de línea y sangría, normalmente de dos o cuatro espacios, para que se vea el anidamiento. Úsalo en archivos de configuración, documentación y depuración.
- El JSON minificado elimina todos los espacios opcionales para reducir el tamaño de los datos. Úsalo en datos que se envían por la red o se almacenan en grandes cantidades; la compresión HTTP también reduce el tamaño, así que el ahorro suele ser modesto.
{"name":"Ada","roles":["admin","editor"],"active":true}La mayoría de los lenguajes pueden hacer ambas cosas. En JavaScript, JSON.stringify(data, null, 2) formatea con sangría de dos espacios y JSON.stringify(data) minifica. En Python, json.dumps(data, indent=2) formatea y json.dumps(data, separators=(",", ":")) da la salida más compacta.
Cómo validar JSON
Validar JSON tiene dos niveles: si es JSON sintácticamente válido, y si tiene la estructura que espera tu aplicación.
- Comprueba la sintaxis con un analizador estricto. Pega el texto en nuestro formateador y validador de JSON, que indica la línea y la columna del primer error y funciona en tu navegador. En la línea de comandos,
python3 -m json.tool data.jsonojq . data.jsonmuestra el documento formateado o un error. - Corrige los errores de uno en uno. Un analizador se detiene en el primer problema, así que vuelve a ejecutarlo tras cada corrección hasta que termine bien.
- Comprueba la estructura. Confirma que existen los campos obligatorios y que tienen el tipo correcto, ya sea en el código o con un validador de JSON Schema.
- Comprueba la codificación. El JSON que se intercambia entre sistemas debería estar en UTF-8. Un archivo guardado con otra codificación puede producir caracteres extraños o errores con texto que no esté en inglés.
JSON Schema en breve
JSON Schema es un vocabulario, escrito en el propio JSON, para describir cómo es un documento válido: qué propiedades son obligatorias, de qué tipo debe ser cada una, qué valores se permiten, patrones de cadena, rangos numéricos, etc. Hay validadores para la mayoría de los lenguajes, y formatos de descripción de API como OpenAPI usan JSON Schema para describir los cuerpos de las peticiones y las respuestas. La especificación se publica en json-schema.org. Un ejemplo pequeño:
{
"$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" },
"roles": { "type": "array", "items": { "type": "string" } }
}
}Un documento sin email o con un id en forma de cadena sería JSON válido, pero no pasaría este esquema. Ten en cuenta que muchos validadores tratan format como una anotación y no la aplican a menos que se configuren para ello.
Preguntas frecuentes
¿Puede JSON tener comentarios?
No. El JSON estándar no admite comentarios de ningún tipo. Algunas herramientas aceptan JSONC o JSON5, que sí los permiten, pero los archivos destinados a ser leídos por otros programas deberían ceñirse al JSON simple. Si necesitas una nota, añade un campo como "_comment".
¿Por qué JSON no permite comas finales?
La gramática se mantuvo deliberadamente mínima y sencillamente no las incluye. Muchos motores de JavaScript y otros lenguajes aceptan comas finales en su propia sintaxis, y por eso aparecen a menudo por error en JSON escrito a mano.
¿Qué diferencia hay entre JSON y un objeto de JavaScript?
JSON es un formato de texto; un objeto de JavaScript es una estructura de datos en memoria. La sintaxis de JSON es un subconjunto más estricto de la sintaxis de literales de JavaScript. Se convierte de uno a otro con JSON.parse y JSON.stringify.
¿Qué significa «Unexpected token < in JSON at position 0»?
El texto que se está analizando empieza por <, lo que casi siempre significa que has recibido HTML, como una página de error o de inicio de sesión, en lugar de JSON. Revisa la URL de la petición, el código de estado HTTP y el cuerpo en bruto de la respuesta.
¿Se conserva el orden de las claves en un objeto JSON?
El estándar trata los objetos como desordenados, así que no debes confiar en el orden de las claves. En la práctica, la mayoría de los analizadores modernos conservan el orden en que las leen, pero el orden de los arrays es el único que JSON garantiza.
¿Qué extensión de archivo y tipo MIME usa JSON?
Los archivos usan la extensión .json y el tipo de medio es application/json, tal como está registrado en la RFC 8259.