Set three options first — by your project's reality
Generating Java classes isn't "click and done": three options decide whether the output is directly usable. Set them by your project (using this site's JSON to Java Class Generator as the example):
| Your project | Option | Why |
|---|---|---|
| Uses Jackson (Spring Boot default) | Annotations: Jackson @JsonProperty |
Field-name mapping and deserialization depend on it; the wrong library's annotation = silent all-null |
| Uses Gson | Annotations: Gson @SerializedName |
Same — library and annotation must match |
| Has Lombok | Enable @Data |
Getters/setters/toString/equals vanish; the class body is just fields |
| No Lombok or team bans it | Off; generate explicit getters/setters | Longer code, zero dependencies |
| Fields may be null | Wrapper types (Integer/Boolean) |
Primitives can't hold null; deserialization throws |
| Fields guaranteed present, performance matters | Primitives (int/boolean) |
No boxing, but null detonates |
Fill class name, package, and access modifiers per team convention; nested objects become inner (or standalone) classes, arrays become List<T>.
Type inference rules and four blind spots
The generator infers types only from the sample you give it — know both the rules and the gaps:
| JSON value | Inferred Java type | Blind spot |
|---|---|---|
\"text\" |
String |
— |
true |
Boolean / boolean |
— |
42 |
Integer / int |
13-digit timestamps and snowflake IDs overflow — change to Long |
3.14 |
Double / double |
For money, change to BigDecimal |
null |
Object |
A null sample reveals no real type |
[] |
List<Object> |
Empty array, no element type |
[1, \"a\"] |
List<Object> |
Mixed types degrade |
{...} |
Nested class | — |
Blind spot one: integer overflow. The generator's sneakiest trap — 1730000000000 looks like an ordinary integer in JSON, but as Integer it overflows at deserialization. Rule: any integer past 10 digits becomes Long by hand, ID fields especially (many APIs ship IDs as strings to dodge JavaScript's 2^53 precision limit — then String is the correct inference).
Blind spot two: null and empty arrays. An Object field is the generator saying "I don't know" — regenerate from a complete sample or hand-correct from the API docs. Reviewing every Object field before shipping is the required finishing step.
Blind spot three: mixed-type arrays. [1, \"a\"] can only be List<Object>, which usually signals a design problem in the API itself — take that finding back to the API owner rather than hacking around it in Java.
Blind spot four: field naming. user_name becomes userName with an annotation preserving the original; Java reserved words (class, default) get a suffix — make sure the renamed field still matches the original in its annotation.
Annotations: library and annotation must match
@JsonProperty(\"user_name\") belongs to Jackson, @SerializedName(\"user_name\") to Gson — use the wrong one and deserialization doesn't error; every field is simply null. It's among the costliest classes of bug to track down.
Three practices:
- Pick the annotation for the library you actually use; Spring Boot defaults to Jackson;
- When the whole project speaks snake_case, skip per-field annotations and configure a global naming strategy on the
ObjectMapper(PropertyNamingStrategies.SNAKE_CASE); - Lombok
@Dataand annotations coexist: annotations sit on fields, and Lombok's generated accessors don't interfere with the serializer reading field annotations.
The truth: a generated class is a snapshot, not a contract
- The sample decides everything: the generator infers from the JSON you pasted — fields absent from the sample are unknown, optional fields read as required, null fields become Object. Reconcile against the API docs or several real responses before shipping;
- APIs evolve: when the upstream adds a field, strict deserialization throws UnrecognizedPropertyException — add
@JsonIgnoreProperties(ignoreUnknown = true)to the class or setFAIL_ON_UNKNOWN_PROPERTIES=falseglobally so new fields are ignored instead of breaking the integration; - record is the modern choice: Java 16+ records are immutable and minimal, well suited to pure data transfer; the generator emits traditional mutable POJOs — on Java 17+ with a team that accepts immutability, converting the output to a record is small work; with Lombok,
@Dataalready removes most boilerplate and the practical gap is modest.
The generator's value is driving "typing fields off a JSON" to zero effort; field types and evolution strategy remain your engineering judgment.
Frequently Asked Questions
The JSON uses snake_case but Java fields need camelCase — how do they line up?
Through serialization annotations: the generator renames user_name to userName and adds @JsonProperty("user_name") (Jackson) or @SerializedName("user_name") (Gson), so the library looks up the JSON key by the original name. Two cautions: the annotation must match the library you actually use — mixing yields silent all-null fields; and for project-wide snake_case, configure a global naming strategy on the ObjectMapper instead of annotating every field.
Why did some fields get inferred as Object?
Type inference only sees the sample, and three situations give it nothing: a null value, an empty array, or an array with mixed element types. Object fields are the generator saying "insufficient sample" — regenerate from a complete sample or hand-correct from the API docs. Reviewing every Object field before shipping is the non-negotiable finishing step.
Why is Integer a problem for integer fields?
The generator infers every integer as Integer (or int), but Java's int tops out at 2,147,483,647 — 13-digit millisecond timestamps, snowflake IDs, and large monetary amounts all exceed it and overflow at deserialization. Any JSON integer beyond 10 digits deserves suspicion; timestamp and ID fields should become Long by default. Safer still: BigDecimal for money, Long or String for IDs.
Should I use the generated mutable POJO or a Java record?
record (Java 16+) is an immutable data carrier suited to pure data transfer; the traditional POJO suits incremental population and compatibility with older frameworks. The generator emits traditional POJOs — treat them as a starting point: on Java 17+ with a team that accepts immutability, converting to a record is small work; with Lombok, @Data already removes most boilerplate and the gap is small.