Mastering @JsonProperty: How to Map Messy API Responses in Spring Boot

By /

Let’s be honest: integrating with third-party APIs is rarely a clean process.

If you have been working in Java for a while, you know the pain. You are building a beautiful, clean Spring Boot application. You have your service layer set up, your architecture is looking solid, and your variable names follow standard camelCase conventions (firstName, accountBalance, creationDate).

Then, you get the documentation for the external API you need to consume.

It looks like a database dump from 1998. The fields are all over the place. You see USER_ID_VAL, f_name, Is_Active_Flag (which returns “Y” or “N” instead of a boolean), and my personal favorite, data_obj_1.

Now you have a dilemma. Do you compromise your code quality and name your Java variables String f_name just to match the JSON? Absolutely not. That is how “spaghetti code” starts.

In this guide, I’m going to walk you through how to use the Jackson library (the default JSON processor in Spring Boot) to map these messy external APIs to clean, readable Java POJOs (Plain Old Java Objects). We will dive into @JsonProperty, handle missing fields, and finally, I’ll show you a workflow that automates the boring part of writing these mappings so you can get back to actual coding.

The Conflict: JSON vs. Java Naming Conventions

Java and JSON often speak different dialects.

In the Java world, we adhere strictly to camelCase. It is baked into the language culture. A variable is userEmailAddress.

In the JSON world, especially with Python or PHP backends, snake_case is king. That same variable comes across the wire as user_email_address.

If you try to map these directly without any configuration, Spring Boot’s ObjectMapper will fail. It looks for a setter method named setUser_email_address(), which doesn’t exist (and shouldn’t exist) in your class.

To bridge this gap, we rely on annotations.

The Hero: @JsonProperty

The @JsonProperty annotation is your primary weapon for decoupling your internal code structure from external data formats. It tells the Jackson mapper: “Hey, when you see this specific key in the JSON, map it to this specific variable in my Java class, regardless of what the variable is named.”

Here is a simple example.

The Messy JSON:

JSON

{
  "emp_id_val": 10234,
  "f_name": "James",
  "is_admin_user": true
}

The Clean Java Class:

import com.fasterxml.jackson.annotation.JsonProperty;

public class EmployeeDTO {
@JsonProperty("emp_id_val")
private Long employeeId;

@JsonProperty("f_name")
private String firstName;

@JsonProperty("is_admin_user")
private boolean isAdmin;

// Getters and Setters...
}

By adding that one annotation, you keep your Java class clean. employeeId is a clear, descriptive name that makes sense to other developers on your team. The ugly emp_id_val key is confined strictly to the annotation layer.

Why not just use a Naming Strategy?

Experienced Spring Boot developers might ask: “Why not just set a global PropertyNamingStrategy in the application.properties file?”

You can do that. Setting spring.jackson.property-naming-strategy=SNAKE_CASE will automatically map first_name to firstName.

However, global strategies are risky for two reasons:

  1. Inconsistency: External APIs are rarely consistent. One endpoint might return user_id (snake_case) while another returns AccountID (PascalCase). A global strategy can’t handle both simultaneously.
  2. Refactoring Safety: If you rely on implicit mapping, changing a variable name in your Java class breaks the API integration. If you use @JsonProperty("user_id"), you can rename your Java variable to whatever you want, and the mapping stays intact. Explicit is almost always better than implicit.

Handling The “Unknowns” with @JsonIgnoreProperties

Another common scenario causes headaches for junior developers. You map the three fields you need, run the application, and get an error: UnrecognizedPropertyException.

This happens because the external API sent a field you didn’t define in your POJO. Maybe they added a new field called debug_trace_id yesterday. By default, Jackson is strict—it expects your Java class to perfectly match the incoming JSON.

To fix this, you should almost always add @JsonIgnoreProperties to the top of your DTOs (Data Transfer Objects).

import com.fasterxml.jackson.annotation.JsonIgnoreProperties;

@JsonIgnoreProperties(ignoreUnknown = true)
public class EmployeeDTO {
    // fields...
}

This tells Spring Boot: “Map the fields I explicitly asked for. If you see anything else in the JSON, just ignore it and don’t throw an exception.” This makes your application much more robust against changes in the external API.

The Real Problem: Boilerplate Fatigue

So far, the theory is simple. But let’s talk about the reality of working in an enterprise environment.

You aren’t usually integrating with an API that has three fields. You are hitting an endpoint that returns a “User Profile” object with 50 to 100 fields. It has nested objects, arrays of addresses, metadata tags, and legacy columns.

Typing out @JsonProperty("...") fifty times is not “software engineering.” It is manual labor.

It usually goes like this:

  1. You copy the JSON response from Postman.
  2. You create a Java file.
  3. You start typing private String....
  4. You tab back to the JSON to check the spelling.
  5. You misspell “addrress” and spend an hour debugging why that field is null.
  6. You generate Getters and Setters.
  7. You realize you forgot the @JsonIgnoreProperties annotation.

This process breaks your flow state. It takes 20 minutes to do something that requires zero actual brainpower. This is exactly why I built the JSON to Java Converter on Toolshref.

Automating the Mapping (The Better Way)

