Introducción a Java JSON

JSON (JavaScript Object Notation) es el formato más común para intercambiar datos en la web. Las API lo devuelven, los archivos de configuración lo usan y los servicios se lo pasan entre sí. Java no tiene soporte de JSON integrado en el núcleo del JDK, así que trabajar con JSON significa elegir una biblioteca — pero los conceptos de análisis, mapeo y serialización siguen siendo los mismos sea cual sea la que elija.

Qué es JSON

JSON es un formato ligero, basado en texto, para datos estructurados. Está construido a partir de unos pocos tipos simples: cadenas, números, booleanos, null, arreglos (listas ordenadas) y objetos (mapas clave/valor). Como es texto plano, cualquier lenguaje puede leerlo y escribirlo, y por eso se convirtió en la lingua franca de las API web.

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

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

Tipo JSON	Equivalente en Java
object	`Map<String, Object>` o un POJO/record
array	`List<?>` o `T[]`
string	`String`
number	`int`, `long`, `double`, `BigDecimal`
`true` / `false`	`boolean` / `Boolean`
`null`	`null`

Por qué importa JSON

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

Comparado con XML — el formato de intercambio más antiguo que JSON desplazó en gran medida — JSON es más escueto, tiene menos ceremonia y se mapea más directamente sobre las estructuras de datos del lenguaje. XML sigue ganando donde se necesitan esquemas, espacios de nombres o contenido mixto, pero para el simple intercambio de datos JSON suele ser la opción más ligera.

Las principales bibliotecas de Java

El JDK no incluye un analizador de JSON, así que usted añade uno. Tres bibliotecas dominan:

Biblioteca	Punto fuerte	Uso típico
Jackson	Rápida, rica en funciones, streaming + binding	El estándar de facto; integrada en Spring Boot
Gson	API sencilla, huella pequeña	Android, scripts rápidos
JSON-P / JSON-B (Jakarta)	Estándar oficial de Jakarta EE	Aplicaciones empresariales/Jakarta

Jackson es la más utilizada. 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();

// Objeto Java -> texto JSON (serializar)
String json = mapper.writeValueAsString(user);

// Texto JSON -> objeto Java (deserializar)
User parsed = mapper.readValue(json, User.class);

Gson sigue la misma forma con nombres distintos:

import com.google.gson.Gson;

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

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

Dos formas de analizar: árbol vs. binding

Sea cual sea la biblioteca que elija, hay dos modelos principales para leer JSON:

El data binding mapea JSON directamente sobre clases Java. Usted define una clase (o record) cuyos campos coinciden con las claves, y la biblioteca la rellena. Es el enfoque más limpio cuando la estructura es conocida y estable.
El modelo de árbol/map analiza JSON en un árbol genérico de nodos (JsonNode en Jackson) o un Map<String, Object>. Usted navega por clave. Úselo cuando la forma es dinámica o solo necesita unos pocos campos.

// Binding: estructura conocida de antemano
record User(String name, int age, boolean admin) {}
User u = mapper.readValue(json, User.class);
System.out.println(u.name());

// Árbol: navegar sin clase
JsonNode root = mapper.readTree(json);
System.out.println(root.get("name").asText());

El binding le aporta seguridad de tipos y código legible; el modelo de árbol le aporta flexibilidad. La mayoría de las aplicaciones usan binding para sus propios objetos de dominio y recurren al modelo de árbol solo para datos poco estructurados.

Un ejemplo ejecutable

El entorno aislado no tiene ni Jackson ni Gson en el classpath, así que el programa siguiente usa solo colecciones del JDK para demostrar la misma idea: un objeto JSON analizado no es más que claves mapeadas sobre valores tipados, un arreglo es una List, y la serialización convierte esa estructura de vuelta en texto JSON. Los ejemplos estáticos de arriba muestran la verdadera API de biblioteca que usará en un proyecto.

java— editable, runs on the server

import java.util.*;

public class JsonIntro {

// A stand-in for a parsed JSON object: keys mapped to values.
    static Map<String, Object> parsedUser() {
        // Models: {"name":"Ann","age":30,"admin":true,"roles":["editor","author"]}
        Map<String, Object> user = new LinkedHashMap<>();
        user.put("name", "Ann");
        user.put("age", 30);
        user.put("admin", true);
        user.put("roles", List.of("editor", "author"));
        return user;
    }

// Turn a Java value into a JSON text fragment (a tiny serializer).
    static String toJson(Object value) {
        if (value == null) return "null";
        if (value instanceof String s) return "\"" + s + "\"";
        if (value instanceof Boolean || value instanceof Number) return value.toString();
        if (value instanceof List<?> list) {
            StringBuilder sb = new StringBuilder("[");
            for (int i = 0; i < list.size(); i++) {
                if (i > 0) sb.append(",");
                sb.append(toJson(list.get(i)));
            }
            return sb.append("]").toString();
        }
        if (value instanceof Map<?, ?> map) {
            StringBuilder sb = new StringBuilder("{");
            boolean first = true;
            for (Map.Entry<?, ?> e : map.entrySet()) {
                if (!first) sb.append(",");
                first = false;
                sb.append("\"").append(e.getKey()).append("\":").append(toJson(e.getValue()));
            }
            return sb.append("}").toString();
        }
        return "\"" + value + "\"";
    }

public static void main(String[] args) {
        Map<String, Object> user = parsedUser();

// Reading values back out by key, the way a parser hands them to you.
        System.out.println("name  -> " + user.get("name"));
        System.out.println("age   -> " + user.get("age"));
        System.out.println("admin -> " + user.get("admin"));

// JSON values keep their type: age is a number, admin is a boolean.
        Object age = user.get("age");
        System.out.println("age is a Number? " + (age instanceof Number));

// Arrays map to a List you can iterate.
        @SuppressWarnings("unchecked")
        List<String> roles = (List<String>) user.get("roles");
        System.out.println("roles count: " + roles.size());
        for (String role : roles) {
            System.out.println("  role: " + role);
        }

// Serializing the same object back into JSON text.
        System.out.println("JSON: " + toJson(user));
    }
}

Qué llevarse de la ejecución:

Un objeto JSON analizado se comporta como un Map: usted obtiene cada campo por su clave, exactamente como lo haría mapper.readTree(...).get("name") en Jackson.
Los valores JSON conservan su tipo — age vuelve como un Number y admin como un Boolean, no como texto en bruto, por lo que age instanceof Number imprime true.
Un arreglo JSON se mapea sobre una List, así que roles es iterable e informa un tamaño de 2.
La serialización es lo inverso del análisis: recorrer la misma estructura reconstruye el texto JSON compacto {"name":"Ann",...}.
Usar LinkedHashMap preserva el orden de inserción, así que las claves serializadas aparecen en el orden en que se añadieron — útil para una salida estable y amigable con los diffs.

Práctica

¿Sobre qué se mapea un arreglo JSON de la forma más natural en Java?

Una List
Una String
Un boolean
Un int