Mejores prácticas de formato JSON

JSON (JavaScript Object Notation) se ha convertido en el estándar de facto para el intercambio de datos en la Web. Las APIs devuelven JSON, los archivos de configuración usan JSON e incluso las bases de datos almacenan documentos JSON. A pesar de su simplicidad, JSON tiene reglas de sintaxis estrictas que son fáciles de violar, y un JSON mal formateado conduce a errores de depuración difíciles, problemas de rendimiento y vulnerabilidades de seguridad. Esta guía cubre todo lo que necesitas saber sobre el formato correcto de JSON, desde la sintaxis básica hasta temas avanzados como la validación con Schema y el manejo de archivos grandes.

¿Qué es JSON?

JSON es un formato de intercambio de datos ligero y basado en texto, derivado de la sintaxis literal de objetos de JavaScript. Fue especificado por Douglas Crockford a principios de los años 2000 y estandarizado como ECMA-404 y RFC 8259. Los objetivos de diseño de JSON son la simplicidad, la legibilidad humana y la facilidad de implementación en todos los lenguajes de programación. Hoy en día, todos los principales lenguajes de programación incluyen soporte JSON incorporado.

JSON soporta seis tipos de datos: cadenas (comillas dobles), números (enteros y de punto flotante), booleanos (true y false), null, objetos (colecciones no ordenadas de clave-valor) y arrays (listas ordenadas). No soporta nativamente comentarios, fechas, datos binarios o valores undefined.

Reglas de sintaxis JSON

JSON tiene una sintaxis que debe seguirse estrictamente. Incluso un error de un solo carácter puede causar que todo el documento falle al analizarse. Comprender estas reglas previene los errores de formato más comunes.

Las cadenas deben usar comillas dobles

Todos los valores de cadena y las claves de objeto deben estar entre comillas dobles. Las comillas simples no son un delimitador de cadena JSON válido. Este es uno de los errores más comunes de los desarrolladores que vienen de JavaScript, donde las comillas simples y dobles son intercambiables.

// Invalid - single quotes
{'name': 'Alice', 'age': 30}

// Valid - double quotes
{"name": "Alice", "age": 30}

Las claves de objeto deben llevar comillas

A diferencia de los literales de objeto de JavaScript, JSON requiere que todas las claves de objeto estén entre comillas dobles. Las claves sin comillas son un error de sintaxis.

// Invalid - unquoted keys
{name: "Alice", age: 30}

// Valid - quoted keys
{"name": "Alice", "age": 30}

Comas finales prohibidas

JSON no permite comas después del último elemento de un objeto o array. Este es otro error común de los desarrolladores de JavaScript, donde las comas finales están permitidas (e incluso se fomentan en algunas guías de estilo).

// Invalid - trailing comma
{
  "name": "Alice",
  "age": 30,
}

// Valid - no trailing comma
{
  "name": "Alice",
  "age": 30
}

No se admiten comentarios

JSON no soporta comentarios. Ni los comentarios de una sola línea // ni los de múltiples líneas /* */ son válidos en JSON. Si necesitas incluir documentación, considera usar un archivo de documentación separado o el formato JSONC (JSON con comentarios) soportado por algunas herramientas.

Tipos de valor estrictos

Los valores JSON deben ser uno de los seis tipos soportados. undefined, NaN, Infinity y -Infinity no son valores JSON válidos. Incluir cualquiera de ellos causa errores de análisis o produce JSON no estándar que muchos analizadores rechazarán.

Errores comunes de formato

Además de los errores de sintaxis, hay varios errores de formato que producen JSON técnicamente válido pero problemático:

• Indentación inconsistente: mezclar tabulaciones y espacios, o usar diferentes profundidades de indentación, hace que JSON sea más difícil de leer en revisiones de código y comparaciones de diferencias. Estandariza en indentación de 2 espacios, que es la convención más común.
• Estructuras profundamente anidadas: JSON con más de 4-5 niveles de anidamiento se vuelve difícil de leer y depurar. Considera aplanar estructuras o dividirlas en documentos separados.
• Orden de claves inconsistente: aunque los objetos JSON son técnicamente no ordenados, mantener un orden de claves consistente (como alfabético o por importancia) hace que las comparaciones de diferencias sean más significativas y reduce los conflictos de fusión en el control de versiones.
• Líneas excesivamente largas: los arrays con muchos elementos en una sola línea son difíciles de navegar. Divide los arrays largos en múltiples líneas, un elemento por línea, para mejorar la legibilidad.
• Manejo de null faltante o inconsistente: decide si omitir completamente los valores null o incluirlos explícitamente, y aplica esa decisión de manera consistente en toda tu API.

Pretty print vs. comprimido

Los dos modos principales de formato JSON sirven para propósitos diferentes, y usar el formato correcto en el contexto adecuado es importante.

JSON con pretty print

El pretty print añade indentación y saltos de línea para hacer el JSON legible para humanos. Esto es crucial durante el desarrollo, la depuración y la escritura de documentación. La mayoría de los formateadores JSON usan indentación de 2 espacios por defecto:

{
  "users": [
    {
      "id": 1,
      "name": "Alice",
      "email": "alice@example.com"
    },
    {
      "id": 2,
      "name": "Bob",
      "email": "bob@example.com"
    }
  ]
}

JSON comprimido

El formato comprimido elimina todos los espacios en blanco innecesarios, produciendo el JSON válido más pequeño posible. Esto es crucial para las APIs de producción donde cada byte importa:

{"users":[{"id":1,"name":"Alice","email":"alice@example.com"},{"id":2,"name":"Bob","email":"bob@example.com"}]}

Cuándo usar cada una

Validación con JSON Schema

Aunque la validación de sintaxis JSON verifica si un documento está bien formado, no valida si los datos tienen la estructura, tipos o valores esperados. JSON Schema llena este vacío proporcionando un vocabulario para describir la forma esperada de los datos JSON.

¿Qué es JSON Schema?

JSON Schema es un documento JSON que describe la estructura de otros documentos JSON. Te permite especificar campos obligatorios, tipos esperados, rangos de valores, patrones de cadena y estructuras de objetos anidados. Un documento JSON que se ajusta a un Schema se llama instancia válida.

Funcionalidades comunes de Schema

• Verificación de tipos: asegura que los campos sean cadenas, números, booleanos, objetos o arrays.
• Campos obligatorios: especifica qué propiedades deben estar presentes.
• Validación de cadenas: aplica patrones (expresiones regulares), longitud mínima/máxima y formato (email, datetime, URI).
• Validación de números: establece mínimo, máximo, límites exclusivos y restricciones de múltiplos.
• Validación de arrays: controla el tipo de elementos, cantidad mínima/máxima de elementos y unicidad.
• Composición: usa allOf, anyOf, oneOf y not para lógica de validación compleja.

Cuándo usar validación con Schema

Debes usar la validación JSON Schema siempre que recibas JSON de fuentes externas: cuerpos de solicitud API, archivos de configuración, importaciones de datos y cargas de colas de mensajes. La validación Schema captura errores temprano, proporciona mensajes de error claros y sirve como documentación viva de los formatos de datos. Bibliotecas como Ajv (JavaScript), jsonschema (Python) y json-schema-validator (Java) facilitan la integración de la validación Schema en cualquier aplicación.

Impacto del tamaño de JSON en el rendimiento

El tamaño del documento JSON impacta directamente el rendimiento de la aplicación en múltiples dimensiones: tiempo de transferencia de red, tiempo de análisis y consumo de memoria. Comprender estos impactos te ayuda a tomar decisiones informadas sobre el formato y la estructura de JSON.

Transferencia de red

Cada byte de JSON debe viajar a través de la red desde el servidor hasta el cliente. En conexiones rápidas, la diferencia entre 10KB y 100KB puede parecer insignificante, pero para los usuarios en redes móviles o en regiones con internet más lento, el impacto es significativo. Los estudios muestran que cada 100ms adicionales de tiempo de carga reducen las tasas de conversión en aproximadamente un 1%. La compresión típicamente reduce el tamaño de JSON en un 30-50%, y la compresión gzip adicionalmente lo reduce en un 70-85%. Siempre habilita la compresión gzip o Brotli para las respuestas de API JSON.

Rendimiento de análisis

El análisis de JSON es sorprendentemente costoso. Para documentos grandes (más de 1MB), el análisis en dispositivos móviles puede tomar cientos de milisegundos. El costo es aproximadamente lineal con el tamaño del documento. Las estrategias clave para reducir los costos de análisis incluyen: enviar solo los datos que el cliente necesita (filtrado de campos), paginar conjuntos de resultados grandes y usar formatos de serialización más eficientes como Protocol Buffers o MessagePack para la comunicación entre servicios internos donde no se necesita legibilidad humana.

Uso de memoria

El JSON analizado típicamente consume de 3 a 10 veces más memoria que su forma serializada, porque cada valor se convierte en un objeto separado con su propia asignación de memoria. Una cadena JSON de 1MB puede usar de 5 a 10MB de RAM después del análisis. Para aplicaciones JavaScript que se ejecutan en navegadores con memoria limitada, esto puede llevar a degradación del rendimiento o bloqueos en dispositivos de gama baja.

JSON vs. JSONL

JSON Lines (JSONL o NDJSON) es un formato relacionado que resuelve una limitación clave de JSON: el requisito de analizar el documento completo como una sola unidad. En JSONL, cada línea del archivo es un objeto JSON completo e independiente.

Cuándo usar JSONL

