Travailler avec JSON en Java | W3Docs Learn Java

JSON (JavaScript Object Notation) est le format le plus courant pour échanger des données sur le web. Les API le retournent, les fichiers de configuration l'utilisent, et les services se le transmettent entre eux. Java ne dispose d'aucune prise en charge de JSON dans le JDK principal, donc travailler avec JSON implique de choisir une bibliothèque — mais les concepts d'analyse, de mapping et de sérialisation restent les mêmes quelle que soit celle que vous choisissez.

Cette page est la carte de la section JSON : elle explique ce qu'est JSON, comment ses types correspondent aux types Java, quelles bibliothèques existent, et les deux modèles d'analyse. Les chapitres suivants approfondissent les deux bibliothèques les plus populaires — JSON avec Jackson et JSON avec Gson.

Ce qu'est JSON

JSON est un format léger, basé sur du texte, pour les données structurées. Il est construit à partir de quelques types simples : les chaînes, les nombres, les booléens, null, les tableaux (listes ordonnées) et les objets (maps clé/valeur). Parce qu'il s'agit de texte brut, tout langage peut le lire et l'écrire, ce qui explique pourquoi il est devenu la lingua franca des API web.

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

Le format se mappe proprement sur les types des langages de programmation. En Java, un objet JSON devient une Map ou une classe personnalisée, un tableau devient une List ou un tableau, et les types scalaires deviennent String, Number, Boolean et null.

Type JSON	Équivalent Java
object	`Map<String, Object>` ou un POJO/record
array	`List<?>` ou `T[]`
string	`String`
number	`int`, `long`, `double`, `BigDecimal`
`true` / `false`	`boolean` / `Boolean`
`null`	`null`

Pourquoi JSON est important

JSON est le format de données par défaut pour les API REST, et les programmes Java en envoient et en reçoivent constamment : un service web lit un corps de requête JSON, interroge une base de données et écrit une réponse JSON. Il est également lisible par l'humain, ce qui en fait aussi un format de configuration et de journalisation.

Par rapport à XML — l'ancien format d'échange que JSON a largement supplanté — JSON est plus concis, nécessite moins de cérémonie et se mappe plus directement aux structures de données des langages. XML reste préférable lorsque vous avez besoin de schémas, d'espaces de noms ou de contenu mixte, mais pour un simple échange de données, JSON est généralement le choix le plus léger.

Les principales bibliothèques Java

Le JDK ne fournit pas d'analyseur JSON, il faut donc en ajouter un. Trois bibliothèques dominent :

Bibliothèque	Point fort	Utilisation typique
Jackson	Rapide, riche en fonctionnalités, streaming + binding	Le standard de facto ; intégré à Spring Boot
Gson	API simple, empreinte légère	Android, scripts rapides
JSON-P / JSON-B (Jakarta)	Standard officiel Jakarta EE	Applications Enterprise/Jakarta

Jackson est la bibliothèque la plus utilisée. Sa classe centrale est ObjectMapper, qui convertit entre du texte JSON et des objets Java en un seul appel :

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 suit la même structure avec des noms différents :

import com.google.gson.Gson;

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

Ajoutez la bibliothèque comme dépendance avant de l'utiliser — pour Jackson c'est com.fasterxml.jackson.core:jackson-databind ; pour Gson, com.google.code.gson:gson.

Laquelle choisir ? Si vous êtes sur Spring Boot, Jackson est déjà présent et configuré, utilisez-le donc. Pour un petit outil autonome ou une application Android où la taille binaire est importante, la petite API sans configuration de Gson est pratique. Optez pour JSON-B uniquement si vous êtes engagé dans la stack Jakarta EE et souhaitez le standard neutre vis-à-vis des fournisseurs. En pratique, le choix importe rarement pour la correction — les trois lisent et écrivent le même JSON — alors préférez celui qui est déjà sur votre classpath.

Deux façons d'analyser : arbre vs binding

Quelle que soit la bibliothèque choisie, il existe deux modèles principaux pour lire le JSON :

Le data binding mappe le JSON directement sur des classes Java. Vous définissez une classe (ou un record) dont les champs correspondent aux clés, et la bibliothèque la remplit. C'est l'approche la plus propre lorsque la structure est connue et stable.
Le modèle arbre / map analyse le JSON en un arbre générique de nœuds (JsonNode dans Jackson) ou un Map<String, Object>. Vous naviguez par clé. Utilisez ce modèle lorsque la structure est dynamique ou que vous n'avez besoin que de quelques champs.

// 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());

Le binding vous offre la sécurité des types et un code lisible ; le modèle arbre vous offre de la flexibilité. La plupart des applications utilisent le binding pour leurs propres objets métier et ont recours au modèle arbre uniquement pour les données à structure souple.

Un exemple exécutable

Le bac à sable n'a pas Jackson ou Gson sur le classpath, donc le programme ci-dessous utilise uniquement les collections du JDK pour illustrer la même idée : un objet JSON analysé n'est qu'un ensemble de clés mappées à des valeurs typées, un tableau est une List, et la sérialisation reconstruit cette structure en texte JSON. Les exemples statiques ci-dessus montrent la vraie API de bibliothèque que vous utiliserez dans un projet.

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));
    }
}

Ce qu'il faut retenir de l'exécution :

Un objet JSON analysé se comporte comme une Map : vous récupérez chaque champ par sa clé, exactement comme mapper.readTree(...).get("name") le ferait dans Jackson.
Les valeurs JSON conservent leur type — age revient en tant que Number et admin en tant que Boolean, pas sous forme de texte brut, ce qui explique pourquoi age instanceof Number affiche true.
Un tableau JSON se mappe sur une List, donc roles est itérable et rapporte une taille de 2.
La sérialisation est l'inverse de l'analyse : parcourir la même structure reconstruit le texte JSON compact {"name":"Ann",...}.
L'utilisation de LinkedHashMap préserve l'ordre d'insertion, de sorte que les clés sérialisées apparaissent dans l'ordre où elles ont été ajoutées — utile pour une sortie stable et facile à différencier.

Pratique

Vers quoi un tableau JSON se mappe-t-il le plus naturellement en Java ?

Une ListUne StringUn booleanUn int