Java JSON Introduction

JSON (JavaScript Object Notation) is the most common format for exchanging data on the web. APIs return it, config files use it, and services pass it between one another. Java has no JSON support built into the core JDK, so working with JSON means picking a library — but the concepts of parsing, mapping, and serializing stay the same whichever one you choose.

This page is the map for the JSON section: it explains what JSON is, how its types line up with Java types, which libraries exist, and the two parsing models. The follow-up chapters go deep on the two most popular libraries — JSON with Jackson and JSON with Gson.

What JSON Is

JSON is a lightweight, text-based format for structured data. It is built from a few simple types: strings, numbers, booleans, null, arrays (ordered lists), and objects (key/value maps). Because it is plain text, any language can read and write it, which is why it became the lingua franca of web APIs.

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

The format maps cleanly onto programming-language types. In Java, a JSON object becomes a Map or a custom class, an array becomes a List or an array, and the scalar types become String, Number, Boolean, and null.

Why JSON Matters

JSON is the default payload for REST APIs, and Java programs constantly send and receive it: a web service reads a JSON request body, queries a database, and writes a JSON response. It is also human-readable, so it doubles as a config and logging format.

Compared to XML — the older interchange format JSON largely displaced — JSON is terser, has less ceremony, and maps more directly to language data structures. XML still wins where you need schemas, namespaces, or mixed content, but for plain data exchange JSON is usually the lighter choice.

The Main Java Libraries

The JDK does not ship a JSON parser, so you add one. Three libraries dominate:

Jackson is the most widely used. Its central class is ObjectMapper, which converts between JSON text and Java objects in a single call:

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 follows the same shape with different names:

import com.google.gson.Gson;

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

Add the library as a dependency before you use it — for Jackson that is com.fasterxml.jackson.core:jackson-databind; for Gson, com.google.code.gson:gson.

Which one should you pick? If you are on Spring Boot, Jackson is already there and configured, so use it. For a small standalone tool or an Android app where binary size matters, Gson's tiny, no-config API is convenient. Reach for JSON-B only when you are committed to the Jakarta EE stack and want the vendor-neutral standard. In practice the choice rarely matters for correctness — all three read and write the same JSON — so prefer the one that is already on your classpath.

Two Ways to Parse: Tree vs Binding

Whichever library you pick, there are two main models for reading JSON:

• Data binding maps JSON straight onto Java classes. You define a class (or record) whose fields match the keys, and the library fills it in. This is the cleanest approach when the structure is known and stable.
• Tree / map model parses JSON into a generic tree of nodes (JsonNode in Jackson) or a Map<String, Object>. You navigate by key. Use this when the shape is dynamic or you only need a few fields.

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

Binding gives you type safety and readable code; the tree model gives you flexibility. Most applications use binding for their own domain objects and reach for the tree model only for loosely structured data.

A Runnable Example

The sandbox has no Jackson or Gson on the classpath, so the program below uses only JDK collections to demonstrate the same idea: a parsed JSON object is just keys mapped to typed values, an array is a List, and serializing turns that structure back into JSON text. The static examples above show the real library API you will use in a project.

What to take from the run:

• A parsed JSON object behaves like a Map: you fetch each field by its key, exactly as mapper.readTree(...).get("name") would in Jackson.
• JSON values keep their type — age comes back as a Number and admin as a Boolean, not as raw text, which is why age instanceof Number prints true.
• A JSON array maps to a List, so roles is iterable and reports a size of 2.
• Serialization is the reverse of parsing: walking the same structure rebuilds the compact JSON text {"name":"Ann",...}.
• Using LinkedHashMap preserves insertion order, so the serialized keys appear in the order they were added — useful for stable, diff-friendly output.

Practice