¿Qué es un archivo JSON?

JSON es un formato de texto plano que se abre en cualquier editor. Se usa para mover datos entre programas y la web.

La extensión es .json y el nombre completo, JavaScript Object Notation. Ambos importan menos que lo que el archivo puede contener, y de eso trata el resto de esta página.

Se remonta a 2001. La especificación es RFC 8259.

La edad interesa por un motivo práctico: cuanto más antiguo es un formato, más programas han tenido tiempo de aprenderlo.

Está publicada entera, así que cualquiera puede implementarla leyendo el documento en vez de a base de inspeccionar archivos. Por eso aparece en tantos programas, y por eso los archivos escritos hace veinte años siguen abriéndose hoy. Publicada no quiere decir libre de regalías: cuando un formato envuelve un códec, la licencia de las patentes es un asunto aparte que la norma no resuelve.

JSON guarda su contenido exactamente. Volver a guardarlo no cambia nada, así que puedes abrirlo, editarlo y guardarlo tantas veces como quieras sin acumular daño; eso es lo que lo convierte en un formato de trabajo y no de entrega.

JSON no tiene sintaxis de comentarios. Todo lo explicativo tiene que vivir fuera del archivo, y conviene saberlo antes de elegirlo para algo que una persona vaya a editar a mano.

Visual Studio Code, jq y Postman lo leen, y también la mayoría de programas del mismo tipo.

Cuando un archivo no se abre, el formato rara vez es el problema: lo más habitual es que el programa sea anterior al formato. Convertir a algo más antiguo es la salida fiable, y para eso está el resto de este sitio.

Cualquier navegador actual lo lee.

Eso lo convierte en algo que puedes poner en una página o adjuntar a un mensaje sin preguntarte qué tiene instalado el otro lado.

JSON está pensado para abrirse y cambiarse. Guarda el archivo en este formato mientras el trabajo siga en marcha y exporta desde él cada vez que haga falta una copia terminada.

Un documento JSON se construye con objetos, listas, cadenas, números, booleanos y nulo. Ese es el vocabulario entero, y la brevedad de la lista es la razón de que el formato se impusiera: todos los lenguajes de programación tienen ya los seis, así que leer un documento consiste en llamar a una función y recibir valores nativos sin nada que traducir.

La especificación cabe en unas pocas páginas. Se describió más que se diseñó —Douglas Crockford tomó la sintaxis de literales de objeto que JavaScript ya tenía y escribió lo que ya funcionaba—, y por eso resulta evidente en lugar de ingenioso.

JSON no tiene comentarios, deliberadamente, y es la propiedad del formato de la que más se queja todo el mundo. El razonamiento fue que los comentarios acaban invitando a meter directivas para el analizador, y el resultado es que JSON es un mal lenguaje de configuración por muy bueno que sea como formato de intercambio.

Circulan tres apaños. Una clave llamada algo así como guion bajo más «comentario», que cualquier analizador acepta y cualquier validador de esquema rechaza. JSON5 y JSONC, que añaden comentarios y comas finales y no son JSON: el archivo de ajustes de Visual Studio Code es JSONC, y por eso una herramienta estricta lo rechaza. Y la respuesta honesta, que es usar TOML o YAML para todo lo que mantenga una persona.

JSON no distingue enteros de decimales. Casi todos los analizadores leen cada número como un doble, y un doble representa enteros de forma exacta solo hasta unos nueve mil billones.

Por encima de esa cifra los valores cambian en silencio. Un identificador de base de datos de 64 bits, un identificador tipo copo de nieve, un importe grande expresado en céntimos: cualquiera puede volver siendo un número distinto del que se envió, sin que nadie dé un error. El remedio es enviar esos valores como cadenas, que es lo que hace toda API seria, y conviene comprobarlo en lugar de suponerlo al integrarse con una que quizá no lo haga.

