Buenas prácticas de formato JSON que todo desarrollador debería conocer

Los fundamentos de la estructura JSON

JSON (JavaScript Object Notation) es un formato de texto ligero para representar datos estructurados. A pesar de su nombre, es independiente del lenguaje y se usa en todas partes, desde APIs REST hasta archivos de configuración. Un documento JSON válido es un objeto (un conjunto de pares clave-valor entre llaves) o un array (una lista ordenada entre corchetes).

Los seis tipos de valor en JSON son: cadena de texto, número, booleano (true/false), null, objeto y array. Cada clave en un objeto JSON debe ser una cadena de texto entre comillas dobles, no simples ni sin comillas.

Errores de sintaxis comunes

JSON es estricto. Un solo error de sintaxis hace que todo el documento sea imposible de analizar. Los errores más frecuentes son:

• Comas finales: {"name": "Alice",}: la coma al final del último elemento es ilegal en JSON (es válida en JavaScript, lo que genera confusión).
• Cadenas entre comillas simples: JSON requiere comillas dobles. {'key': 'value'} no es JSON válido.
• Claves sin comillas: {name: "Alice"} es sintaxis de objeto literal de JavaScript, no JSON.
• Comentarios: JSON no admite comentarios. Si necesitas comentarios en un archivo de configuración, considera JSONC o YAML.
• Undefined y NaN: estos valores de JavaScript no existen en JSON. Usa null u omite el campo.
• Caracteres de control sin escapar: los saltos de línea dentro de cadenas deben escribirse como \n, no como saltos de línea literales.

Formato para legibilidad

El JSON enviado por red suele estar minificado —sin espacios en blanco— para reducir el tamaño del payload. Pero el JSON almacenado en archivos de configuración o en control de versiones debería estar formateado para la legibilidad humana. Las convenciones estándar son:

• Dos o cuatro espacios por nivel de sangría (elige uno y sé coherente)
• Un par clave-valor por línea en los objetos
• Llave de apertura en la misma línea que la clave padre, llave de cierre en su propia línea
• Los arrays de valores simples pueden escribirse en una sola línea si son cortos

La mayoría de los editores pueden formatear JSON automáticamente. En VS Code, haz clic derecho y selecciona «Formatear documento» o usa el atajo Shift+Alt+F. Los usuarios de línea de comandos pueden usar jq . input.json para imprimir de forma legible cualquier archivo JSON.

Convenciones de nomenclatura

El propio JSON no impone convenciones de nomenclatura, pero tu API o base de código debería elegir una y ceñirse a ella. Los tres patrones comunes son:

• camelCase (firstName): estándar en las APIs de JavaScript y la mayoría de los servicios REST
• snake_case (first_name): habitual en las APIs de Python y PostgreSQL
• PascalCase (FirstName): usado en algunos entornos .NET y C#

Mezclar convenciones en una sola API es fuente de confusión. Si consumes una API con una convención y tu base de código usa otra, gestiona la conversión en una capa de serialización dedicada en lugar de distribuir conversiones ad hoc por todo el código.

Gestión de null frente a campos ausentes

Un objeto JSON puede representar la ausencia de un valor de dos maneras: la clave está presente con un valor null, o la clave está ausente por completo. Estas tienen diferentes semánticas. Usa null cuando un campo es esperado pero no tiene valor (por ejemplo, un campo de segundo nombre que el usuario dejó en blanco). Omite el campo cuando simplemente no aplica a ese registro en absoluto. Decide un enfoque coherente dentro de tu API para que los consumidores sepan qué esperar.

Números grandes y precisión

Los números JSON no tienen un límite de tamaño definido, pero muchos analizadores los deserializan como valores de punto flotante de doble precisión IEEE 754. Esto significa que los enteros mayores que 2^53 no pueden representarse con precisión. Si tu JSON necesita transportar enteros grandes (IDs de base de datos, cantidades financieras en unidades monetarias menores, identificadores criptográficos), represéntalos como cadenas de texto y documéntalo en tu API. Este es un problema conocido con los IDs de tuit de Twitter, por ejemplo.

Validación de JSON

Más allá de la validación de sintaxis (¿es esto JSON válido?), JSON Schema permite definir la forma esperada de un documento: qué campos son obligatorios, sus tipos, rangos de valores y más. Herramientas como ajv (JavaScript), jsonschema (Python) y validadores en línea pueden comprobar un documento JSON contra un esquema. Para cualquier API que publiques o consumas en un contexto de producción, vale la pena implementar la validación con JSON Schema en el límite.

Un formateador y validador de JSON, como el de TheDailyUtils, es la forma más rápida de detectar errores de sintaxis en un payload desconocido. Pega el JSON sin procesar y verás de inmediato si se analiza correctamente y dónde están los errores.

Formatea y valida JSON al instante

Abre el formateador JSON gratuito: pega cualquier JSON para imprimirlo de forma legible, minificarlo o detectar errores de sintaxis en segundos. Se ejecuta en tu navegador; tus datos permanecen privados.