Jackson — JSON in Java

What is Jackson, and Why Does Every Java Project Use It?

Jackson is a Java library for processing JSON — converting Java objects to JSON strings (serialisation) and JSON strings back to Java objects (deserialisation). It is not part of the JDK, not part of the Java EE / Jakarta EE spec, and not written by Spring — it is an independent open-source library that became the industry default because it is fast, flexible, and deeply integrated into every major Java framework.

Before Jackson, Java had no standard way to handle JSON. Projects used string concatenation, home-grown parsers, or the Jakarta EE JSON-P/JSON-B APIs (which are correct but verbose and less widely adopted). Jackson solved the problem once and solved it well — its ObjectMapper can convert any Java object to JSON and back with zero configuration for the common case, and precise control when needed.

/*
 * Before Jackson — manual JSON construction (real pre-2010 code):
 *
 *   String json = "{\"name\":\"" + user.getName() + "\","
 *               + "\"email\":\"" + user.getEmail() + "\"}";
 *
 * Problem: escaping, null handling, nested objects, arrays — all manual.
 * No type safety, no refactoring support, wrong JSON on one typo.
 *
 * With Jackson:
 */
ObjectMapper mapper = new ObjectMapper();
String json = mapper.writeValueAsString(user);          // → {"name":"Ana","email":"ana@example.com"}
User parsed = mapper.readValue(json, User.class);       // back to User

ObjectMapper — The Core, and Why You Don't new It Per Request

// ObjectMapper is THREAD-SAFE after configuration — create once, reuse everywhere
@Bean
public ObjectMapper objectMapper() {
    return new ObjectMapper()
        .registerModule(new JavaTimeModule())                         // LocalDate, LocalDateTime, etc.
        .disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS)      // ISO-8601 strings, not epoch longs
        .disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES)   // ignore extra JSON fields
        .enable(MapperFeature.ACCEPT_CASE_INSENSITIVE_PROPERTIES);    // "Name" binds to "name"
}

// Basic operations
ObjectMapper mapper = new ObjectMapper();

// Serialise — object to JSON string
String json        = mapper.writeValueAsString(user);
String prettyJson  = mapper.writerWithDefaultPrettyPrinter().writeValueAsString(user);

// Deserialise — JSON string to object
User user          = mapper.readValue(json, User.class);

// Generic types — List, Map, Page<T> require TypeReference
List<User> users   = mapper.readValue(json, new TypeReference<List<User>>() {});

// Convert between types (e.g. Map → POJO, useful for dynamic structures)
Map<String, Object> map = mapper.convertValue(user, new TypeReference<>() {});
User fromMap       = mapper.convertValue(map, User.class);

Core Annotations

public class UserDto {

    @JsonProperty("full_name")          // serialises as "full_name" in JSON, even though the field is "name"
    private String name;

    @JsonIgnore                          // excluded from both serialisation AND deserialisation
    private String passwordHash;

    @JsonAlias({"mail", "emailAddress"})  // accepts any of these names when deserialising; serialises as "email"
    private String email;

    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "UTC")
    private LocalDateTime createdAt;

    @JsonInclude(JsonInclude.Include.NON_NULL)  // field omitted from JSON when value is null
    private String middleName;

    @JsonAnyGetter                       // serialises a Map's entries as top-level JSON properties
    private Map<String, Object> extra = new HashMap<>();
}

// Class-level annotations
@JsonIgnoreProperties(ignoreUnknown = true)    // class-level equivalent of FAIL_ON_UNKNOWN_PROPERTIES=false
@JsonNaming(PropertyNamingStrategies.SnakeCaseStrategy.class)  // camelCase → snake_case globally for this class
public class ExternalApiResponse {
    private String firstName;   // serialised as "first_name" automatically
    private String lastName;    // serialised as "last_name" automatically
}

Records and Jackson — Java 17+ Idiom

Java records are immutable by construction — no setters, all fields set via the canonical constructor. Jackson supports records natively from jackson-databind 2.12+ (which corresponds to Spring Boot 2.4+ — all Boot 3.x versions qualify).

// Records deserialise via constructor — no default constructor needed, no setters needed
public record UserResponse(
    Long id,
    String name,
    @JsonProperty("email_address") String email,  // annotations on record components work
    @JsonFormat(pattern = "yyyy-MM-dd") LocalDate dob
) {}

mapper.registerModule(new ParameterNamesModule());

Date and Time — The Most Common Production Gotcha

// Without JavaTimeModule: LocalDateTime throws InvalidDefinitionException at runtime
// With JavaTimeModule + WRITE_DATES_AS_TIMESTAMPS disabled: ISO-8601 strings

// Maven dependency (not pulled in by spring-boot-starter-web automatically in all versions)

<!-- pom.xml -->
<dependency>
    <groupId>com.fasterxml.jackson.datatype</groupId>
    <artifactId>jackson-datatype-jsr310</artifactId>
    <!-- version managed by Spring Boot parent -->
</dependency>

// Register the module — or set it in application.properties (Spring Boot)
ObjectMapper mapper = new ObjectMapper()
    .registerModule(new JavaTimeModule())
    .disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS);

# application.properties — the Spring Boot way: no Java config needed
spring.jackson.serialization.write-dates-as-timestamps=false
spring.jackson.time-zone=UTC

