Introducción a JSON en Java

JSON (JavaScript Object Notation) es el formato más común para intercambiar datos en la web. Las APIs lo devuelven, los archivos de configuración lo usan, y los servicios lo pasan entre sí. Java no incluye soporte JSON en el JDK principal, por lo que trabajar con JSON implica elegir una biblioteca, pero los conceptos de análisis, mapeo y serialización son los mismos independientemente de cuál elijas.

Esta página es el mapa de la sección JSON: explica qué es JSON, cómo sus tipos se corresponden con los tipos de Java, qué bibliotecas existen y los dos modelos de análisis. Los capítulos siguientes profundizan en las dos bibliotecas más populares — JSON con Jackson y JSON con Gson.

Qué es JSON

JSON es un formato ligero y basado en texto para datos estructurados. Está construido a partir de unos pocos tipos simples: cadenas, números, booleanos, null, arrays (listas ordenadas) y objetos (mapas clave/valor). Al ser texto plano, cualquier lenguaje puede leerlo y escribirlo, lo que lo convirtió en la lengua franca de las APIs web.

{
  "name": "Ann",
  "age": 30,
  "admin": true,
  "roles": ["editor", "author"],
  "address": null
}

El formato se corresponde limpiamente con los tipos de los lenguajes de programación. En Java, un objeto JSON se convierte en un Map o en una clase personalizada, un array se convierte en una List o en un array, y los tipos escalares se convierten en String, Number, Boolean y null.

Por qué Importa JSON

JSON es la carga útil predeterminada para las APIs REST, y los programas Java constantemente lo envían y reciben: un servicio web lee el cuerpo de una solicitud JSON, consulta una base de datos y escribe una respuesta JSON. También es legible por humanos, por lo que sirve como formato de configuración y registro.

En comparación con XML — el formato de intercambio más antiguo que JSON desplazó en gran medida — JSON es más conciso, tiene menos ceremonia y se corresponde más directamente con las estructuras de datos del lenguaje. XML sigue siendo mejor cuando necesitas esquemas, espacios de nombres o contenido mixto, pero para el intercambio de datos simples JSON suele ser la opción más ligera.

Las Principales Bibliotecas de Java

El JDK no incluye un analizador JSON, por lo que hay que añadir uno. Tres bibliotecas dominan el panorama:

Jackson es el más ampliamente utilizado. Su clase central es ObjectMapper, que convierte entre texto JSON y objetos Java en una sola llamada:

import com.fasterxml.jackson.databind.ObjectMapper;

ObjectMapper mapper = new ObjectMapper();

// Java object -> JSON text (serialize)
String json = mapper.writeValueAsString(user);

// JSON text -> Java object (deserialize)
User parsed = mapper.readValue(json, User.class);

Gson sigue la misma estructura con nombres diferentes:

import com.google.gson.Gson;

Gson gson = new Gson();
String json = gson.toJson(user);          // serialize
User parsed = gson.fromJson(json, User.class); // deserialize

Añade la biblioteca como dependencia antes de usarla — para Jackson es com.fasterxml.jackson.core:jackson-databind; para Gson, com.google.code.gson:gson.

¿Cuál deberías elegir? Si estás en Spring Boot, Jackson ya está allí y configurado, así que úsalo. Para una herramienta independiente pequeña o una aplicación Android donde el tamaño del binario importa, la API compacta y sin configuración de Gson es conveniente. Recurre a JSON-B solo cuando estés comprometido con el stack de Jakarta EE y quieras el estándar neutro respecto al proveedor. En la práctica la elección raramente importa para la corrección — las tres leen y escriben el mismo JSON — así que prefiere la que ya esté en tu classpath.

Dos Formas de Analizar: Árbol vs Binding

Independientemente de la biblioteca que elijas, hay dos modelos principales para leer JSON:

• Data binding mapea JSON directamente en clases Java. Defines una clase (o record) cuyos campos coinciden con las claves, y la biblioteca los rellena. Este es el enfoque más limpio cuando la estructura es conocida y estable.
• Modelo de árbol / mapa analiza JSON en un árbol genérico de nodos (JsonNode en Jackson) o en un Map<String, Object>. Navegas por clave. Úsalo cuando la forma es dinámica o solo necesitas unos pocos campos.

// Binding: structure known ahead of time
record User(String name, int age, boolean admin) {}
User u = mapper.readValue(json, User.class);
System.out.println(u.name());

// Tree: navigate without a class
JsonNode root = mapper.readTree(json);
System.out.println(root.get("name").asText());

El binding te ofrece seguridad de tipos y código legible; el modelo de árbol te da flexibilidad. La mayoría de las aplicaciones usan binding para sus propios objetos de dominio y recurren al modelo de árbol solo para datos con estructura poco definida.

Un Ejemplo Ejecutable

El entorno de pruebas no tiene Jackson ni Gson en el classpath, por lo que el programa a continuación usa solo colecciones del JDK para demostrar la misma idea: un objeto JSON analizado es simplemente claves mapeadas a valores tipados, un array es una List, y serializar convierte esa estructura de nuevo en texto JSON. Los ejemplos estáticos anteriores muestran la API real de la biblioteca que usarás en un proyecto.

Lo que debes extraer de la ejecución:

• Un objeto JSON analizado se comporta como un Map: obtienes cada campo por su clave, exactamente como haría mapper.readTree(...).get("name") en Jackson.
• Los valores JSON mantienen su tipo — age vuelve como un Number y admin como un Boolean, no como texto sin procesar, por eso age instanceof Number imprime true.
• Un array JSON se mapea a una List, por lo que roles es iterable e indica un tamaño de 2.
• La serialización es el proceso inverso del análisis: recorrer la misma estructura reconstruye el texto JSON compacto {"name":"Ann",...}.
• Usar LinkedHashMap preserva el orden de inserción, por lo que las claves serializadas aparecen en el orden en que fueron añadidas — útil para una salida estable y fácil de comparar con diff.

Práctica