• Archivos de log: cada registro de log es un objeto JSON autónomo en una línea independiente. Puedes agregar nuevos registros sin modificar los datos existentes y leer cualquier línea de forma independiente.
• Flujos de datos: procesa registros a medida que llegan sin esperar el conjunto de datos completo. Cada línea es un mensaje completo.
• Conjuntos de datos grandes: analiza y procesa registros uno por uno sin cargar todo el archivo en memoria. Esto es crucial para conjuntos de datos que exceden la RAM disponible.
• Procesamiento paralelo: divide archivos JSONL en los límites de línea y distribuye los fragmentos a diferentes workers. Esto es imposible con JSON estándar porque dividir en una posición de bytes arbitraria rompería la estructura.

Cuándo mantener JSON estándar

• Respuestas de API: JSON estándar es el formato esperado para las APIs REST. Envolver los resultados en un array u objeto es convencional y esperado.
• Archivos de configuración: la configuración típicamente necesita cargarse de una vez, por lo que las ventajas de streaming de JSONL son irrelevantes.
• Estructuras de datos anidadas: si tus datos tienen anidamiento complejo que no puede aplanarse fácilmente en registros separados, JSON estándar es más natural.

Manejo de archivos JSON grandes

Los archivos JSON grandes (más de 10MB) presentan desafíos únicos que requieren un manejo especial. Los métodos de análisis estándar pueden fallar o tener un rendimiento deficiente a esta escala.

Analizadores de streaming

Los analizadores de streaming (o estilo SAX) procesan JSON incrementalmente sin cargar todo el documento en memoria. Emiten eventos a medida que encuentran elementos estructurales como inicio de objeto, pares clave-valor y elementos de array. Este enfoque usa memoria constante independientemente del tamaño del archivo. Bibliotecas como oboe.js (JavaScript), ijson (Python) y Jackson Streaming API (Java) proporcionan análisis JSON en streaming.

Consejos prácticos para archivos grandes

• Convierte primero a JSONL: si tienes un array JSON grande, conviértelo a JSONL (un objeto por línea) para habilitar el procesamiento línea por línea usando herramientas estándar como grep, awk y jq.
• Usa herramientas de línea de comandos: jq es la herramienta estándar para procesar JSON desde la línea de comandos. Puede manejar archivos grandes de manera eficiente y soporta modo streaming para entradas muy grandes.
• Divide y paraleliza: divide archivos JSONL grandes en fragmentos más pequeños y procésalos en paralelo. Cada fragmento puede procesarse de forma independiente porque cada línea es autónoma.
• Evita cargar en memoria: nunca uses JSON.parse() en archivos más grandes que la memoria disponible. Usa analizadores de streaming o procesamiento línea por línea.
• Almacenamiento comprimido: los archivos JSON grandes se comprimen extremadamente bien con gzip (típicamente 80-90% de reducción). Mantén copias comprimidas para almacenamiento y descomprime sobre la marcha durante el procesamiento.

Consideraciones de seguridad en JSON

Aunque JSON es un formato de datos y no es inherentemente inseguro, la forma en que las aplicaciones procesan JSON puede introducir vulnerabilidades. Comprender estos riesgos es crucial para construir sistemas seguros.

Nunca uses eval() para analizar JSON

La regla de seguridad más crítica: nunca uses la función eval() de JavaScript para analizar JSON. eval() ejecuta código JavaScript arbitrario, lo que significa que una carga JSON maliciosa puede ejecutar código en la máquina del usuario. Usa siempre JSON.parse(), que solo analiza JSON válido y rechaza cualquier código ejecutable. Esto es innegociable.

JSONP y riesgos entre dominios

JSONP (JSON con Padding) era una técnica para eludir las restricciones de la política de mismo origen antes de que CORS fuera ampliamente soportado. Funciona envolviendo datos JSON en una llamada de función que se ejecuta como script. Esto es inherentemente peligroso porque ejecuta JavaScript arbitrario de servidores de terceros. Si controlas tanto el cliente como el servidor, usa CORS en lugar de JSONP. JSONP debe considerarse una tecnología heredada y evitarse en nuevas aplicaciones.

Contaminación de prototipos

Al fusionar o copiar profundamente objetos JSON en JavaScript, ten cuidado con las claves como __proto__, constructor y prototype. Si el JSON proporcionado por el usuario se fusiona recursivamente en objetos existentes sin limpiar estas claves, puede modificar el prototipo de todos los objetos en la aplicación, llevando a escalada de privilegios o denegación de servicio. Siempre limpia las claves de objeto antes de fusionar.

Denegación de servicio por anidamiento profundo

Los documentos JSON cuidadosamente construidos con profundidad de anidamiento extrema (miles de niveles) pueden causar errores de desbordamiento de pila en analizadores recursivos. Mitiga esto estableciendo una profundidad máxima de anidamiento en tu analizador. La mayoría de los analizadores JSON de producción te permiten configurar este límite.

Validación de entrada

Nunca confíes en datos JSON de fuentes externas. Siempre valida la estructura, tipos y rangos de valores del JSON entrante antes de usarlo. La validación JSON Schema es el enfoque más robusto, pero incluso verificaciones simples de campos obligatorios y aserciones de tipo proporcionan una protección significativa contra entradas mal formadas o maliciosas.