Las claves duplicadas no están prohibidas. Los analizadores no coinciden en qué hacer con ellas —la mayoría se queda con la última, algunos con la primera, unos pocos dan error—, y un documento que dependa de cualquiera de esas conductas depende de una implementación y no de JSON.

El orden de las claves tampoco está garantizado, así que tratar un objeto como una estructura ordenada es un error: si el orden importa, la respuesta es una lista. Y no hay fechas: la convención universal son cadenas en ISO 8601, y todo analizador te devuelve un texto que algo más tiene que interpretar. En este sitio el orden sí se conserva en todas las conversiones de datos, porque nada ordena por el camino, pero eso es una propiedad de este conversor y no una promesa del formato.

JSON es UTF-8. La especificación lo dice para todo lo que se intercambie entre sistemas, y el corolario práctico es que no se admite marca de orden de bytes: esos tres bytes invisibles al principio del archivo provocan un fallo de análisis cuyo mensaje suele culpar al primer carácter en vez de nombrar la causa.

Si un JSON no se analiza y en el editor se ve perfecto, eso es lo primero que hay que mirar. El ajuste se llama «UTF-8 sin BOM», y es el mismo consejo que para cualquier otro formato de texto, con la diferencia de que aquí es directamente mortal en lugar de simplemente molesto.

Un documento JSON tiene que estar completo antes de poder analizarse —el corchete de cierre es lo que lo hace válido—, así que una lista de diez gigabytes de registros hay que leerla entera en memoria antes de tener disponible el primero. Para exportaciones grandes y para tuberías de registros eso es fatal.

NDJSON, también llamado JSON Lines, lo resuelve poniendo un objeto JSON completo en cada línea, sin lista alrededor. Cada línea se analiza por su cuenta, de modo que un archivo de cualquier tamaño se procesa fila a fila y el trabajo empieza con el primer registro. Las exportaciones de datos, el envío de registros y los conjuntos de datos para aprendizaje automático lo usan casi siempre, y es a lo que hay que recurrir en cuanto un JSON se mide en gigabytes.

JSON Schema es la forma estándar de describir cómo es un documento válido, y merece la pena en cualquier interfaz entre dos sistemas: convierte «la API ha devuelto algo raro» en un error concreto que nombra el campo. El soporte es bueno y menos uniforme que el equivalente de XML.

Para el día a día, un editor con soporte de JSON regala la mitad importante: una coma que falta o una que sobra se señala en el sitio, y un JSON generado por una máquina que llegó como una línea larguísima se puede reformatear hasta hacerlo legible. Son dos operaciones de segundos que ahorran un tiempo sorprendente.

Depende del destino, y la diferencia es grande. Hacia YAML, TOML, XML o NDJSON el árbol se conserva tal cual: son formatos que saben anidar. Hacia CSV, TSV, XLSX, Parquet, INI o SQL no hay dónde meterlo, así que la estructura se aplana en una columna por cada hoja del árbol, y el nombre de la columna es la ruta con puntos, con los índices de las listas como un tramo más de esa ruta. Un objeto de tres niveles sale como una tabla ancha con encabezados largos, lo cual es la lectura correcta de un árbol en una tabla, pero no es lo que espera quien nunca ha visto el resultado.

Dos detalles más al salir. Los comentarios no sobreviven a ningún formato de configuración —ni YAML, ni TOML, ni INI, ni XML los conservan—, así que si el JSON venía de convertir un archivo comentado, ese texto ya no está. Y la salida SQL son únicamente sentencias `INSERT INTO`: no hay `CREATE TABLE`, no hay tipos declarados, el nombre de la tabla se saca del nombre del archivo y los booleanos se escriben `TRUE` y `FALSE`, que no vale en todos los dialectos. Es material para cargar en una tabla que ya existe, no un volcado completo. Todo esto ocurre dentro del navegador, con un tope de 100 MB por archivo y sin que el JSON se suba a ninguna parte.