I created the Toolshref JSON to Java Converter specifically to solve this “boilerplate fatigue.” It is designed to take a raw JSON blob and output a production-ready Java class, complete with Jackson annotations.

Here is how you can save yourself hours of typing using the tool.

Step 1: Get Your Data

First, grab a representative JSON response. You usually get this from Swagger documentation or by hitting the endpoint via curl or Postman.

{
  "data": {
    "user_id": "8821",
    "attributes": {
      "first_login": "2024-01-01",
      "pref_lang": "en_US"
    },
    "roles_list": ["ADMIN", "EDITOR"]
  }
}

Step 2: Paste and Convert

Go to the JSON to Java Converter. Paste that JSON into the input box.

You don’t need to configure complex settings. The tool automatically detects that user_id should likely be a String or Integer, and that roles_list is a List<String>.

Step 3: The Result

The tool generates the following code instantly:

import com.fasterxml.jackson.annotation.JsonProperty;
import java.util.List;

public class Root {
    @JsonProperty("data")
    private Data data;

    // Getters and Setters
}

class Data {
    @JsonProperty("user_id")
    private String userId;

    @JsonProperty("attributes")
    private Attributes attributes;

    @JsonProperty("roles_list")
    private List<String> rolesList;
    
    // Getters and Setters
}

class Attributes {
    @JsonProperty("first_login")
    private String firstLogin;

    @JsonProperty("pref_lang")
    private String prefLang;

    // Getters and Setters
}

Notice what happened here:

  1. CamelCase Conversion: It automatically converted user_id to userId and pref_lang to prefLang, keeping your Java code clean.
  2. Annotation Injection: It added the @JsonProperty("original_name") automatically, so the mapping will work perfectly with Spring Boot.
  3. Nested Classes: It detected the nested attributes object and created a separate class for it.

Step 4: Copy and Refine

Now, you just click “Copy,” paste it into your IntelliJ or Eclipse project, and rename the classes if you want (e.g., changing Root to UserApiResponse).

Advanced Tips for Cleaner DTOs

Once you have auto-generated your class using the tool, here are a few advanced tips to make your code even better:

1. Use Lombok

If your project uses Project Lombok (and it should), you can delete all those generated getters and setters. Just add @Data or @Value to the top of the generated class.

Note: I am working on adding a “Lombok Mode” to the Toolshref converter soon!

2. Wrapper Classes

Sometimes APIs wrap their response in a generic envelope, like {"status": "success", "payload": { ... }}. Instead of creating a unique class for every response, create a generic wrapper:

public class ApiResponse<T> {
    @JsonProperty("status")
    private String status;
    
    @JsonProperty("payload")
    private T payload;
}

Then you can use the tool to generate just the inner User object and pass it as the generic type T.

3. Handling Dates

The tool generates dates as Strings by default (e.g., “2024-01-01”) because date formats are notoriously tricky. To handle this in Spring Boot, change the field type to LocalDate and add the @JsonFormat annotation:

@JsonProperty("first_login")
@JsonFormat(pattern = "yyyy-MM-dd")
private LocalDate firstLogin;

Summary

Mapping JSON to Java doesn’t have to be a chore. While understanding @JsonProperty is critical for debugging and handling edge cases, manually typing these annotations for every single field is a waste of your valuable time.

Keep your variable names clean. Use annotations to bridge the gap between snake_case APIs and camelCase Java. And when you are faced with a massive JSON object, don’t type it out by hand.

Head over to the Toolshref JSON to Java Converter, paste your data, and let the tool handle the boilerplate so you can focus on building the features that actually matter.

Happy Coding!

FAQ

Q1: How do I ignore unknown fields when converting JSON to Java? A: If your API response contains fields you don’t need, Jackson will throw an UnrecognizedPropertyException. To fix this, add the @JsonIgnoreProperties(ignoreUnknown = true) annotation to the top of your Java class. This tells the mapper to skip any JSON fields that don’t have a matching Java variable.

Q2: How do I map a JSON field name that has spaces or special characters? A: Java variable names cannot contain spaces or dashes. To map a JSON key like "first-name" or "User ID", use the @JsonProperty annotation. For example:

@JsonProperty("User ID")
private String userId;

Q3: Can I map a JSON Array directly to a Java List? A: Yes. If your JSON has a field like "roles": ["admin", "editor"], you can map it to a List<String> or ArrayList<String>. For arrays of objects, use List<YourClassName>. Our JSON to Java Converter detects these arrays automatically and generates the correct List<> syntax.

Q4: How do I handle Date formats in Jackson (Spring Boot)? A: By default, Jackson may try to convert dates to timestamps (long numbers). To force a specific format like “YYYY-MM-DD”, use the @JsonFormat annotation on your LocalDate or Date field:

@JsonFormat(shape = JsonFormat.Shape.STRING, pattern = "yyyy-MM-dd")
private LocalDate birthDate;

Q5: What is the difference between @JsonProperty and @JsonAlias? A: @JsonProperty is used for both serializing (writing JSON) and deserializing (reading JSON). @JsonAlias is only used during deserialization to accept multiple possible names for a single field (e.g., accepting both “fName” and “first_name” for the same variable)

Leave a Comment

Your email address will not be published. Required fields are marked *

Scroll to Top