Buenas prácticas de formato JSON para desarrolladores

¿Qué es JSON y por qué importa el formato?

JSON (JavaScript Object Notation) es el formato de intercambio de datos de facto en la web. Es ligero, legible y prácticamente todos los lenguajes lo soportan de forma nativa. Tanto si construyes una API REST como si guardas configuración o mueves datos entre el frontend y el backend, JSON es casi siempre la opción por defecto.

Pero "legible" depende de cómo lo escribas. Una sola línea de JSON minificado puede ocupar 4 KB; los mismos datos con indentación de dos espacios pueden ocupar 8 KB. Ambos son válidos. La diferencia es si el próximo desarrollador —incluido tú mismo en el futuro— podrá leerlo a las 2 de la madrugada durante una incidencia.

Un buen formato no va solo de estética. Afecta directamente a:

• Depurabilidad: un payload embellecido muestra la estructura de un vistazo. Los objetos anidados se navegan fácil, las claves que faltan saltan a la vista y las erratas se notan.
• Legibilidad del diff: revisar código sobre JSON minificado es inútil. Un diff con indentación de dos espacios muestra claramente qué campos cambiaron.
• Localización de errores: cuando el parseo falla, los números de línea y columna solo tienen sentido si el documento tiene un diseño real.
• Colaboración: un estilo coherente en el equipo evita que nadie pierda tiempo reformateando archivos antes de poder trabajar con ellos.

En resumen, formatear es una forma de comunicación. Trata tu JSON como tratas tu código.

Los errores de JSON más comunes

Incluso desarrolladores con experiencia cometen estos fallos. Son sintaxis válida en JavaScript, por eso pasan desapercibidos en el editor.

Comas finales

Una coma extra tras el último elemento de un array u objeto es perfectamente válida en JavaScript. JSON no la permite.

```json // INVÁLIDO { "name": "Ada", "age": 36, } ```

La solución es trivial: quita la coma. La mayoría de los linters lo detectan. Si el tuyo no, cambia a uno que sí.

Comillas simples para strings

Los strings en JSON deben ir con comillas dobles. Las comillas simples son convención de JavaScript, no de JSON.

```json // INVÁLIDO { 'name': 'Ada' } ```

Esto pasa a menudo al copiar valores de un literal de objeto en JavaScript o de un diccionario en Python. Usa siempre comillas dobles, tanto para claves como para valores de tipo string.

Claves sin comillas

Las claves en JSON deben ser strings, y los strings deben ir entre comillas.

```json // INVÁLIDO { name: "Ada" } ```

Comentarios

JSON no soporta comentarios. Ni `//` ni `/ /` se parsearán. Si necesitas anotaciones, usa un campo `"_comment"`, un fichero auxiliar o pasa a JSON5/JSONC — pero solo en el lado productor, porque la mayoría de consumidores esperan JSON estricto.

Llaves y corchetes descompensados

Una `}` que falta o un `]` de más es la causa más común de "Unexpected end of JSON input" y similares. Embellecer es la forma más rápida de detectarlo: tu ojo lo verá al instante.

Cómo validar JSON

Validar se divide en dos categorías: sintáctica (¿es un JSON bien formado?) y semántica (¿coincide con el esquema que espero?).

Para validación sintáctica, cualquier editor moderno te vale. VS Code resalta en rojo el JSON malformado. La herramienta CLI `jq` te dirá en el primer carácter que falla. Los validadores online funcionan, pero ve con cuidado con datos sensibles — pega solo muestras no sensibles.

Para validación semántica necesitas un JSON Schema (más abajo) o un parser tipado en tu lenguaje. En TypeScript, librerías como `zod` o `io-ts` permiten describir la forma esperada y rechazar lo que no encaje. Esto atrapa la peor clase de bug: que la API devuelva silenciosamente un campo nuevo, o que un campo antiguo pase a ser `null`, y tu código reviente tres capas más abajo.

Un buen flujo de trabajo:

1. Embellece el JSON entrante mientras depuras.
2. Valida contra un esquema en la frontera de tu sistema (controlador, cliente de API, handler de mensajes).
3. No confíes en nada dentro de la frontera.

Embellecer vs. minificar

Son las dos caras de la misma moneda, y las dos son útiles — solo que en sitios distintos.

Embellecer (también "beautify" o "expand") añade indentación y saltos de línea. Úsalo para:

• Ficheros fuente que subes a git
• Respuestas de API que inspeccionas en desarrollo
• Entradas de log que podrías necesitar leer más tarde
• Documentación y ejemplos

Minificar elimina todos los espacios. Úsalo para:

• Respuestas de API en producción
• Tokens y cookies (JWT, almacenamiento de sesión)
• Almacenamiento en bases de datos o cachés con espacio limitado
• Cargas de red donde cada byte cuenta

Regla práctica: embellece en desarrollo, minifica en producción. La mayoría de herramientas de build lo hacen automáticamente. Para tareas puntuales, un formateador de JSON gratuito hace ambas direcciones con solo pegar.

Si necesitas comparar dos documentos JSON, una herramienta de diff de texto resaltará exactamente qué campos cambiaron — mucho más útil que mirar fijamente la salida minificada.

Trabajar con datos anidados

Los objetos y arrays anidados son donde brilla la expresividad de JSON — y donde se esconden los bugs.

Algunos principios:

• Mantén el anidamiento poco profundo. Tres niveles está bien. Cinco niveles significa que probablemente deberías modelar los datos como una lista plana con claves foráneas, o dividir en varios endpoints.
• Sé coherente entre arrays y objetos. Un campo que a veces es array y a veces `null` es causa común de `Cannot read property 'map' of null`. Decide de antemano: si no hay elementos, devuelve `[]`, no `null`.
• Usa un orden de claves estable cuando importe. JSON no exige orden, pero los parsers y herramientas de diff se comportan mejor con un orden predecible. Alfabético es un valor por defecto seguro.
• Cuidado con arrays enormes. Un blob JSON de 50 MB con un millón de elementos en un array es técnicamente válido pero imposible de streamear. Considera NDJSON (un objeto JSON por línea) o una API paginada.

JSON en APIs: content-type y códigos de estado

Si construyes APIs HTTP, dos cabeceras hacen casi todo el trabajo:

• `Content-Type: application/json` — indica al cliente (y a cualquier intermediario) qué esperar. Olvidarla es el bug de API más común en producción.
• `Accept: application/json` — lo que el cliente está dispuesto a recibir. Útil para negociación de contenido.

En la respuesta, haz coincidir el código de estado con el resultado:

• `200 OK` — éxito, el cuerpo contiene el recurso o resultado.
• `201 Created` — se creó un nuevo recurso; la cabecera `Location` debería apuntar a él.
• `204 No Content` — éxito, sin cuerpo (frecuente en DELETE).
• `400 Bad Request` — la petición está mal formada (JSON inválido, falta un campo obligatorio).
• `401 Unauthorized` — sin credenciales válidas.
• `403 Forbidden` — credenciales válidas pero sin permiso.
• `404 Not Found` — el recurso no existe.
• `422 Unprocessable Entity` — JSON válido pero semánticamente incorrecto (p. ej., edad negativa).
• `500 Internal Server Error` — algo explotó en el servidor. Nunca filtres stack traces.

Un patrón habitual es envolver respuestas: `{ "data": ..., "error": null }` o `{ "data": null, "error": { "code": "...", "message": "..." } }`. Está bien, pero no es obligatorio. Cualquiera de las dos opciones es mejor que formas incoherentes improvisadas.

Básico de JSON Schema

JSON Schema es un vocabulario que permite describir la forma y restricciones de un documento JSON. Piensa en él como el sistema de tipos de JSON.

Un esquema mínimo:

```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "required": ["name", "age"], "properties": { "name": { "type": "string", "minLength": 1 }, "age": { "type": "integer", "minimum": 0 } } } ```

Dice: el documento debe ser un objeto con un `name` no vacío y un `age` entero no negativo. Puedes extenderlo con formatos (`"format": "email"`), enums, regex y referencias a otros esquemas.

¿Para qué molestarse? Validar en la frontera atrapa datos malos antes de que se propaguen. También sirve como documentación viva: el esquema describe lo que tu API realmente acepta, no lo que alguien cree que acepta.

Casi todos los lenguajes tienen un validador de JSON Schema. En TypeScript, herramientas como `zod` son cada vez más populares porque generan tipos TypeScript a partir del esquema por ti.

Problemas frecuentes con fechas, números y caracteres especiales

JSON es deliberadamente minimalista. No tiene tipo fecha, y eso confunde a todo el mundo.

• Fechas: guárdalas como strings ISO 8601 (`"2026-02-01T12:00:00Z"`). Evita formatos como `"02/01/2026"` — ambiguos y dependientes de la configuración regional.
• Números: los números en JSON son decimales. No hay tipo entero. En JavaScript, los enteros por encima de 2^53 pierden precisión. Para IDs o dinero, prefiere strings.
• Booleanos: solo los literales `true` y `false`. Strings como `"true"` no se convierten automáticamente.
• Unicode: los strings en JSON son Unicode, así que emojis y caracteres CJK funcionan directamente. Pero las secuencias de escape importan: `\n` es salto de línea, `\\` es barra invertida, `\u0041` es `A`. En caso de duda, pega tus datos en un formateador de JSON e inspecciona los bytes.
• Null vs. ausente: `{"age": null}` y `{}` significan cosas distintas. Decide en tu sistema cuál representa "desconocido" y apégate a ello.

Herramientas que ahorran tiempo

Un buen formateador es de esas herramientas que no sabes que necesitas hasta que la usas. Nuestro formateador de JSON gratuito se ejecuta por completo en el navegador — sin subidas, sin registro, sin tracking. Pega un payload minificado, obtén un árbol legible, cópialo. Valida mientras formatea, así los errores de sintaxis aparecen en línea señalando el carácter problemático.

Para comparar dos versiones de un documento JSON — por ejemplo, antes y después de una migración — la herramienta de diff de texto hace el mismo trabajo con cualquier texto plano, resaltando línea a línea.

Ambas forman parte de un conjunto más amplio de herramientas de desarrollador pensadas para esas utilidades rápidas en el navegador que usas decenas de veces al día.

Conclusión

El formato JSON es una de esas pequeñas disciplinas que se acumulan a lo largo de un proyecto. Embellece en desarrollo, minifica en producción. Valida en la frontera. Usa esquemas cuando los datos vayan a reutilizarse. Guarda las fechas como ISO 8601, los números grandes como strings, y trata `null` con intención.

Nada de esto es glamuroso. Pero todo te ahorrará horas de depuración la próxima vez que algo falle — y algo siempre falla. La buena noticia es que, con un formateador y un esquema a mano, la solución suele estar a un solo pegar.