Spring Boot Auto-Configuration — What Boot Does by Default

Spring Boot auto-configures a single ObjectMapper bean via JacksonAutoConfiguration. Knowing what it sets by default tells you what you don't need to configure manually — and what to override when the default is wrong for your use case.

# The cleanest way to customise Boot's ObjectMapper: application.properties
# Avoids subclassing or replacing the auto-configured bean entirely
spring.jackson.serialization.write-dates-as-timestamps=false
spring.jackson.deserialization.fail-on-unknown-properties=false
spring.jackson.default-property-inclusion=non_null
spring.jackson.time-zone=UTC
spring.jackson.property-naming-strategy=SNAKE_CASE     # camelCase → snake_case globally

@Bean
public Jackson2ObjectMapperBuilderCustomizer jacksonCustomizer() {
    return builder -> builder
        .modules(new JavaTimeModule())
        .featuresToDisable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS)
        .propertyNamingStrategy(PropertyNamingStrategies.SNAKE_CASE);
}

Custom Serializers and Deserializers

Use custom serializers when Jackson's default output for a type is wrong for your API contract — sensitive data masking, legacy format compatibility, or types Jackson can't handle automatically (e.g. third-party value objects).

// Custom serializer — masks a credit card number to show only last 4 digits
public class MaskedCardSerializer extends JsonSerializer<String> {
    @Override
    public void serialize(String value, JsonGenerator gen, SerializerProvider provider)
            throws IOException {
        if (value != null && value.length() > 4) {
            gen.writeString("****-****-****-" + value.substring(value.length() - 4));
        } else {
            gen.writeString(value);
        }
    }
}

// Attach to a specific field via annotation
public class PaymentDto {
    @JsonSerialize(using = MaskedCardSerializer.class)
    private String cardNumber;
}

// Custom deserializer — parses a non-standard date format from a legacy API
public class LegacyDateDeserializer extends JsonDeserializer<LocalDate> {
    private static final DateTimeFormatter FMT =
        DateTimeFormatter.ofPattern("dd/MM/yyyy");

    @Override
    public LocalDate deserialize(JsonParser p, DeserializationContext ctx)
            throws IOException {
        return LocalDate.parse(p.getText(), FMT);
    }
}

public record LegacyOrderDto(
    Long id,
    @JsonDeserialize(using = LegacyDateDeserializer.class) LocalDate orderDate
) {}

// Register serializers globally on the mapper (instead of per-field annotations)
SimpleModule module = new SimpleModule();
module.addSerializer(String.class, new MaskedCardSerializer());
mapper.registerModule(module);

@JsonView — Different Fields for Different Contexts

@JsonView lets you define named "views" and annotate fields with the views in which they should appear. A public API endpoint and an admin endpoint can return the same object but with different fields — without creating two separate DTOs.

// Define view marker interfaces (no methods needed — they're just type tokens)
public class Views {
    public interface Public {}
    public interface Admin extends Public {}  // Admin extends Public — inherits Public fields
}

public class UserDto {
    @JsonView(Views.Public.class)
    private Long id;

    @JsonView(Views.Public.class)
    private String name;

    @JsonView(Views.Admin.class)  // only visible in Admin view
    private String email;

    @JsonView(Views.Admin.class)  // only visible in Admin view
    private LocalDateTime lastLogin;
}

// In a Spring MVC controller — activate the view per endpoint
@GetMapping("/api/users/{id}")
@JsonView(Views.Public.class)         // returns: {id, name}
public UserDto getPublic(@PathVariable Long id) { ... }

@GetMapping("/admin/users/{id}")
@JsonView(Views.Admin.class)          // returns: {id, name, email, lastLogin}
public UserDto getAdmin(@PathVariable Long id) { ... }

Jackson in Tests

// In @WebMvcTest — ObjectMapper is auto-configured and injectable
@WebMvcTest(UserController.class)
class UserControllerTest {
    @Autowired private MockMvc mockMvc;
    @Autowired private ObjectMapper objectMapper;  // same instance as the app uses

    @Test
    void createUser_serialisesCorrectly() throws Exception {
        var request = new CreateUserRequest("Ana", "ana@example.com", "pass1234");

        mockMvc.perform(post("/api/users")
                .contentType(MediaType.APPLICATION_JSON)
                .content(objectMapper.writeValueAsString(request)))  // use the injected mapper
            .andExpect(status().isCreated());
    }
}

// Pure unit test — no Spring context needed for serialisation logic
class UserDtoSerializationTest {
    private final ObjectMapper mapper = new ObjectMapper()
        .registerModule(new JavaTimeModule())
        .disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS);

    @Test
    void passwordHash_isNeverSerialised() throws Exception {
        var user = new UserDto(1L, "Ana", "$2a$10$abc...");
        String json = mapper.writeValueAsString(user);

        assertThat(json).doesNotContain("passwordHash");
        assertThat(json).doesNotContain("$2a$");  // assert the actual hash value isn't there either
    }

    @Test
    void dates_serialiseAsIso8601() throws Exception {
        var dto = new EventDto(LocalDateTime.of(2024, 1, 15, 10, 30));
        String json = mapper.writeValueAsString(dto);

        assertThat(json).contains("\"2024-01-15T10:30:00\"");  // ISO-8601, not an array or epoch
    }
}

Interview Questions