Modern Java — particularly Java 16 through 21 — introduced several language features that change how you model data: Records for immutable value objects, Optional for nullable return types, and Sealed Classes for closed type hierarchies. Each of these interacts with Jackson in ways that require specific setup. This guide shows you exactly what to configure so that Jackson handles all three correctly.

Jackson with Java Records

Java Records are ideal DTOs: they are immutable, concise, and carry their own equals(), hashCode(), and toString() implementations. Jackson 3 supports Records natively with zero additional modules — the canonical constructor is used automatically for deserialisation and record accessor methods replace getters for serialisation.

Define a Record:

// A concise, immutable data transfer object
public record ProductRecord(
    Long   productId,
    String productName,
    double unitPrice
) {}

Jackson is the most widely used JSON library in the Java ecosystem, and ObjectMapper is its workhorse. Whether you need to convert a Java object into a JSON string, parse a JSON file from disk, or read from an HTTP response body, ObjectMapper handles it all with a clean, consistent API. This guide covers everything you need to use Jackson’s ObjectMapper effectively in real projects.

What Is Jackson ObjectMapper?

ObjectMapper is the central class in Jackson’s data-binding API. It bridges the gap between Java objects (POJOs) and JSON text. Internally it uses a JsonParser for reading and a JsonGenerator for writing, but you rarely interact with those directly — ObjectMapper wraps them behind a higher-level API.

Three key facts to keep in mind:

• Thread-safe after configuration. Create one instance, share it across your application. Recreating it per request is expensive.
• Highly configurable. Date formats, null handling, unknown-property behaviour, and much more are controlled via feature flags.
• Extensible. Custom serialisers, deserialisers, and modules let you handle any type Jackson does not know about out of the box.

Adding Jackson to Your Project

The jackson-databind artifact is all you need. It pulls in jackson-core and jackson-annotations as transitive dependencies.

Jackson annotations give you precise control over how your Java objects map to JSON and back. Rather than relying solely on field names, you can rename properties, ignore specific fields, handle nulls, format dates, and much more — all without writing a single custom serialiser. This guide covers every annotation you will encounter in real projects, with concrete examples for each.

@JsonProperty — Rename a Field in JSON

Use @JsonProperty when the JSON key must differ from the Java field name — for example, when consuming a third-party API that uses snake_case.

public class OrderSummary {
    @JsonProperty("order_id")        // JSON key: order_id
    private Long orderId;

    @JsonProperty("customer_name")   // JSON key: customer_name
    private String customerName;

    // Getters and setters
}

// Serialise
{"order_id":1001,"customer_name":"Alice"}

// Deserialise: JSON with "order_id" maps correctly to the orderId field

There are two scenarios where Jackson’s built-in annotations are not enough: when you need to control exactly how a complex type is serialised, and when the class you need to annotate belongs to a third-party library whose source you cannot modify. For the first case, Jackson provides custom serialisers and deserialisers. For the second, it provides Mix-in Annotations — a mechanism that lets you attach annotations to any class without touching its source.

Writing a Custom Serialiser

Extend StdSerializer<T> and override serialize(). The method receives the value to write and a JsonGenerator you use to emit JSON tokens.

Suppose you have a Money type that should serialise as a structured JSON object containing the amount and the currency code:

public class Money {
    private final BigDecimal amount;
    private final String     currencyCode;
    // Constructor and getters
}

Polymorphic deserialisation is the technique of deserialising a JSON payload into one of several possible concrete subtypes based on information embedded in the JSON itself. It is essential whenever your API works with inheritance hierarchies — event systems, payment processors, notification pipelines, or any domain where a list of heterogeneous objects needs to round-trip through JSON. Jackson handles this cleanly with @JsonTypeInfo and @JsonSubTypes.

The Problem: Deserialising an Abstract Type

Consider an API that returns a list of payment methods. Some are credit cards, others are bank transfers. Both share a common base, but each has its own fields. Without polymorphic support, Jackson cannot decide which concrete class to instantiate when it sees a generic PaymentMethod type.

Setting Up the Hierarchy with @JsonTypeInfo and @JsonSubTypes

Annotate the base class (or interface) with @JsonTypeInfo to tell Jackson where the type discriminator lives in the JSON, and with @JsonSubTypes to register the permitted subtypes:

@JsonTypeInfo(
    use      = JsonTypeInfo.Id.NAME,    // Use a logical name as the discriminator
    include  = JsonTypeInfo.As.PROPERTY, // Embed it as a field in the JSON object
    property = "paymentType"             // The JSON key that carries the type name
)
@JsonSubTypes({
    @JsonSubTypes.Type(value = CreditCardPayment.class, name = "credit_card"),
    @JsonSubTypes.Type(value = BankTransferPayment.class, name = "bank_transfer")
})
public abstract class PaymentMethod {
    private Long   paymentId;
    private double amountDue;
    // Getters and setters
}